diff --git a/xml/System.Activities.Expressions/IndexerReference`2.xml b/xml/System.Activities.Expressions/IndexerReference`2.xml index c232c9f1135..59bc3b9b617 100644 --- a/xml/System.Activities.Expressions/IndexerReference`2.xml +++ b/xml/System.Activities.Expressions/IndexerReference`2.xml @@ -31,66 +31,66 @@ The type of the indexer array. Represents an element referenced by an object indexer that can be used as an l-value in an expression. - in an `Assign` activity to assign an integer value to the object item at index [1,2] and prints the item value to the console. The `Assign` activity is equivalent to the following statement when using an object that implements an indexer. `myObj[1,2] = 4;` . - + in an `Assign` activity to assign an integer value to the object item at index [1,2] and prints the item value to the console. The `Assign` activity is equivalent to the following statement when using an object that implements an indexer. `myObj[1,2] = 4;` . + > [!NOTE] -> Instead of instantiating the l-value expression activity directly, it is strongly recommended that you call , which provides a higher level of abstraction and enables you to implement your workflow more intuitively. - -```csharp - -// Define a class with a multi-dimensional indexer. -public class ObjectWithIndexer -{ - private int[,] array = new int[10,10]; - public int this[int i, int j] - { - get { return array[i,j]; } - set { array[i,j] = value; } - } -} - -public static void IndexerReferenceSample() -{ - // Create a variable of type ObjectWithIndexer to store the object item. - var oivar = new Variable("oivar", new ObjectWithIndexer()); - - Activity myActivity = new Sequence - { - Variables = { oivar }, - Activities = - { - // Create an Assign activity with a reference for the object at index [1,2]. - new Assign - { - To = new IndexerReference - { - Operand = oivar, - Indices = - { - new InArgument(1), - new InArgument(2) - } - }, - // Assign an integer value to the object at index [1,2]. - Value = 4, - }, - // Print the new item value to the console. - new WriteLine() - { - Text = ExpressionServices.Convert(ctx => oivar.Get(ctx)[1, 2].ToString()), - } - } - }; - - // Invoke the Sequence activity. - WorkflowInvoker.Invoke(myActivity); -} - -``` - +> Instead of instantiating the l-value expression activity directly, it is strongly recommended that you call , which provides a higher level of abstraction and enables you to implement your workflow more intuitively. + +```csharp + +// Define a class with a multi-dimensional indexer. +public class ObjectWithIndexer +{ + private int[,] array = new int[10,10]; + public int this[int i, int j] + { + get { return array[i,j]; } + set { array[i,j] = value; } + } +} + +public static void IndexerReferenceSample() +{ + // Create a variable of type ObjectWithIndexer to store the object item. + var oivar = new Variable("oivar", new ObjectWithIndexer()); + + Activity myActivity = new Sequence + { + Variables = { oivar }, + Activities = + { + // Create an Assign activity with a reference for the object at index [1,2]. + new Assign + { + To = new IndexerReference + { + Operand = oivar, + Indices = + { + new InArgument(1), + new InArgument(2) + } + }, + // Assign an integer value to the object at index [1,2]. + Value = 4, + }, + // Print the new item value to the console. + new WriteLine() + { + Text = ExpressionServices.Convert(ctx => oivar.Get(ctx)[1, 2].ToString()), + } + } + }; + + // Invoke the Sequence activity. + WorkflowInvoker.Invoke(myActivity); +} + +``` + ]]> @@ -196,11 +196,11 @@ public static void IndexerReferenceSample() Gets a collection of arguments that represent the indices of the element in the indexer array. The indices of the element in the indexer array. - property is read-only, but the items in the collection can be modified and the indices can be changed. - + property is read-only, but the items in the collection can be modified and the indices can be changed. + ]]> diff --git a/xml/System.Activities.Expressions/MultidimensionalArrayItemReference`1.xml b/xml/System.Activities.Expressions/MultidimensionalArrayItemReference`1.xml index f436f74c495..295a216a2cc 100644 --- a/xml/System.Activities.Expressions/MultidimensionalArrayItemReference`1.xml +++ b/xml/System.Activities.Expressions/MultidimensionalArrayItemReference`1.xml @@ -29,51 +29,51 @@ The type of elements in the array. Represents an element in a multidimensional array that can be used as an l-value in an expression. - in an `Assign` activity to assign an integer value to the array element at row 1 and column 2 and prints the value of the array element to the console. The `Assign` activity is equivalent to the following statement when using arrays: `array[1, 2] = 1;`. - + in an `Assign` activity to assign an integer value to the array element at row 1 and column 2 and prints the value of the array element to the console. The `Assign` activity is equivalent to the following statement when using arrays: `array[1, 2] = 1;`. + > [!NOTE] -> Instead of instantiating the l-value expression activity directly, it is strongly recommended that you call , which provides a higher level of abstraction and enables you to implement your workflow more intuitively. - -```csharp - -public static void MultidimensionalArrayItemReferenceSample() -{ - // Create a variable to store a multidimensional array. - var arrayvar = new Variable("arrayvar", new int[4, 5]); - - Activity myActivity = new Sequence - { - Variables = { arrayvar }, - Activities = - { - // Create an Assign activity to assign a value to the array item at index [1,2]. - new Assign - { - To = new MultidimensionalArrayItemReference - { - Array = arrayvar, - Indices = {1, 2} - }, - // Assign an integer value to the array item at row 1 column 2. - Value = 1, - }, - // Print the array item value to the console. - new WriteLine() - { - Text = ExpressionServices.Convert(ctx => arrayvar.Get(ctx)[1, 2].ToString()), - } - } - }; - - // Invoke the Sequence activity. - WorkflowInvoker.Invoke(myActivity); -} - -``` - +> Instead of instantiating the l-value expression activity directly, it is strongly recommended that you call , which provides a higher level of abstraction and enables you to implement your workflow more intuitively. + +```csharp + +public static void MultidimensionalArrayItemReferenceSample() +{ + // Create a variable to store a multidimensional array. + var arrayvar = new Variable("arrayvar", new int[4, 5]); + + Activity myActivity = new Sequence + { + Variables = { arrayvar }, + Activities = + { + // Create an Assign activity to assign a value to the array item at index [1,2]. + new Assign + { + To = new MultidimensionalArrayItemReference + { + Array = arrayvar, + Indices = {1, 2} + }, + // Assign an integer value to the array item at row 1 column 2. + Value = 1, + }, + // Print the array item value to the console. + new WriteLine() + { + Text = ExpressionServices.Convert(ctx => arrayvar.Get(ctx)[1, 2].ToString()), + } + } + }; + + // Invoke the Sequence activity. + WorkflowInvoker.Invoke(myActivity); +} + +``` + ]]> @@ -214,11 +214,11 @@ public static void MultidimensionalArrayItemReferenceSample() Gets a collection of arguments that represent the indices of the element in the array. The indices of the element in the array. - property is read-only, but the items in the collection can be modified and the indices can be changed. - + property is read-only, but the items in the collection can be modified and the indices can be changed. + ]]> diff --git a/xml/System.Activities.Expressions/PropertyReference`2.xml b/xml/System.Activities.Expressions/PropertyReference`2.xml index a2e9dccf875..c469dd77c95 100644 --- a/xml/System.Activities.Expressions/PropertyReference`2.xml +++ b/xml/System.Activities.Expressions/PropertyReference`2.xml @@ -25,11 +25,11 @@ The type of the result. A reference to a property. - unless that activity is compatible with its property. - + unless that activity is compatible with its property. + ]]> diff --git a/xml/System.Activities.Expressions/ValueTypeIndexerReference`2.xml b/xml/System.Activities.Expressions/ValueTypeIndexerReference`2.xml index 18696df405e..a6ee7b34b48 100644 --- a/xml/System.Activities.Expressions/ValueTypeIndexerReference`2.xml +++ b/xml/System.Activities.Expressions/ValueTypeIndexerReference`2.xml @@ -31,62 +31,62 @@ The type of indexer array. Represents an element referenced by an indexer on a value type that can be used as an l-value in an expression. - in an `Assign` activity to assign a `string` value to the `struct` element at index 1 and prints the element value to the console. The `Assign` activity is equivalent to the following statement when using the `struct` defined in the following example: `myStructVariable[1] = "Hello";`. - + in an `Assign` activity to assign a `string` value to the `struct` element at index 1 and prints the element value to the console. The `Assign` activity is equivalent to the following statement when using the `struct` defined in the following example: `myStructVariable[1] = "Hello";`. + > [!NOTE] -> Instead of instantiating the l-value expression activity directly, it is strongly recommended that you call , which provides a higher level of abstraction and enables you to implement your workflow more intuitively. - -```csharp - - // Define a struct with an indexer. - struct StructWithIndexer - { - string val; - public string this[int index] - { - get { return val; } - set { val = value; } - } - } - - public static void ValueTypeIndexerReferenceSample() - { - // Create a variable of type StructWithIndexer to store the element. - var swivar = new Variable("swivar", new StructWithIndexer()); - - // Create the top-level activity to be invoked later. - Activity myActivity = new Sequence - { - Variables = { swivar }, - Activities = - { - // Create an Assign activity with an element at index 1. - new Assign - { - To = new ValueTypeIndexerReference - { - OperandLocation = swivar, - Indices = { new InArgument(1) }, - }, - // Assign a string literal to the element at index 1. - Value = "Hello", - }, - new WriteLine() - { - Text = ExpressionServices.Convert(ctx => swivar.Get(ctx)[1]), - } - } - }; - - // Invoke the Sequence activity. - WorkflowInvoker.Invoke(myActivity); -} - -``` - +> Instead of instantiating the l-value expression activity directly, it is strongly recommended that you call , which provides a higher level of abstraction and enables you to implement your workflow more intuitively. + +```csharp + + // Define a struct with an indexer. + struct StructWithIndexer + { + string val; + public string this[int index] + { + get { return val; } + set { val = value; } + } + } + + public static void ValueTypeIndexerReferenceSample() + { + // Create a variable of type StructWithIndexer to store the element. + var swivar = new Variable("swivar", new StructWithIndexer()); + + // Create the top-level activity to be invoked later. + Activity myActivity = new Sequence + { + Variables = { swivar }, + Activities = + { + // Create an Assign activity with an element at index 1. + new Assign + { + To = new ValueTypeIndexerReference + { + OperandLocation = swivar, + Indices = { new InArgument(1) }, + }, + // Assign a string literal to the element at index 1. + Value = "Hello", + }, + new WriteLine() + { + Text = ExpressionServices.Convert(ctx => swivar.Get(ctx)[1]), + } + } + }; + + // Invoke the Sequence activity. + WorkflowInvoker.Invoke(myActivity); +} + +``` + ]]> @@ -192,11 +192,11 @@ Gets a collection of arguments that represent the indices of the element in the indexer array. The indices of the element in the indexer array. - property is read-only, but the items in the collection can be modified and the indices can be changed. - + property is read-only, but the items in the collection can be modified and the indices can be changed. + ]]> diff --git a/xml/System.Activities.Expressions/VariableReference`1.xml b/xml/System.Activities.Expressions/VariableReference`1.xml index 3008de277f3..429bb516aac 100644 --- a/xml/System.Activities.Expressions/VariableReference`1.xml +++ b/xml/System.Activities.Expressions/VariableReference`1.xml @@ -174,11 +174,11 @@ Returns a representation of the . The variable reference. - property has been set then the string representation consists of the variable's name; otherwise, it consists of the activity ID and name. - + property has been set then the string representation consists of the variable's name; otherwise, it consists of the activity ID and name. + ]]> diff --git a/xml/System.Activities.Expressions/VariableValue`1.xml b/xml/System.Activities.Expressions/VariableValue`1.xml index 329a1f9a88a..e6b439216c0 100644 --- a/xml/System.Activities.Expressions/VariableValue`1.xml +++ b/xml/System.Activities.Expressions/VariableValue`1.xml @@ -174,11 +174,11 @@ Returns a representation of the . The value of the variable. - property has been set then the string representation consists of the variable's name; otherwise, it consists of the activity ID and name. - + property has been set then the string representation consists of the variable's name; otherwise, it consists of the activity ID and name. + ]]> diff --git a/xml/System.Activities.Hosting/WorkflowInstance.xml b/xml/System.Activities.Hosting/WorkflowInstance.xml index 23d17979380..1b7337adf65 100644 --- a/xml/System.Activities.Hosting/WorkflowInstance.xml +++ b/xml/System.Activities.Hosting/WorkflowInstance.xml @@ -29,11 +29,11 @@ - An exception in the workflow was uncaught and escaped the root. The host will be notified through the method. -- The scheduler has run out of work items and is now . The host will be notified through the method. Note that the scheduler could have run out of work items because the instance is idle or because the instance is complete. The value of the property can be used to differentiate between the two. +- The scheduler has run out of work items and is now . The host will be notified through the method. Note that the scheduler could have run out of work items because the instance is idle or because the instance is complete. The value of the property can be used to differentiate between the two. - The host can request a change from Running to Paused by calling the or methods of the instance returned by the property. This request should not be considered to have a specific response meaning that the host should not attempt to correlate an OnNotify* or with a specific call to pause. In response to a pause request, the runtime may transition to Paused and call while the scheduler still has pending work items. The value of the property can be used to determine whether the scheduler has no more work or was interrupted by a request to pause. + The host can request a change from Running to Paused by calling the or methods of the instance returned by the property. This request should not be considered to have a specific response meaning that the host should not attempt to correlate an OnNotify* or with a specific call to pause. In response to a pause request, the runtime may transition to Paused and call while the scheduler still has pending work items. The value of the property can be used to determine whether the scheduler has no more work or was interrupted by a request to pause. - The method of the instance returned by the property is the only method that can be called while the is in the Running state. All other methods will throw an if called.Given the rules for how transitions from one state to another, the public notion of Running and Paused can be defined as follows: + The method of the instance returned by the property is the only method that can be called while the is in the Running state. All other methods will throw an if called.Given the rules for how transitions from one state to another, the public notion of Running and Paused can be defined as follows: - Running - The state between a call to and the next WorkflowInstance.OnNotify*. diff --git a/xml/System.Activities.Presentation.Model/ModelItem.xml b/xml/System.Activities.Presentation.Model/ModelItem.xml index 938ccbdf8e1..e597ae5abe6 100644 --- a/xml/System.Activities.Presentation.Model/ModelItem.xml +++ b/xml/System.Activities.Presentation.Model/ModelItem.xml @@ -373,7 +373,7 @@ Assert.AreEqual(root.Properties["Residence"], location.Source, "sources point to on an item. If the of this item declares a `RuntimeNamePropertyAttribute`, the property is a direct mapping to the property dictated by that attribute. + Not all items need to have names, so this might return `null`. Depending on the type of item and where it sits in the hierarchy, it might not always be legal to set the on an item. If the of this item declares a `RuntimeNamePropertyAttribute`, the property is a direct mapping to the property dictated by that attribute. ]]> diff --git a/xml/System.Activities.Presentation.Model/ModelItemCollection.xml b/xml/System.Activities.Presentation.Model/ModelItemCollection.xml index 31d20cc49fb..a63f88c88fd 100644 --- a/xml/System.Activities.Presentation.Model/ModelItemCollection.xml +++ b/xml/System.Activities.Presentation.Model/ModelItemCollection.xml @@ -45,11 +45,11 @@ Represents a collection of model items that can be individually accessed by index. - property will not be updated until the editing scope completes. - + property will not be updated until the editing scope completes. + ]]> @@ -136,11 +136,11 @@ Adds a model item to the end of the . Returns wrapped in a . - . - + . + ]]> @@ -316,11 +316,11 @@ Returns the count of items in the collection. The count of items in the collection. - session. If an object is added to the during a session, the value will not be updated until the session exits. - + session. If an object is added to the during a session, the value will not be updated until the session exits. + ]]> @@ -469,11 +469,11 @@ if the collection is a fixed size; otherwise, . - @@ -571,11 +571,11 @@ Identifies the Item dependency property. - . The Item property points to the itself. - + . The Item property points to the itself. + ]]> @@ -1196,11 +1196,11 @@ This member is an explicit interface member implementation. It can be used only The to remove from the . Removes the first occurrence of a specific object from the . - , the remains unchanged and no exception is thrown. - + , the remains unchanged and no exception is thrown. + ]]> diff --git a/xml/System.Activities.Presentation.PropertyEditing/DialogPropertyValueEditor.xml b/xml/System.Activities.Presentation.PropertyEditing/DialogPropertyValueEditor.xml index 76f4e9e23d7..66a2199c30e 100644 --- a/xml/System.Activities.Presentation.PropertyEditing/DialogPropertyValueEditor.xml +++ b/xml/System.Activities.Presentation.PropertyEditing/DialogPropertyValueEditor.xml @@ -29,9 +29,9 @@ The following list shows the rules for determining whether the or method is used. - If the property is not a null reference (Nothing in Visual Basic), that is hosted in a host-specific dialog box, which provides host styling. The is not called. + If the property is not a null reference (Nothing in Visual Basic), that is hosted in a host-specific dialog box, which provides host styling. The is not called. - If the property is a null reference (Nothing in Visual Basic), the virtual method is called and you can override this method to show any dialog box. + If the property is a null reference (Nothing in Visual Basic), the virtual method is called and you can override this method to show any dialog box. ]]> diff --git a/xml/System.Activities.Presentation.PropertyEditing/ExtendedPropertyValueEditor.xml b/xml/System.Activities.Presentation.PropertyEditing/ExtendedPropertyValueEditor.xml index 1d46916731f..87c577a18f2 100644 --- a/xml/System.Activities.Presentation.PropertyEditing/ExtendedPropertyValueEditor.xml +++ b/xml/System.Activities.Presentation.PropertyEditing/ExtendedPropertyValueEditor.xml @@ -16,15 +16,15 @@ Container for all extended editor logic for properties. - class can hold two objects, one for an inline editor and one for an extended editor. The inline editor provides a custom interface that appears within the bounds of the `Properties` window, and the extended editor provides an interface that appears in a new window. - - The property returns the XAML template for the visual interface for the inline editor, and the property returns the XAML template for the extended editor. These are typically provided in a ResourceDictionary elsewhere in the project. - - You should use the to invoke your custom . - + class can hold two objects, one for an inline editor and one for an extended editor. The inline editor provides a custom interface that appears within the bounds of the `Properties` window, and the extended editor provides an interface that appears in a new window. + + The property returns the XAML template for the visual interface for the inline editor, and the property returns the XAML template for the extended editor. These are typically provided in a ResourceDictionary elsewhere in the project. + + You should use the to invoke your custom . + ]]> @@ -88,11 +88,11 @@ The used for the inline editor. Creates a new instance of with the specified extended and inline editor objects. - is set to a . - + is set to a . + ]]> @@ -126,11 +126,11 @@ Gets or sets the used for the extended pop-up or pinned editor. The object used for the extended pop-up or pinned editor. - is set to a . - + is set to a . + ]]> diff --git a/xml/System.Activities.Presentation.Toolbox/ToolboxCategory.xml b/xml/System.Activities.Presentation.Toolbox/ToolboxCategory.xml index 651fa4bc9ac..275c6177dad 100644 --- a/xml/System.Activities.Presentation.Toolbox/ToolboxCategory.xml +++ b/xml/System.Activities.Presentation.Toolbox/ToolboxCategory.xml @@ -29,13 +29,13 @@ A collection of toolbox items that have been categorized. - collection contains items of type that are added and removed from an instance of the collection using the and methods. - - The class implements the interface. This allows the collection that is storing the toolbox items to provide notifications when properties like the property are changed and methods like and are used to change the contents of the collection. - + collection contains items of type that are added and removed from an instance of the collection using the and methods. + + The class implements the interface. This allows the collection that is storing the toolbox items to provide notifications when properties like the property are changed and methods like and are used to change the contents of the collection. + ]]> @@ -64,11 +64,11 @@ Creates an instance of the class. - collection is an empty `string`. - + collection is an empty `string`. + ]]> @@ -92,11 +92,11 @@ The name of the toolbox category collection. Creates an instance of the class with a specified name. - collection can be an empty `string`. This is the value assigned by the parameterless constructor, . - + collection can be an empty `string`. This is the value assigned by the parameterless constructor, . + ]]> @@ -151,11 +151,11 @@ Gets or sets the name of the toolbox category. The name of the toolbox category. - @@ -264,11 +264,11 @@ The index of the array at which the copying begins. Copies the entire collection to a compatible one-dimensional , starting at the specified index of the target . - in the same order in which the enumerator iterates through the collection. - + in the same order in which the enumerator iterates through the collection. + ]]> The is . @@ -296,11 +296,11 @@ Gets the number of tools contained in the . The number of elements contained in the . - implements the interface. - + implements the interface. + ]]> @@ -328,11 +328,11 @@ if access to the is synchronized (thread safe); otherwise, . - implements the interface. The property returns an object, which can be used to synchronize access to the . - + implements the interface. The property returns an object, which can be used to synchronize access to the . + ]]> @@ -359,11 +359,11 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - implements the interface. - + implements the interface. + ]]> @@ -391,15 +391,15 @@ Returns an enumerator that iterates through the collection. An for the . - is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is no longer valid 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. - + is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is no longer valid 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. + ]]> @@ -430,11 +430,11 @@ Adds a tool to the . The zero-based index of the tool added to the collection. - implements the interface. - + implements the interface. + ]]> The is of a type that is not assignable to the implemented by the collection. @@ -462,11 +462,11 @@ Removes all the tools from the . - implements the interface. - + implements the interface. + ]]> @@ -498,11 +498,11 @@ if the is found in the ; otherwise, . - implements the interface. - + implements the interface. + ]]> The is . @@ -534,11 +534,11 @@ Determines the index of a specific tool in the . The zero-based index of if found in the ; otherwise, -1. - implements the interface. - + implements the interface. + ]]> The is . @@ -571,15 +571,15 @@ The tool added to the collection. Inserts a tool into the at the specified index. - implements the interface. - - If `index` equals the number of items in the , then `value` is appended to the end. - - In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. - + implements the interface. + + If `index` equals the number of items in the , then `value` is appended to the end. + + In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. + ]]> The is not valid for the collection. @@ -610,11 +610,11 @@ if the has a fixed size; otherwise, . - implements the interface. - + implements the interface. + ]]> @@ -642,11 +642,11 @@ if the is read-only; otherwise, . - implements the interface. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - + implements the interface. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + ]]> @@ -677,11 +677,11 @@ Gets or sets the tool at the specified index. The tool at the specified index. - implements the interface. This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - + implements the interface. This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. + ]]> @@ -711,13 +711,13 @@ The tool to remove from the . Removes the first occurrence of a specific tool from the . - implements the interface. - - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. - + implements the interface. + + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. + ]]> @@ -747,13 +747,13 @@ The zero-based index of the tool item to remove. Removes the tool at the specified index of the collection. - implements the interface. - - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. - + implements the interface. + + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. + ]]> The is not valid for the collection. diff --git a/xml/System.Activities.Presentation.Toolbox/ToolboxCategoryItems.xml b/xml/System.Activities.Presentation.Toolbox/ToolboxCategoryItems.xml index 24abca56957..a31125f7fc3 100644 --- a/xml/System.Activities.Presentation.Toolbox/ToolboxCategoryItems.xml +++ b/xml/System.Activities.Presentation.Toolbox/ToolboxCategoryItems.xml @@ -444,7 +444,7 @@ implements the interface. The property returns an object, which can be used to synchronize access to the . + implements the interface. The property returns an object, which can be used to synchronize access to the . ]]> diff --git a/xml/System.Activities.Presentation.Toolbox/ToolboxControl.xml b/xml/System.Activities.Presentation.Toolbox/ToolboxControl.xml index 337d7125f65..f6c8095b6cf 100644 --- a/xml/System.Activities.Presentation.Toolbox/ToolboxControl.xml +++ b/xml/System.Activities.Presentation.Toolbox/ToolboxControl.xml @@ -30,14 +30,14 @@ Provides functions to render a collection of categorized tools, as well as notify users about tool selection and creation events. This class is , so it cannot be inherited. - . The contains a collection of toolbox categories that hold various categories of tools that can be accessed with the property. It also is able to retrieve the with which it is associated using the property. - + . The contains a collection of toolbox categories that hold various categories of tools that can be accessed with the property. It also is able to retrieve the with which it is associated using the property. + > [!WARNING] -> For activities to load properly in the toolbox, the assembly that contains the activities must be loaded first. Use to load the activity type if it is contained in a different assembly; using instead will cause an exception to be thrown. - +> For activities to load properly in the toolbox, the assembly that contains the activities must be loaded first. Use to load the activity type if it is contained in a different assembly; using instead will cause an exception to be thrown. + ]]> @@ -119,11 +119,11 @@ Gets or sets the collection of toolbox categories associated with this control. The that contains the collection of objects associated with this . - will be cleared. - + will be cleared. + ]]> @@ -229,11 +229,11 @@ Builds the visual tree for this toolbox control. - method is invoked by the method. implements , which, in turn, implements . - + method is invoked by the method. implements , which, in turn, implements . + ]]> diff --git a/xml/System.Activities.Presentation.Toolbox/ToolboxItemWrapper.xml b/xml/System.Activities.Presentation.Toolbox/ToolboxItemWrapper.xml index f56e452c911..95ba4035fe8 100644 --- a/xml/System.Activities.Presentation.Toolbox/ToolboxItemWrapper.xml +++ b/xml/System.Activities.Presentation.Toolbox/ToolboxItemWrapper.xml @@ -20,11 +20,11 @@ Represents a wrapper used to establish link between an actual instance and the tool representation, as well as add support for categorization of toolbox items. This class is , so it cannot be inherited. - @@ -53,11 +53,11 @@ Initializes a new instance of the class. - , , , and properties with an empty `string`. - + , , , and properties with an empty `string`. + ]]> @@ -81,11 +81,11 @@ The type of the tool. Initializes a new instance of the class with the type of the tool. - and properties can be extracted from the `toolType` parameter. The and properties are each initialized with an empty `string`. - + and properties can be extracted from the `toolType` parameter. The and properties are each initialized with an empty `string`. + ]]> @@ -111,11 +111,11 @@ The name of the display. Initializes a new instance of the class with the type of the tool and a specified display name. - and properties can be extracted from the `toolType` parameter. The property is initialized with an empty `string`. - + and properties can be extracted from the `toolType` parameter. The property is initialized with an empty `string`. + ]]> @@ -143,11 +143,11 @@ A that contains the name of the display. Initializes a new instance of the class with the type of the tool and specified names for the bitmap and display. - and properties can be extracted from the `toolType` parameter. - + and properties can be extracted from the `toolType` parameter. + ]]> @@ -204,11 +204,11 @@ Gets or sets the assembly name for the toolbox item. The assembly name. - The assembly name has already been specified and cannot be changed after the corresponding has been initialized. @@ -260,11 +260,11 @@ Gets or sets the bitmap name. The bitmap name. - @@ -288,11 +288,11 @@ Gets or sets the display name. The display name. - @@ -317,11 +317,11 @@ if the is valid; otherwise, . - is valid if it is not `null`. - + is valid if it is not `null`. + ]]> @@ -348,11 +348,11 @@ An event that occurs when a property is changed. - property is defined by the interface that is implemented by the class. - + property is defined by the interface that is implemented by the class. + ]]> @@ -382,11 +382,11 @@ Gets or sets the name of the tool. The tool name. - The name of the tool cannot be changed after the corresponding has been initialized. diff --git a/xml/System.Activities.Presentation/ActivityDesigner.xml b/xml/System.Activities.Presentation/ActivityDesigner.xml index 87df0ff6556..b55cd542db7 100644 --- a/xml/System.Activities.Presentation/ActivityDesigner.xml +++ b/xml/System.Activities.Presentation/ActivityDesigner.xml @@ -21,7 +21,7 @@ ## Remarks This type provides the basic look-and-feel functionality for other activity designers and allows a developer to add additional capabilities to an activity designer surface. This is typically done in order to either display additional interesting information to the user of the activity, create a better on canvas editing experience (for example, using the `ExpressionTextBox` on an `If` activity designer), or to allow contained elements to be edited (again, consider the and properties of the activity). - The inherits from and primarily adds the default styling, as well as the ability to customize the icon via the property. It should be used whenever you are creating a designer for a type that derives from . When associated with an type, the property will point to the ModelItem hierarchy describing the instance of that type being edited. + The inherits from and primarily adds the default styling, as well as the ability to customize the icon via the property. It should be used whenever you are creating a designer for a type that derives from . When associated with an type, the property will point to the ModelItem hierarchy describing the instance of that type being edited. ## Examples In the sample code below, a `First2of3` activity is defined first, then the code for the First2of3 designer is shown, and finally it is shown how to use the Designer attribute to associate the activity with the designer is provided. diff --git a/xml/System.Activities.Presentation/ActivityDesignerOptionsAttribute.xml b/xml/System.Activities.Presentation/ActivityDesignerOptionsAttribute.xml index 411662d0054..7970c3cf724 100644 --- a/xml/System.Activities.Presentation/ActivityDesignerOptionsAttribute.xml +++ b/xml/System.Activities.Presentation/ActivityDesignerOptionsAttribute.xml @@ -22,11 +22,11 @@ Specifies drill-down and node viewing mode for an , such as Flowcharts, that are used to compose activities. - property to `false`. Child nodes are not always collapsed by default, but can be set to always collapse by setting the property to `true`. - + property to `false`. Child nodes are not always collapsed by default, but can be set to always collapse by setting the property to `true`. + ]]> @@ -46,11 +46,11 @@ Creates an instance of the class. - property and `false` for the property. - + property and `false` for the property. + ]]> diff --git a/xml/System.Activities.Presentation/ClipboardData.xml b/xml/System.Activities.Presentation/ClipboardData.xml index ef5ad4c649d..88d1aae9e28 100644 --- a/xml/System.Activities.Presentation/ClipboardData.xml +++ b/xml/System.Activities.Presentation/ClipboardData.xml @@ -27,11 +27,11 @@ ## Remarks The contains three types of data: -- The data itself, accessed through the property. +- The data itself, accessed through the property. -- The metadata, accessed through the property. +- The metadata, accessed through the property. -- The version information, accessed through the property. +- The version information, accessed through the property. ]]> diff --git a/xml/System.Activities.Presentation/ContextItem.xml b/xml/System.Activities.Presentation/ContextItem.xml index 69a84b159fe..e77a10c1d2d 100644 --- a/xml/System.Activities.Presentation/ContextItem.xml +++ b/xml/System.Activities.Presentation/ContextItem.xml @@ -19,7 +19,7 @@ , which is part of the employed by a when representing the workflow model visually. The is returned by the property which contains the data that is shared between a host and the designer. This data provides the mechanism needed to hook into subscription and change notification. + A context item represents a piece of transient state in a designer. Context items are managed by a , which is part of the employed by a when representing the workflow model visually. The is returned by the property which contains the data that is shared between a host and the designer. This data provides the mechanism needed to hook into subscription and change notification. ]]> diff --git a/xml/System.Activities.Presentation/ServiceManager.xml b/xml/System.Activities.Presentation/ServiceManager.xml index 74954f45e43..05908bafc2a 100644 --- a/xml/System.Activities.Presentation/ServiceManager.xml +++ b/xml/System.Activities.Presentation/ServiceManager.xml @@ -29,7 +29,7 @@ represent functionality that is either provided by the host for the designer to use or that is used by the designer to make functionality available to all designers within the editor. It is obtained from the by the property. + represent functionality that is either provided by the host for the designer to use or that is used by the designer to make functionality available to all designers within the editor. It is obtained from the by the property. ]]> diff --git a/xml/System.Activities.Presentation/WorkflowItemPresenter.xml b/xml/System.Activities.Presentation/WorkflowItemPresenter.xml index fbe372bffc0..2ea6a491931 100644 --- a/xml/System.Activities.Presentation/WorkflowItemPresenter.xml +++ b/xml/System.Activities.Presentation/WorkflowItemPresenter.xml @@ -20,34 +20,34 @@ Provides a visual editor to edit objects, and provides an area for the user to drag and drop, and otherwise edit composed elements. - property. The is one of two controls (the other being ) that can be used to create a container for visualizing and editing a composed element. It is important to note that the visualization of the composed element is not controlled by the but it renders with the visualization associated in the metadata store for a given type. The is a specialized subclass of the WPF that has been modified to support drag and drop, copy and paste, and other visual editing actions. - - - -## Examples - The primary use of this control will be in an activity designer, as seen in the sample code below. The XAML below shows the declarative usage of the control to build a simple designer for the If activity. The If activity has two properties of type Activity, Then and Else, and the Item for each WorkflowItemPresenter is linked to that respective property. - - For an example of the in use, see the [Custom Composite Designers - Workflow Item Presenter](/dotnet/framework/windows-workflow-foundation/samples/custom-composite-designers-workflow-item-presenter) sample. - -```xaml - - - - - - - - - -``` - + property. The is one of two controls (the other being ) that can be used to create a container for visualizing and editing a composed element. It is important to note that the visualization of the composed element is not controlled by the but it renders with the visualization associated in the metadata store for a given type. The is a specialized subclass of the WPF that has been modified to support drag and drop, copy and paste, and other visual editing actions. + + + +## Examples + The primary use of this control will be in an activity designer, as seen in the sample code below. The XAML below shows the declarative usage of the control to build a simple designer for the If activity. The If activity has two properties of type Activity, Then and Else, and the Item for each WorkflowItemPresenter is linked to that respective property. + + For an example of the in use, see the [Custom Composite Designers - Workflow Item Presenter](/dotnet/framework/windows-workflow-foundation/samples/custom-composite-designers-workflow-item-presenter) sample. + +```xaml + + + + + + + + + +``` + ]]> @@ -88,11 +88,11 @@ Gets or sets the . A that contains the allowed item. - disallows dropping objects that do not conform to the `Type`. - + disallows dropping objects that do not conform to the `Type`. + ]]> diff --git a/xml/System.Activities.Presentation/WorkflowItemsPresenter.xml b/xml/System.Activities.Presentation/WorkflowItemsPresenter.xml index ac3bf599369..2f3411fec79 100644 --- a/xml/System.Activities.Presentation/WorkflowItemsPresenter.xml +++ b/xml/System.Activities.Presentation/WorkflowItemsPresenter.xml @@ -28,46 +28,46 @@ Represents a control that can be used to present a collection of objects on a design surface. - is the second key Windows Presentation Foundation (WPF) control provided by the Windows Workflow Foundation designer infrastructure that is collection-based. While the enables the display and the editing of a single contained element, the is collection-based, displays a visualization, and supports editing of the collection of items provided by the property. In addition to allowing the multiple items contained in the collection to be visualized and edited, the `WorkflowItemsPresenter` also enables collection-oriented actions, such as inserting an item at a given index in the collection, deleting an item from the collection, and moving an item from one index to another. `WorkflowItemsPresenter` also handles combined actions, such as dragging between the various presenters and allowing that edit to occur in a single, undoable action.Use to present a single object on a design surface. - - For an example of the in use, see the [Custom Composite Designers - Workflow Items Presenter](/dotnet/framework/windows-workflow-foundation/samples/custom-composite-designers-workflow-items-presenter) sample. - - - -## Examples - The following sample code shows how you can build a designer for the Parallel activity. Note the binding to ModelItem.Branches for the Items. - -```xaml - - - - - - - - - - - - - - - - - - - - -``` - + is the second key Windows Presentation Foundation (WPF) control provided by the Windows Workflow Foundation designer infrastructure that is collection-based. While the enables the display and the editing of a single contained element, the is collection-based, displays a visualization, and supports editing of the collection of items provided by the property. In addition to allowing the multiple items contained in the collection to be visualized and edited, the `WorkflowItemsPresenter` also enables collection-oriented actions, such as inserting an item at a given index in the collection, deleting an item from the collection, and moving an item from one index to another. `WorkflowItemsPresenter` also handles combined actions, such as dragging between the various presenters and allowing that edit to occur in a single, undoable action.Use to present a single object on a design surface. + + For an example of the in use, see the [Custom Composite Designers - Workflow Items Presenter](/dotnet/framework/windows-workflow-foundation/samples/custom-composite-designers-workflow-items-presenter) sample. + + + +## Examples + The following sample code shows how you can build a designer for the Parallel activity. Note the binding to ModelItem.Branches for the Items. + +```xaml + + + + + + + + + + + + + + + + + + + + +``` + ]]> @@ -445,26 +445,26 @@ Identifies the dependency property. - is based on a vertically oriented `StackPanel`. As an illustration, the `ItemsPanel` for the designer of activities is based on a horizontally oriented `StackPanel`. - - - -## Examples - The following example in XAML shows the `ItemsPanel` for the designer of activities that is based on a horizontally oriented `StackPanel`. - -```xaml - - - - - - - -``` - + is based on a vertically oriented `StackPanel`. As an illustration, the `ItemsPanel` for the designer of activities is based on a horizontally oriented `StackPanel`. + + + +## Examples + The following example in XAML shows the `ItemsPanel` for the designer of activities that is based on a horizontally oriented `StackPanel`. + +```xaml + + + + + + + +``` + ]]> @@ -632,11 +632,11 @@ The that was moved. Informs the that a was moved. - , it is removed. - + , it is removed. + ]]> diff --git a/xml/System.Activities.Presentation/WorkflowViewElement.xml b/xml/System.Activities.Presentation/WorkflowViewElement.xml index ecb5943d334..0aa67a5ae58 100644 --- a/xml/System.Activities.Presentation/WorkflowViewElement.xml +++ b/xml/System.Activities.Presentation/WorkflowViewElement.xml @@ -20,20 +20,20 @@ Specifies the base class for any UI element that appears on the Windows Workflow Foundation designer canvas and that visually represents an instance of an atomic item that can be edited. - include and . `WorkflowViewElement` provides a common contract that the designer uses to render the visual element onto the designer surface and to interact with it through the various editing actions. - - If you are building a designer for an , you should use the base type. If there are non-activity elements that need to be treated as first class items on the designer canvas, such as a toolbox item that needs to be draggable throughout the canvas, or for cut-and-paste scenarios, use `WorkflowViewElement` as the base class. If you do not want to use the standard activity chrome for an activity designer, `WorkflowViewElement` should be used as the base type to provide the most flexibility. - - A represents a in the UI and provides code access to the model item and an that allows changes to be made. - - - -## Examples - For a code sample showing how to create a new and an , and then how to associate them, see the sample in the documentation. - + include and . `WorkflowViewElement` provides a common contract that the designer uses to render the visual element onto the designer surface and to interact with it through the various editing actions. + + If you are building a designer for an , you should use the base type. If there are non-activity elements that need to be treated as first class items on the designer canvas, such as a toolbox item that needs to be draggable throughout the canvas, or for cut-and-paste scenarios, use `WorkflowViewElement` as the base class. If you do not want to use the standard activity chrome for an activity designer, `WorkflowViewElement` should be used as the base type to provide the most flexibility. + + A represents a in the UI and provides code access to the model item and an that allows changes to be made. + + + +## Examples + For a code sample showing how to create a new and an , and then how to associate them, see the sample in the documentation. + ]]> @@ -53,11 +53,11 @@ Initializes a new instance of the class. - property is set to `false` by default. - + property is set to `false` by default. + ]]> @@ -140,11 +140,11 @@ Gets or sets the editing context that is shared by all elements contained in a workflow designer. The object for the workflow designer that contains the workflow view element. - object is a collection of services shared between all elements contained in the designer and used to interact between the host and the designer. Services are published and requested through the . - + object is a collection of services shared between all elements contained in the designer and used to interact between the host and the designer. Services are published and requested through the . + ]]> @@ -300,11 +300,11 @@ When implemented in a derived class, retrieves the automation help text. The default implementation is to return an empty . - @@ -329,11 +329,11 @@ When implemented in a derived class, gets the name of a property of the model item associated with the element that is used as automation ID. The name to use as automation ID. The base class always returns . - @@ -423,11 +423,11 @@ Gets or sets the underlying object associated with the workflow view element. A object that is a wrapper around a model instance or an in-memory representation of the underlying workflow. - object provides notification of changes even if the model instance does not provide change notification. - + object provides notification of changes even if the model instance does not provide change notification. + ]]> @@ -613,11 +613,11 @@ The that contains the event data. Raises the event. - @@ -644,11 +644,11 @@ An that represents the changed state of the model item. Invoked when the underlying model item is changed. Implement this method in a derived class to handle this event. - @@ -820,11 +820,11 @@ to indicate that the element is read-only; otherwise, . Invoked when the read-only property is changed. - @@ -852,11 +852,11 @@ to indicate that the value of the show expanded property is changed; otherwise, . Invoked when the show expanded property is changed. - @@ -1072,11 +1072,11 @@ Gets the associated with the workflow view element. The view service associated with the workflow view element. - property. - + property. + ]]> diff --git a/xml/System.Activities.Statements/FlowDecision.xml b/xml/System.Activities.Statements/FlowDecision.xml index 1f5a82cdb7c..fe3dc1ad073 100644 --- a/xml/System.Activities.Statements/FlowDecision.xml +++ b/xml/System.Activities.Statements/FlowDecision.xml @@ -16,18 +16,18 @@ A specialized that provides the ability to model a conditional node with two outcomes. - uses a condition and defines actions to take if the condition is `true` or `false`. - - - -## Examples - The following code sample demonstrates creating a node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: - + uses a condition and defines actions to take if the condition is `true` or `false`. + + + +## Examples + The following code sample demonstrates creating a node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: + ]]> @@ -40,13 +40,13 @@ Creates a new instance of the class. - node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: - + node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: + ]]> @@ -72,13 +72,13 @@ Creates a new instance of the class. - node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: - + node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: + ]]> @@ -102,13 +102,13 @@ The condition the is testing. Creates a new instance of the class with the specified condition. - node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: - + node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: + ]]> @@ -132,13 +132,13 @@ The condition the is testing. Creates a new instance of the class with the specified condition. - node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: - + node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: + ]]> @@ -176,18 +176,18 @@ Specifies the condition the is testing. A value expression that represents the condition. - in the property is executed. Otherwise the in the property is executed. - - - -## Examples - The following code sample demonstrates using the Condition property of a node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: - + in the property is executed. Otherwise the in the property is executed. + + + +## Examples + The following code sample demonstrates using the Condition property of a node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: + ]]> @@ -256,13 +256,13 @@ Gets or sets the that is executed when the condition evaluates to . The activity that is executed when the condition evaluates to . - node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: - + node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: + ]]> @@ -304,13 +304,13 @@ Gets or sets the that is executed when the condition evaluates to . The activity to execute when the condition evaluates to . - node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: - + node. This example is from the [Fault Handling in a Flowchart Activity Using TryCatch](/dotnet/framework/windows-workflow-foundation/samples/fault-handling-in-a-flowchart-activity-using-trycatch) sample. + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_flowchartwithfaulthandling/cs/program.cs" id="Snippet3"::: + ]]> diff --git a/xml/System.Activities.Statements/Parallel.xml b/xml/System.Activities.Statements/Parallel.xml index 07fdc35cfac..4e517cf163d 100644 --- a/xml/System.Activities.Statements/Parallel.xml +++ b/xml/System.Activities.Statements/Parallel.xml @@ -22,19 +22,19 @@ An activity that executes all child activities simultaneously and asynchronously. - activity operates by simultaneously scheduling each in its collection at the start. It completes when all of its complete or when its property evaluates to `true`. While all the objects run asynchronously, they do not execute on separate threads, so each successive activity only executes when the previously scheduled activity completes or goes idle. If none of the child activities of this activity go idle, this activity execute in the same way that a activity does. - - - + activity operates by simultaneously scheduling each in its collection at the start. It completes when all of its complete or when its property evaluates to `true`. While all the objects run asynchronously, they do not execute on separate threads, so each successive activity only executes when the previously scheduled activity completes or goes idle. If none of the child activities of this activity go idle, this activity execute in the same way that a activity does. + + + ## Examples The following code sample demonstrates creating a activity. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_compensationcancellation/cs/program.cs" id="Snippet1"::: - + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_compensationcancellation/cs/program.cs" id="Snippet1"::: + ]]> @@ -60,14 +60,14 @@ The following code sample demonstrates creating a Creates a new instance of the activity. - activity. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_compensationcancellation/cs/program.cs" id="Snippet1"::: - + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_compensationcancellation/cs/program.cs" id="Snippet1"::: + ]]> @@ -97,14 +97,14 @@ The following code sample demonstrates creating a The child elements to be executed in parallel. The elements. - activity. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_compensationcancellation/cs/program.cs" id="Snippet1"::: - + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_compensationcancellation/cs/program.cs" id="Snippet1"::: + ]]> @@ -194,17 +194,17 @@ The following code sample demonstrates setting the Branches property of a Evaluates after any branch completes. The completion expression. - collection are canceled. If this property is not set, all objects in the collection execute until completion. ## Examples The following code sample demonstrates setting the CompletionCondition property of a activity. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_compensationcancellation/cs/program.cs" id="Snippet1"::: - + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_compensationcancellation/cs/program.cs" id="Snippet1"::: + ]]> diff --git a/xml/System.Activities.Statements/Switch`1.xml b/xml/System.Activities.Statements/Switch`1.xml index 26e838ce9d4..ceadfbab4fa 100644 --- a/xml/System.Activities.Statements/Switch`1.xml +++ b/xml/System.Activities.Statements/Switch`1.xml @@ -26,17 +26,17 @@ The type of the values provided in the collection. Selects one choice from a number of activities to execute, based on the value of a given expression of the type specified in this object's type specifier. - dictionary consists of a value (serving as the key for the dictionary) and an activity (serving as the value for the dictionary). The is evaluated and compared against the keys in the dictionary. If a match is found, the corresponding activity is executed. Every key in the dictionary must be unique according to the dictionary's equality comparer. ## Examples The following code sample demonstrates creating a activity. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_procedurals/cs/program.cs" id="Snippet1"::: - + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_procedurals/cs/program.cs" id="Snippet1"::: + ]]> @@ -49,14 +49,14 @@ The following code sample demonstrates creating a Creates a new instance of the class. - activity. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_procedurals/cs/program.cs" id="Snippet1"::: - + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_procedurals/cs/program.cs" id="Snippet1"::: + ]]> @@ -82,14 +82,14 @@ The following code sample demonstrates creating a Creates a new instance of the class. - activity. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_procedurals/cs/program.cs" id="Snippet1"::: - + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_procedurals/cs/program.cs" id="Snippet1"::: + ]]> @@ -200,17 +200,17 @@ The following code sample demonstrates creating a Represents the dictionary of potential execution paths. Each entry contains a key and an activity that is executed when the result of the expression matches the key. The execution paths. - property. + property. ## Examples The following code sample demonstrates setting the Cases property of a activity. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_procedurals/cs/program.cs" id="Snippet1"::: - + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_procedurals/cs/program.cs" id="Snippet1"::: + ]]> @@ -311,17 +311,17 @@ The following code sample demonstrates setting the Cases property of a Gets the object to compare to the keys in the collection. The object to compare to the keys in the collection. - activity. - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_procedurals/cs/program.cs" id="Snippet1"::: - + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/wfs_procedurals/cs/program.cs" id="Snippet1"::: + ]]> diff --git a/xml/System.Activities.Statements/TerminateWorkflow.xml b/xml/System.Activities.Statements/TerminateWorkflow.xml index b1370a8f429..f308e9081d5 100644 --- a/xml/System.Activities.Statements/TerminateWorkflow.xml +++ b/xml/System.Activities.Statements/TerminateWorkflow.xml @@ -98,11 +98,11 @@ Gets or sets the exception that provoked the instance termination. The exception. - is a if only is set. If only is set, that exception is passed to . If both and are set, a is passed with the specified , and is set as the exception's property. If neither is set, a default is created. - + is a if only is set. If only is set, that exception is passed to . If both and are set, a is passed with the specified , and is set as the exception's property. If neither is set, a default is created. + ]]> @@ -164,11 +164,11 @@ A string input argument with the reason for the workflow instance termination. The reason for workflow termination. - is a if only is set. If only is set, that exception is passed to . If both and are set, a is passed with the specified , and is set as the exception's property. If neither is set, a default is created. - + is a if only is set. If only is set, that exception is passed to . If both and are set, a is passed with the specified , and is set as the exception's property. If neither is set, a default is created. + ]]> diff --git a/xml/System.Activities/WorkflowInvoker.xml b/xml/System.Activities/WorkflowInvoker.xml index fe42f81ac6a..c2f2ab7afa9 100644 --- a/xml/System.Activities/WorkflowInvoker.xml +++ b/xml/System.Activities/WorkflowInvoker.xml @@ -309,7 +309,7 @@ ## Remarks Only a workflow invoked by one of the overloads that takes a `userState` parameter can be canceled. - If the cancellation succeeds, the property of the passed to the handler is set to `true`; otherwise, it is set to `false`. + If the cancellation succeeds, the property of the passed to the handler is set to `true`; otherwise, it is set to `false`. diff --git a/xml/System.AddIn.Contract.Automation/IRemoteMethodInfoContract.xml b/xml/System.AddIn.Contract.Automation/IRemoteMethodInfoContract.xml index a569f665348..a09a9608e05 100644 --- a/xml/System.AddIn.Contract.Automation/IRemoteMethodInfoContract.xml +++ b/xml/System.AddIn.Contract.Automation/IRemoteMethodInfoContract.xml @@ -18,13 +18,13 @@ Defines a contract that components can use to access information about a method across application domain and process boundaries. - represents a method of a remote object that implements the interface. - - To access one or more methods of a remote object, use the method to get an that represents the type of the remote object. Then, call the or method. - + represents a method of a remote object that implements the interface. + + To access one or more methods of a remote object, use the method to get an that represents the type of the remote object. Then, call the or method. + ]]> @@ -50,11 +50,11 @@ Returns information about the method that this identifies. A that provides information about the method that this identifies. - structure includes the types of the method's return value and parameters. - + structure includes the types of the method's return value and parameters. + ]]> @@ -89,11 +89,11 @@ Invokes the method that this identifies. A that specifies the return value of the invoked method. - returns a default in which the property is set to the value and the property is set to the value . - + returns a default in which the property is set to the value and the property is set to the value . + ]]> diff --git a/xml/System.AddIn.Contract.Automation/RemoteTypeData.xml b/xml/System.AddIn.Contract.Automation/RemoteTypeData.xml index 0794fd6bf88..936e0c86bc3 100644 --- a/xml/System.AddIn.Contract.Automation/RemoteTypeData.xml +++ b/xml/System.AddIn.Contract.Automation/RemoteTypeData.xml @@ -23,11 +23,11 @@ Provides information about a type that components can access across application domain and process boundaries. - structure provides information about an object that implements the interface. To get type information about a remote object, components call the method to obtain an . Then, components call the method to get a . - + structure provides information about an object that implements the interface. To get type information about a remote object, components call the method to obtain an . Then, components call the method to get a . + ]]> @@ -51,11 +51,11 @@ Indicates the rank (that is, the number of dimensions) of the remote array type that this describes. - describes an array, use the field. - + describes an array, use the field. + ]]> @@ -100,11 +100,11 @@ Represents the name of the remote type that this describes, qualified by the name of the assembly that contains the type. - property. - + property. + ]]> @@ -128,11 +128,11 @@ Represents the attributes of the remote type that this describes. - if this describes the type of a COM object. - + if this describes the type of a COM object. + ]]> @@ -177,11 +177,11 @@ Represents the type of the elements in the remote array type that this describes. - describes an array, use the field. - + describes an array, use the field. + ]]> @@ -205,11 +205,11 @@ Represents the name of the remote type that this describes, qualified by the namespace. - @@ -233,11 +233,11 @@ Indicates whether this describes an array type. - describes an array type; otherwise, the value of this field is `false`. - + describes an array type; otherwise, the value of this field is `false`. + ]]> @@ -261,11 +261,11 @@ Indicates whether this describes a type that is passed by reference. - describes a type that is passed by reference; otherwise, the value of this field is `false`. - + describes a type that is passed by reference; otherwise, the value of this field is `false`. + ]]> @@ -310,11 +310,11 @@ Represents the type of the remote type that this describes. - , the value of this field is . - + , the value of this field is . + ]]> diff --git a/xml/System.AddIn.Contract/IServiceProviderContract.xml b/xml/System.AddIn.Contract/IServiceProviderContract.xml index 56b818557e7..d65978d5862 100644 --- a/xml/System.AddIn.Contract/IServiceProviderContract.xml +++ b/xml/System.AddIn.Contract/IServiceProviderContract.xml @@ -18,11 +18,11 @@ Defines a mechanism for retrieving a service contract from a component. - interface defines a contract that enables a component to obtain a custom service that is defined by another component. A component that implements is known as a service provider. Service providers implement the method to return an that implements a service. - + interface defines a contract that enables a component to obtain a custom service that is defined by another component. A component that implements is known as a service provider. Service providers implement the method to return an that implements a service. + ]]> @@ -53,11 +53,11 @@ Returns a service contract that is implemented by this . An that represents a service contract that a client is requesting from the ; if the does not implement the requested contract. - implementation. It is recommended that implementations identify a service contract by the property of the type that implements the service contract. - + implementation. It is recommended that implementations identify a service contract by the property of the type that implements the service contract. + ]]> diff --git a/xml/System.AddIn.Contract/RemoteArgument.xml b/xml/System.AddIn.Contract/RemoteArgument.xml index 502cd0a7c7b..f143cedfac3 100644 --- a/xml/System.AddIn.Contract/RemoteArgument.xml +++ b/xml/System.AddIn.Contract/RemoteArgument.xml @@ -38,11 +38,11 @@ - Arrays that contain elements of intrinsic data types. - An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . + An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . provides constructors for each of the types that it supports. You can also use the methods to create objects. The methods automatically call the appropriate constructor for your argument type. - If you create a using the default parameterless constructor, the property is set to the value and the property is set to the value . + If you create a using the default parameterless constructor, the property is set to the value and the property is set to the value . ]]> @@ -80,7 +80,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -109,7 +109,7 @@ property to , the property to the type code of the array element type, and the property to `false`. + This constructor sets the property to , the property to the type code of the array element type, and the property to `false`. ]]> @@ -141,7 +141,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -170,7 +170,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -199,7 +199,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -228,7 +228,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -257,7 +257,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -286,7 +286,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -315,7 +315,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -344,7 +344,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -373,7 +373,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -402,7 +402,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -437,7 +437,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -466,7 +466,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -495,7 +495,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -530,7 +530,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -565,7 +565,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -600,7 +600,7 @@ property to , the property to , and the property to `false`. + This constructor sets the property to , the property to , and the property to `false`. ]]> @@ -632,7 +632,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -671,7 +671,7 @@ ## Remarks This constructor assigns the default value of the data type specified by the `typeCode` parameter to the . - An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . + An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . ]]> @@ -713,7 +713,7 @@ property to , the property to the type code of the array element type, and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to the type code of the array element type, and the property to the value of the `isByRef` parameter. ]]> @@ -748,7 +748,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -780,7 +780,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -812,7 +812,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -844,7 +844,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -876,7 +876,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -908,7 +908,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -940,7 +940,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -972,7 +972,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1004,7 +1004,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1036,7 +1036,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1074,7 +1074,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1106,7 +1106,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1138,7 +1138,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1176,7 +1176,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1214,7 +1214,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1252,7 +1252,7 @@ property to , the property to , and the property to the value of the `isByRef` parameter. + This constructor sets the property to , the property to , and the property to the value of the `isByRef` parameter. ]]> @@ -1288,7 +1288,7 @@ ## Remarks This constructor assigns the default value of the data type specified by the `typeCode` parameter to the . - An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . + An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . ]]> @@ -1609,7 +1609,7 @@ ## Remarks This method calls the constructor that applies to the type of the `value` parameter. - You cannot use this method to create a that represents a `null` array that contains elements of intrinsic data types. An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . + You cannot use this method to create a that represents a `null` array that contains elements of intrinsic data types. An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . ]]> @@ -1937,7 +1937,7 @@ property of the type is `true`) or a , , , or . + An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . ]]> diff --git a/xml/System.AddIn.Contract/RemoteArgumentKind.xml b/xml/System.AddIn.Contract/RemoteArgumentKind.xml index 8474e6b0b3d..d403d7ee15e 100644 --- a/xml/System.AddIn.Contract/RemoteArgumentKind.xml +++ b/xml/System.AddIn.Contract/RemoteArgumentKind.xml @@ -16,13 +16,13 @@ Specifies the kind of argument that a represents. - enumeration is used by the property. - - An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . - + enumeration is used by the property. + + An intrinsic data type is a primitive data type (that is, the property of the type is `true`) or a , , , or . + ]]> diff --git a/xml/System.AddIn.Hosting/AddInController.xml b/xml/System.AddIn.Hosting/AddInController.xml index e1721807b0c..4dd34d4ca19 100644 --- a/xml/System.AddIn.Hosting/AddInController.xml +++ b/xml/System.AddIn.Hosting/AddInController.xml @@ -22,11 +22,11 @@ ## Remarks Use this class to perform the following tasks: -- Use the property to obtain an object for an add-in. Then use that object to activate other add-ins in the same application domain and process as the original add-in. +- Use the property to obtain an object for an add-in. Then use that object to activate other add-ins in the same application domain and process as the original add-in. -- Use the property to obtain an object for an add-in. Then use that object to activate other add-ins in the same application domain as the original add-in. Note that because of limitations in cross-process remoting, this scenario will not work with add-ins that are activated in a separate process. +- Use the property to obtain an object for an add-in. Then use that object to activate other add-ins in the same application domain as the original add-in. Note that because of limitations in cross-process remoting, this scenario will not work with add-ins that are activated in a separate process. -- Use the property to obtain an object that represents an add-in. +- Use the property to obtain an object that represents an add-in. - Shut down an add-in with the method. diff --git a/xml/System.AddIn.Hosting/AddInEnvironment.xml b/xml/System.AddIn.Hosting/AddInEnvironment.xml index 610695c2095..ebd02a44cc1 100644 --- a/xml/System.AddIn.Hosting/AddInEnvironment.xml +++ b/xml/System.AddIn.Hosting/AddInEnvironment.xml @@ -28,13 +28,13 @@ - An existing external process. - To obtain the object for an add-in, pass the add-in's application domain to the class constructor. Alternatively, you can use the property of the class to obtain the add-in's object. + To obtain the object for an add-in, pass the add-in's application domain to the class constructor. Alternatively, you can use the property of the class to obtain the add-in's object. After you obtain the object, you can do the following: - Pass that object to the appropriate method overload. The add-in will be activated in the application domain and process that is represented by the object. -- Use the property to obtain an object. Then pass that object to the appropriate method overload. The add-in will be activated in the process that is represented by the object but in a new application domain. +- Use the property to obtain an object. Then pass that object to the appropriate method overload. The add-in will be activated in the process that is represented by the object but in a new application domain. ]]> @@ -64,7 +64,7 @@ object. Otherwise, you can use the property of the class to obtain the object. + If you have access to the application domain that contains the add-in you need, you can use this constructor to obtain the add-in's object. Otherwise, you can use the property of the class to obtain the object. ]]> diff --git a/xml/System.AddIn.Hosting/AddInProcess.xml b/xml/System.AddIn.Hosting/AddInProcess.xml index b5d4e69d366..025b7e6aae1 100644 --- a/xml/System.AddIn.Hosting/AddInProcess.xml +++ b/xml/System.AddIn.Hosting/AddInProcess.xml @@ -154,12 +154,12 @@ If the value of this property is `true`, the add-in is running in-process with the host application. In that case, using the or method throws an . > [!NOTE] -> The property returns an object that represents the host application process if the add-in is running in-process. +> The property returns an object that represents the host application process if the add-in is running in-process. ## Examples - The following example activates an add-in in an external process and uses the property to determine whether the add-in is in the same process as the host application process. + The following example activates an add-in in an external process and uses the property to determine whether the add-in is in the same process as the host application process. :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.AddIn.Hosting/AddInController/Overview/p3host.vb" id="Snippet10"::: diff --git a/xml/System.AddIn.Hosting/AddInSegmentDirectoryNotFoundException.xml b/xml/System.AddIn.Hosting/AddInSegmentDirectoryNotFoundException.xml index 0b7807ec50b..38abed73806 100644 --- a/xml/System.AddIn.Hosting/AddInSegmentDirectoryNotFoundException.xml +++ b/xml/System.AddIn.Hosting/AddInSegmentDirectoryNotFoundException.xml @@ -23,11 +23,11 @@ The exception that is thrown when a segment directory is missing from the pipeline directory structure. - @@ -63,18 +63,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error (for example, "The target application domain has been unloaded."). This message takes the current system culture into account. - - The following table shows the initial property values for an instance of the class. - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error (for example, "The target application domain has been unloaded."). This message takes the current system culture into account. + + The following table shows the initial property values for an instance of the class. + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -105,16 +105,16 @@ A message that describes the error. Initializes a new instance of the class with a specified message. - class. - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + class. + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -147,18 +147,18 @@ The contextual information about the source or destination object data. Initializes a new instance of the class with serialization data. - class. - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The localized error message string.| - + class. + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The localized error message string.| + ]]> @@ -191,18 +191,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference, the current exception is raised in a catch 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 to the constructor, or a null reference 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 the class. - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The localized error message string.| - + property. The property returns the same value that is passed to the constructor, or a null reference 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 the class. + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The localized error message string.| + ]]> diff --git a/xml/System.AddIn.Hosting/AddInSegmentType.xml b/xml/System.AddIn.Hosting/AddInSegmentType.xml index 72df054fab1..cd7479c772d 100644 --- a/xml/System.AddIn.Hosting/AddInSegmentType.xml +++ b/xml/System.AddIn.Hosting/AddInSegmentType.xml @@ -16,19 +16,19 @@ Specifies the type of a pipeline segment. - attribute, you can obtain the data specified in the attribute with the property of an object. - - - -## Examples - The following example uses the enumeration to evaluate an add-in's qualification data. - + attribute, you can obtain the data specified in the attribute with the property of an object. + + + +## Examples + The following example uses the enumeration to evaluate an add-in's qualification data. + :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.AddIn.Hosting/AddInController/Overview/p3host.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/System.AddIn.Hosting/AddInController/Overview/p3host.vb" id="Snippet11"::: + ]]> diff --git a/xml/System.AddIn.Hosting/AddInStore.xml b/xml/System.AddIn.Hosting/AddInStore.xml index 16f808a1413..499de996f5a 100644 --- a/xml/System.AddIn.Hosting/AddInStore.xml +++ b/xml/System.AddIn.Hosting/AddInStore.xml @@ -86,7 +86,7 @@ collection. If multiple pipelines to the specified add-in are found, you can differentiate them by examining the property. + If a single pipeline for an add-in is found, it will be the only item in the collection. If multiple pipelines to the specified add-in are found, you can differentiate them by examining the property. ## Examples The following example finds a specific add-in. diff --git a/xml/System.AddIn.Hosting/AddInToken.xml b/xml/System.AddIn.Hosting/AddInToken.xml index cc768658e06..a2310b3afd8 100644 --- a/xml/System.AddIn.Hosting/AddInToken.xml +++ b/xml/System.AddIn.Hosting/AddInToken.xml @@ -417,7 +417,7 @@ property. This value is always available on an instance of an object. + This property obtains the full name of the add-in as it would be returned by the property. This value is always available on an instance of an object. @@ -454,7 +454,7 @@ property. This value is always available on an instance of an object. + This property obtains the display name of the assembly that contains the add-in, as it would be returned by the property. This value is always available on an instance of an object. @@ -614,9 +614,9 @@ Use the enumerator returned by this method to iterate through the qualification data items of the pipeline segments associated with the current token. Each item of qualification data is a structure that identifies the pipeline segment and contains a name/value pair from a attribute applied to that segment. > [!NOTE] -> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . +> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . - Alternatively, you can use the property to get a nested set of dictionaries that contain the qualification data of the pipeline segments. + Alternatively, you can use the property to get a nested set of dictionaries that contain the qualification data of the pipeline segments. ## Examples The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. @@ -807,9 +807,9 @@ Use the enumerator returned by this method to iterate through the qualification data items of the pipeline segments associated with the current token. Each item of qualification data is a structure that identifies the pipeline segment and contains the name/value pair from a attribute applied to that segment. > [!NOTE] -> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . +> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . - Alternatively, you can use the property to get a nested set of dictionaries containing the qualification data of the pipeline segments. + Alternatively, you can use the property to get a nested set of dictionaries containing the qualification data of the pipeline segments. ]]> diff --git a/xml/System.AddIn.Hosting/InvalidPipelineStoreException.xml b/xml/System.AddIn.Hosting/InvalidPipelineStoreException.xml index ada121fd213..9a5fb8ead43 100644 --- a/xml/System.AddIn.Hosting/InvalidPipelineStoreException.xml +++ b/xml/System.AddIn.Hosting/InvalidPipelineStoreException.xml @@ -23,13 +23,13 @@ The exception that is thrown when a directory is not found and the user does not have permission to access the pipeline root path or an add-in path. - , this exception does not provide any path information. This prevents a malicious user from deliberately specifying erroneous paths and using the information returned by the exception to determine actual paths. - - This exception is thrown by the following discovery methods that build and update the store of add-in and pipeline information: ,, , , and . - + , this exception does not provide any path information. This prevents a malicious user from deliberately specifying erroneous paths and using the information returned by the exception to determine actual paths. + + This exception is thrown by the following discovery methods that build and update the store of add-in and pipeline information: ,, , , and . + ]]> @@ -117,11 +117,11 @@ The contextual information about the source or destination object data. Initializes a new instance of the class with serialization and streaming context information. - @@ -154,18 +154,18 @@ The exception that is the cause of the current exception. If the parameter is not a null reference, the current exception is raised in a catch block that handles the inner exception. Initializes a new instance of the class with the specified 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 to the constructor, or a null reference 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 the class. - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The localized error message string.| - + property. The property returns the same value that is passed to the constructor, or a null reference 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 the class. + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The localized error message string.| + ]]> diff --git a/xml/System.AddIn.Hosting/QualificationDataItem.xml b/xml/System.AddIn.Hosting/QualificationDataItem.xml index 44537f86226..d821c9181c3 100644 --- a/xml/System.AddIn.Hosting/QualificationDataItem.xml +++ b/xml/System.AddIn.Hosting/QualificationDataItem.xml @@ -28,7 +28,7 @@ ## Remarks Each item of qualification data consists of a name/value pair that was applied to a pipeline segment by using the attribute, to provide information that qualifies the use of the segment (for example, the recommended isolation level for the segment). The structure contains one name/value pair and the type of pipeline segment it was applied to. - Use the property to get a nested set of dictionaries that contains structures for the pipeline segments associated with an . + Use the property to get a nested set of dictionaries that contains structures for the pipeline segments associated with an . Alternatively, use the method to get an enumerator for the structures of the pipeline segments associated with a token, or simply use a `foreach` statement (`For Each` in Visual Basic) to treat the token as if it were a collection of structures. @@ -121,12 +121,12 @@ attribute, to provide information to consumers of the add-in. The property gets the name. Use the property to get the value. + Each item of qualification data consists of a name/value pair that was applied to a pipeline segment by using the attribute, to provide information to consumers of the add-in. The property gets the name. Use the property to get the value. ## Examples - The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the name of each item. + The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the name of each item. :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.AddIn.Hosting/AddInController/Overview/p3host.vb" id="Snippet12"::: @@ -225,12 +225,12 @@ When you enumerate qualification data, use this property to identify the qualification data that belongs to a particular segment of the pipeline. > [!NOTE] -> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . +> The add-in model does not use qualification data that is applied to the host view of the add-in. As a result, when you enumerate qualification data you will not find any items whose property is . ## Examples - The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the kind of segment. + The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the kind of segment. :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.AddIn.Hosting/AddInController/Overview/p3host.vb" id="Snippet12"::: @@ -268,12 +268,12 @@ attribute, to provide information to consumers of the add-in. The property gets the value. Use the property to get the name. + Each item of qualification data consists of a name/value pair that was applied to a pipeline segment by using the attribute, to provide information to consumers of the add-in. The property gets the value. Use the property to get the name. ## Examples - The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the value of the item. + The following example lists the qualification data for the pipeline segments associated with each in a collection of tokens. The property is used to display the value of the item. :::code language="csharp" source="~/snippets/csharp/System.AddIn.Hosting/AddInController/Overview/P3Host.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.AddIn.Hosting/AddInController/Overview/p3host.vb" id="Snippet12"::: diff --git a/xml/System.AddIn.Pipeline/QualificationDataAttribute.xml b/xml/System.AddIn.Pipeline/QualificationDataAttribute.xml index 3711a0b9b24..3e8f5694c77 100644 --- a/xml/System.AddIn.Pipeline/QualificationDataAttribute.xml +++ b/xml/System.AddIn.Pipeline/QualificationDataAttribute.xml @@ -23,25 +23,25 @@ Provides developer-specified data for a pipeline segment. - and methods, which maintain the store of information about available pipeline segments, use this attribute to identify a segment that has qualification data. - - To access the qualification data for a pipeline segment, see the property. To enumerate the data for all the pipeline segments, see the class. - - Qualification data is only read by the host and is not consumed by the add-in system in any other way. - + and methods, which maintain the store of information about available pipeline segments, use this attribute to identify a segment that has qualification data. + + To access the qualification data for a pipeline segment, see the property. To enumerate the data for all the pipeline segments, see the class. + + Qualification data is only read by the host and is not consumed by the add-in system in any other way. + You can apply qualification data to a pipeline segment by placing a attribute next to the segment attribute. -## Examples - The following example applies qualification data to an add-in. - +## Examples + The following example applies qualification data to an add-in. + :::code language="csharp" source="~/snippets/csharp/System.AddIn/AddInAttribute/Overview/addincalcv2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.AddIn/AddInAttribute/Overview/AddInCalcV2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.AddIn/AddInAttribute/Overview/AddInCalcV2.vb" id="Snippet2"::: + ]]> @@ -74,11 +74,11 @@ Any value. Initializes a new instance of the class. - diff --git a/xml/System.CodeDom.Compiler/CodeGeneratorOptions.xml b/xml/System.CodeDom.Compiler/CodeGeneratorOptions.xml index 41817a8b830..34923ee21dd 100644 --- a/xml/System.CodeDom.Compiler/CodeGeneratorOptions.xml +++ b/xml/System.CodeDom.Compiler/CodeGeneratorOptions.xml @@ -39,7 +39,7 @@ ## Remarks is passed to the code generation methods of an implementation to specify options used during code generation. - The property specifies the string to use for each spacing indentation. The property specifies the placement style for braces indicating the boundaries of code blocks. The property specifies whether to append an `else`, `catch`, or `finally` block, including brackets, at the closing line of each `if` or `try` block. The property specifies whether to insert blank lines between members. + The property specifies the string to use for each spacing indentation. The property specifies the placement style for braces indicating the boundaries of code blocks. The property specifies whether to append an `else`, `catch`, or `finally` block, including brackets, at the closing line of each `if` or `try` block. The property specifies whether to insert blank lines between members. An implementation can provide custom code generation options which you can set or pass data to using the dictionary indexer, which a code generator can search through to locate additional code generation options. @@ -331,7 +331,7 @@ property to inject #region blocks into code, thus changing the order. + The default generates members by their type, for example; field, member, constructor, or property. A code generator can use the property to inject #region blocks into code, thus changing the order. ]]> diff --git a/xml/System.CodeDom.Compiler/CompilerError.xml b/xml/System.CodeDom.Compiler/CompilerError.xml index 7c151752bae..19476a9db2c 100644 --- a/xml/System.CodeDom.Compiler/CompilerError.xml +++ b/xml/System.CodeDom.Compiler/CompilerError.xml @@ -197,7 +197,7 @@ property can be set to zero for compilers that do not return column information. + The property can be set to zero for compilers that do not return column information. ]]> @@ -249,7 +249,7 @@ property can contain a string of any length. + The property can contain a string of any length. ]]> @@ -301,7 +301,7 @@ property can be a string of any length. + The property can be a string of any length. ]]> diff --git a/xml/System.CodeDom.Compiler/CompilerInfo.xml b/xml/System.CodeDom.Compiler/CompilerInfo.xml index a2732c97732..da51f974c31 100644 --- a/xml/System.CodeDom.Compiler/CompilerInfo.xml +++ b/xml/System.CodeDom.Compiler/CompilerInfo.xml @@ -99,7 +99,7 @@ implementation on the computer. The property value is a instance that represents a configured language provider implementation. + The machine configuration file contains the fully qualified type name for each implementation on the computer. The property value is a instance that represents a configured language provider implementation. @@ -167,7 +167,7 @@ The [<system.codedom> Element](/dotnet/framework/configure-apps/file-schema/compiler/system-codedom-element) in the machine configuration file contains the language provider and compiler configuration settings for each implementation on the computer. Each language provider configuration element can contain optional `compilerOptions` and `warningLevel` attributes. These attributes define the default values for the and properties. - If the language provider configuration element does not define the `compilerOptions` attribute, the property value is an empty string (""). If the language provider configuration element does not define the `warningLevel` attribute, the property value is -1. + If the language provider configuration element does not define the `compilerOptions` attribute, the property value is an empty string (""). If the language provider configuration element does not define the `warningLevel` attribute, the property value is -1. @@ -339,7 +339,7 @@ The two instances are considered equal if the values of the following properties are equal: -- The property. +- The property. - The , , and properties of the instance returned by the method. @@ -557,7 +557,7 @@ property to check the implementation before accessing the provider properties or methods. For example, after you get the language provider settings from the method, use the property to verify the provider type implementation before calling the method or using the property. + Use the property to check the implementation before accessing the provider properties or methods. For example, after you get the language provider settings from the method, use the property to verify the provider type implementation before calling the method or using the property. diff --git a/xml/System.CodeDom.Compiler/CompilerParameters.xml b/xml/System.CodeDom.Compiler/CompilerParameters.xml index 83e7868f143..3d5560a0e9c 100644 --- a/xml/System.CodeDom.Compiler/CompilerParameters.xml +++ b/xml/System.CodeDom.Compiler/CompilerParameters.xml @@ -50,15 +50,15 @@ ## Remarks A object represents the settings and options for an interface. - If you are compiling an executable program, you must set the property to `true`. When the is set to `false`, the compiler will generate a class library. By default, a new is initialized with its property set to `false`. If you are compiling an executable from a CodeDOM graph, a must be defined in the graph. If there are multiple code entry points, you can indicate the class that defines the entry point to use by setting the name of the class to the property. + If you are compiling an executable program, you must set the property to `true`. When the is set to `false`, the compiler will generate a class library. By default, a new is initialized with its property set to `false`. If you are compiling an executable from a CodeDOM graph, a must be defined in the graph. If there are multiple code entry points, you can indicate the class that defines the entry point to use by setting the name of the class to the property. - You can specify a file name for the output assembly in the property. Otherwise, a default output file name will be used. To include debug information in a generated assembly, set the property to `true`. If your project references any assemblies, you must specify the assembly names as items in a set to the property of the used when invoking compilation. + You can specify a file name for the output assembly in the property. Otherwise, a default output file name will be used. To include debug information in a generated assembly, set the property to `true`. If your project references any assemblies, you must specify the assembly names as items in a set to the property of the used when invoking compilation. - You can compile an assembly that is written to memory rather than disk by setting the property to `true`. When an assembly is generated in memory, your code can obtain a reference to the generated assembly from the property of a . If an assembly is written to disk, you can obtain the path to the generated assembly from the property of a . + You can compile an assembly that is written to memory rather than disk by setting the property to `true`. When an assembly is generated in memory, your code can obtain a reference to the generated assembly from the property of a . If an assembly is written to disk, you can obtain the path to the generated assembly from the property of a . - To specify a warning level at which to halt compilation, set the property to an integer that represents the warning level at which to halt compilation. You can also configure the compiler to halt compilation if warnings are encountered by setting the property to `true`. + To specify a warning level at which to halt compilation, set the property to an integer that represents the warning level at which to halt compilation. You can also configure the compiler to halt compilation if warnings are encountered by setting the property to `true`. - To specify a custom command-line arguments string to use when invoking the compilation process, set the string in the property. If a Win32 security token is required to invoke the compiler process, specify the token in the property. To include .NET Framework resource files in the compiled assembly, add the names of the resource files to the property. To reference .NET Framework resources in another assembly, add the names of the resource files to the property. To include a Win32 resource file in the compiled assembly, specify the name of the Win32 resource file in the property. + To specify a custom command-line arguments string to use when invoking the compilation process, set the string in the property. If a Win32 security token is required to invoke the compiler process, specify the token in the property. To include .NET Framework resource files in the compiled assembly, add the names of the resource files to the property. To reference .NET Framework resources in another assembly, add the names of the resource files to the property. To include a Win32 resource file in the compiled assembly, specify the name of the Win32 resource file in the property. > [!NOTE] > This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands) and [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). @@ -349,7 +349,7 @@ An typically includes this string o property. + If the value of this property is an empty string or `null`, the compiler uses the default core assembly. Depending on the compiler version, the default core assembly may be mscorlib.dll or System.Runtime.dll in a Framework directory or reference assembly directory. If the value of this property is not empty, the Code Document Object Model (CodeDOM) explicitly references the specified assembly and emits compiler options that cause the compiler to not reference any assemblies implicitly during compilation.. For compilers that reference the core or standard assembly only implicitly by default, this property can be used on its own. For compilers that implicitly reference assemblies in addition to the core or standard assembly, using this option may require specifying additional entries in the property. > [!NOTE] > An or implementation may choose to ignore this property. @@ -409,7 +409,7 @@ An typically includes this string o Add one or more .NET resource file paths to the returned to embed the file resources in the compiled assembly. Adding a duplicate or invalid file path results in compilation errors; ensure that each string specifies a unique path to a valid .NET resource file. - Use to include default or neutral culture .NET resources for an assembly; use the property to reference .NET resources in satellite assemblies. + Use to include default or neutral culture .NET resources for an assembly; use the property to reference .NET resources in satellite assemblies. ## Examples The following example illustrates using to specify various compiler settings and options. This code example is part of a larger example provided for the class. @@ -671,7 +671,7 @@ An typically includes this string o Add one or more .NET resource file paths to the returned to create links for the resources in the compiled assembly. Adding a duplicate or invalid file path results in compilation errors; ensure that each string specifies a unique path to a valid .NET resource file. - Use to reference .NET resources in satellite assemblies, localized for a particular culture; use the property to embed the resources into the compiled assembly. + Use to reference .NET resources in satellite assemblies, localized for a particular culture; use the property to embed the resources into the compiled assembly. ## Examples The following example illustrates using to specify various compiler settings and options. This code example is part of a larger example provided for the class. @@ -900,7 +900,7 @@ An typically includes this string o property in the collection. The property is set if the collection is created using the constructor with the `keepFiles` parameter set to `true`. + The temporary files in the collection are retained or deleted upon the completion of compiler activity based on the value of the property in the collection. The property is set if the collection is created using the constructor with the `keepFiles` parameter set to `true`. > [!NOTE] > This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands) and [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). diff --git a/xml/System.CodeDom.Compiler/CompilerResults.xml b/xml/System.CodeDom.Compiler/CompilerResults.xml index dc6284858e5..23ea1ca2fef 100644 --- a/xml/System.CodeDom.Compiler/CompilerResults.xml +++ b/xml/System.CodeDom.Compiler/CompilerResults.xml @@ -46,19 +46,19 @@ ## Remarks This class contains the following information about the results of a compilation by an interface implementation: -- The property indicates the compiled assembly. +- The property indicates the compiled assembly. -- The property indicates the security evidence for the assembly. +- The property indicates the security evidence for the assembly. -- The property indicates the path to the compiled assembly, if it was not generated only in memory. +- The property indicates the path to the compiled assembly, if it was not generated only in memory. -- The property indicates any compiler errors and warnings. +- The property indicates any compiler errors and warnings. -- The property contains the compiler output messages. +- The property contains the compiler output messages. -- The property indicates result code value returned by the compiler. +- The property indicates result code value returned by the compiler. -- The property indicates the temporary files generated during compilation and linking. +- The property indicates the temporary files generated during compilation and linking. > [!NOTE] > This class contains an inheritance demand at the class level that applies to all members. A is thrown when the derived class does not have full-trust permission. For details about inheritance demands, see [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). @@ -154,7 +154,7 @@ ## Remarks > [!NOTE] -> The `get` accessor for the property calls the method to load the compiled assembly into the current application domain. After calling the `get` accessor, the compiled assembly cannot be deleted until the current is unloaded. +> The `get` accessor for the property calls the method to load the compiled assembly into the current application domain. After calling the `get` accessor, the compiled assembly cannot be deleted until the current is unloaded. ]]> diff --git a/xml/System.CodeDom.Compiler/LanguageOptions.xml b/xml/System.CodeDom.Compiler/LanguageOptions.xml index 74f6ccef121..82521cdb6ee 100644 --- a/xml/System.CodeDom.Compiler/LanguageOptions.xml +++ b/xml/System.CodeDom.Compiler/LanguageOptions.xml @@ -44,11 +44,11 @@ Defines identifiers that indicate special features of a language. - has a property that is used to indicate certain characteristics of the programming language supported by the provider. The meaning of a identifier can be relevant to properly generating, compiling, and reading the language. - + has a property that is used to indicate certain characteristics of the programming language supported by the provider. The meaning of a identifier can be relevant to properly generating, compiling, and reading the language. + ]]> diff --git a/xml/System.CodeDom.Compiler/TempFileCollection.xml b/xml/System.CodeDom.Compiler/TempFileCollection.xml index 112aed15a5f..5cf46907c3b 100644 --- a/xml/System.CodeDom.Compiler/TempFileCollection.xml +++ b/xml/System.CodeDom.Compiler/TempFileCollection.xml @@ -62,13 +62,13 @@ A file in any directory can be added to an instance of using the method. - To generate a unique name for a temporary file of a particular file extension, call and specify the extension of the file name to generate. The method will return a string consisting of a full path to a file name of the specified extension in the directory specified by the property. The method will only return one unique file name per file name extension. + To generate a unique name for a temporary file of a particular file extension, call and specify the extension of the file name to generate. The method will return a string consisting of a full path to a file name of the specified extension in the directory specified by the property. The method will only return one unique file name per file name extension. Both the and methods have overloads that allow you to specify whether the files should be deleted when the collection is disposed or the method is called. The method will delete all the files in the collection except those that are marked to be kept. - The property indicates a full path to the base file name, without a file name extension, used to generate the file names returned by the method. + The property indicates a full path to the base file name, without a file name extension, used to generate the file names returned by the method. > [!NOTE] > This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands) and [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). @@ -218,7 +218,7 @@ parameter. The temporary files in the collection are retained or deleted upon the completion of compiler activity based on the value of the property in the collection. As each file is added to the collection, the current value of is associated with it, unless it is added with a method that has a `keepFile` parameter, in which case that value is used for that specific file. When the method is called, if is `true`, all files are deleted, including those added with a value of `true`. This allows specific files, those identified as being keep files, to be temporarily retained after compilation for purposes such as error reporting, then deleted when they are no longer needed. + The value of `keepFiles` is used to set the parameter. The temporary files in the collection are retained or deleted upon the completion of compiler activity based on the value of the property in the collection. As each file is added to the collection, the current value of is associated with it, unless it is added with a method that has a `keepFile` parameter, in which case that value is used for that specific file. When the method is called, if is `true`, all files are deleted, including those added with a value of `true`. This allows specific files, those identified as being keep files, to be temporarily retained after compilation for purposes such as error reporting, then deleted when they are no longer needed. ]]> @@ -541,7 +541,7 @@ method examines each file in the collection to determine, on an individual basis, whether the file is to be kept or deleted. Files can be explicitly marked to be kept when added to the collection using add methods that take a `keepFile` parameter. When adding a file to the collection using the overload that does not have a `keepFile` parameter the value of the property is used as the default keep file indicator. + The method examines each file in the collection to determine, on an individual basis, whether the file is to be kept or deleted. Files can be explicitly marked to be kept when added to the collection using add methods that take a `keepFile` parameter. When adding a file to the collection using the overload that does not have a `keepFile` parameter the value of the property is used as the default keep file indicator. ]]> @@ -738,7 +738,7 @@ property is used as the default value when the overload that does not have a `keepFile` parameter is called to add a temporary file to the collection. Each temporary file in the collection has an associated keep file flag that determines, on a per-file basis, whether that file is to be kept or deleted. Files are automatically kept or deleted on completion of the compilation based on their associated keep files value. However, after compilation is complete, files that were kept can be released by setting false and calling the method. This will result in all files being deleted. + The value of the property is used as the default value when the overload that does not have a `keepFile` parameter is called to add a temporary file to the collection. Each temporary file in the collection has an associated keep file flag that determines, on a per-file basis, whether that file is to be kept or deleted. Files are automatically kept or deleted on completion of the compilation based on their associated keep files value. However, after compilation is complete, files that were kept can be released by setting false and calling the method. This will result in all files being deleted. ]]> diff --git a/xml/System.CodeDom/CodeArgumentReferenceExpression.xml b/xml/System.CodeDom/CodeArgumentReferenceExpression.xml index 1b1d8d67e4e..9ea6ddff1d9 100644 --- a/xml/System.CodeDom/CodeArgumentReferenceExpression.xml +++ b/xml/System.CodeDom/CodeArgumentReferenceExpression.xml @@ -54,13 +54,13 @@ ## Remarks can be used in a method to reference the value of a parameter that has been passed to the method. - The property specifies the name of the parameter to reference. + The property specifies the name of the parameter to reference. ## Examples The following example code defines a method that invokes `Console.WriteLine` to output the string parameter passed to the method. A references the argument passed to the method by method parameter name. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeArgumentReferenceExpression/Overview/codeargumentreferenceexpressionexample.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeArgumentReferenceExpression/Overview/codeargumentreferenceexpressionexample.vb" id="Snippet2"::: diff --git a/xml/System.CodeDom/CodeArrayCreateExpression.xml b/xml/System.CodeDom/CodeArrayCreateExpression.xml index 95a24d2059f..d44f35b39d1 100644 --- a/xml/System.CodeDom/CodeArrayCreateExpression.xml +++ b/xml/System.CodeDom/CodeArrayCreateExpression.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent a code expression that creates an array. Expressions that create an array should specify either a number of elements, or a list of expressions to use to initialize the array. - Most arrays can be initialized immediately following declaration. The property can be set to the expression to use to initialize the array. + Most arrays can be initialized immediately following declaration. The property can be set to the expression to use to initialize the array. A only directly supports creating single-dimension arrays. If a language allows arrays of arrays, it is possible to create them by nesting a within a . Not all languages support arrays of arrays. You can check whether an for a language declares support for nested arrays by calling with the flag. @@ -62,7 +62,7 @@ ## Examples The following code uses a to create an array of integers with 10 indexes. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeArrayCreateExpression/Overview/codearraycreateexpressionsnippet.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeArrayCreateExpression/Overview/codearraycreateexpressionsnippet.vb" id="Snippet1"::: diff --git a/xml/System.CodeDom/CodeArrayIndexerExpression.xml b/xml/System.CodeDom/CodeArrayIndexerExpression.xml index 84be5a84d6a..2298de3a5c0 100644 --- a/xml/System.CodeDom/CodeArrayIndexerExpression.xml +++ b/xml/System.CodeDom/CodeArrayIndexerExpression.xml @@ -52,13 +52,13 @@ can be used to represent a reference to an index of an array of one or more dimensions. Use for representing a reference to an index of a code (non-array) indexer. The property indicates the indexer object. The property indicates either a single index within the target array, or a set of indexes that together specify a specific intersection of indexes across the dimensions of the array. + can be used to represent a reference to an index of an array of one or more dimensions. Use for representing a reference to an index of a code (non-array) indexer. The property indicates the indexer object. The property indicates either a single index within the target array, or a set of indexes that together specify a specific intersection of indexes across the dimensions of the array. ## Examples The following code creates a that references index 5 of an array of integers named `x` : - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeArrayIndexerExpression/Overview/codearrayindexerexpressionsnippet.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeArrayIndexerExpression/Overview/codearrayindexerexpressionsnippet.vb" id="Snippet1"::: diff --git a/xml/System.CodeDom/CodeAssignStatement.xml b/xml/System.CodeDom/CodeAssignStatement.xml index 679d86bf49e..fdfd35b1d01 100644 --- a/xml/System.CodeDom/CodeAssignStatement.xml +++ b/xml/System.CodeDom/CodeAssignStatement.xml @@ -52,7 +52,7 @@ can be used to represent a statement that assigns the value of an object to another object, or a reference to another reference. Simple assignment statements are usually of the form " `value1` = `value2` ", where `value1` is the object being assigned to, and `value2` is being assigned. The property indicates the object to assign to. The property indicates the object to assign. + can be used to represent a statement that assigns the value of an object to another object, or a reference to another reference. Simple assignment statements are usually of the form " `value1` = `value2` ", where `value1` is the object being assigned to, and `value2` is being assigned. The property indicates the object to assign to. The property indicates the object to assign. diff --git a/xml/System.CodeDom/CodeAttachEventStatement.xml b/xml/System.CodeDom/CodeAttachEventStatement.xml index 60bd39345c9..aacbf3985c5 100644 --- a/xml/System.CodeDom/CodeAttachEventStatement.xml +++ b/xml/System.CodeDom/CodeAttachEventStatement.xml @@ -52,13 +52,13 @@ can be used to represent a statement that adds an event-handler delegate for an event. The property indicates the event to attach the event handler to. The property indicates the event handler to attach. + can be used to represent a statement that adds an event-handler delegate for an event. The property indicates the event to attach the event handler to. The property indicates the event handler to attach. ## Examples The following example code demonstrates use of a to attach an event handler with an event. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeAttachEventStatement/Overview/codeattacheventstatementexample.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeAttachEventStatement/Overview/codeattacheventstatementexample.vb" id="Snippet3"::: diff --git a/xml/System.CodeDom/CodeAttributeArgument.xml b/xml/System.CodeDom/CodeAttributeArgument.xml index ee2d4f7ad7c..0b0637a2768 100644 --- a/xml/System.CodeDom/CodeAttributeArgument.xml +++ b/xml/System.CodeDom/CodeAttributeArgument.xml @@ -54,9 +54,9 @@ ## Remarks can be used to represent either the value for a single argument of an attribute constructor, or a value with which to initialize a property of the attribute. - The property indicates the value of the argument. The property, when used, indicates the name of a property of the attribute to which to assign the value. + The property indicates the value of the argument. The property, when used, indicates the name of a property of the attribute to which to assign the value. - Attribute declarations are frequently initialized with a number of arguments that are passed into the constructor of the attribute at run time. To provide arguments to the constructor for an attribute, add a for each argument to the collection of a . Only the property of each needs to be initialized. The order of arguments within the collection must correspond to the order of arguments in the method signature of the constructor for the attribute. + Attribute declarations are frequently initialized with a number of arguments that are passed into the constructor of the attribute at run time. To provide arguments to the constructor for an attribute, add a for each argument to the collection of a . Only the property of each needs to be initialized. The order of arguments within the collection must correspond to the order of arguments in the method signature of the constructor for the attribute. You can also set properties of the attribute that are not available through the constructor by providing a that indicates the name of the property to set, along with the value to set. @@ -64,7 +64,7 @@ ## Examples The following code creates a class, and adds code attributes to declare that the class is serializable and obsolete. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeAttributeArgument/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeAttributeArgument/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.CodeDom/CodeAttributeDeclaration.xml b/xml/System.CodeDom/CodeAttributeDeclaration.xml index d9f06f312ed..16fde0c9b4d 100644 --- a/xml/System.CodeDom/CodeAttributeDeclaration.xml +++ b/xml/System.CodeDom/CodeAttributeDeclaration.xml @@ -58,7 +58,7 @@ ## Examples The following code example creates a that declares a with an argument of `false`: - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeAttributeDeclaration/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeAttributeDeclaration/Overview/source.vb" id="Snippet1"::: @@ -235,7 +235,7 @@ and properties, and the `arguments` parameter is used to set the property for the . + The `attributeType` parameter is used to set the and properties, and the `arguments` parameter is used to set the property for the . ]]> diff --git a/xml/System.CodeDom/CodeCastExpression.xml b/xml/System.CodeDom/CodeCastExpression.xml index 3442375928f..ce6f22a6050 100644 --- a/xml/System.CodeDom/CodeCastExpression.xml +++ b/xml/System.CodeDom/CodeCastExpression.xml @@ -54,13 +54,13 @@ ## Remarks can be used to represent an expression cast to a different data type or interface. - The property indicates the to cast. The property indicates the type to cast to. + The property indicates the to cast. The property indicates the type to cast to. ## Examples This example demonstrates using a to cast a `System.Int32` value to a `System.Int64` data type. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeCastExpression/Overview/codecastexpressionexample.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeCastExpression/Overview/codecastexpressionexample.vb" id="Snippet2"::: diff --git a/xml/System.CodeDom/CodeCatchClause.xml b/xml/System.CodeDom/CodeCatchClause.xml index 2f8b67b64d9..dd9637b155e 100644 --- a/xml/System.CodeDom/CodeCatchClause.xml +++ b/xml/System.CodeDom/CodeCatchClause.xml @@ -54,13 +54,13 @@ ## Remarks can be used to represent a `catch` exception block of a `try/catch` statement. - The property specifies the type of exception to catch. The property specifies a name for the variable representing the exception that has been caught. The collection property contains the statements for the `catch` block. + The property specifies the type of exception to catch. The property specifies a name for the variable representing the exception that has been caught. The collection property contains the statements for the `catch` block. ## Examples The following example code demonstrates using objects to define exception handling clauses of a try...catch block. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeCatchClause/Overview/codetrycatchfinallyexample.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeCatchClause/Overview/codetrycatchfinallyexample.vb" id="Snippet2"::: diff --git a/xml/System.CodeDom/CodeChecksumPragma.xml b/xml/System.CodeDom/CodeChecksumPragma.xml index 5bb4d40d416..bf1948786e9 100644 --- a/xml/System.CodeDom/CodeChecksumPragma.xml +++ b/xml/System.CodeDom/CodeChecksumPragma.xml @@ -165,7 +165,7 @@ property. + For more information on the `checksumAlgorithmId` parameter, see the property. @@ -232,7 +232,7 @@ Algorithms are provided for the MD5 and SHA-1 hashes. The GUID value to use for Due to collision problems with SHA-1 and MD5, Microsoft recommends a security model based on SHA-256 or better. ## Examples - The following code example shows the setting of the property. This code example is part of a larger example provided for the class. + The following code example shows the setting of the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet6"::: @@ -286,12 +286,12 @@ Algorithms are provided for the MD5 and SHA-1 hashes. The GUID value to use for property contains data from the target file specified by the property. + The property contains data from the target file specified by the property. ## Examples - The following code example shows the setting of the property. This code example is part of a larger example provided for the class + The following code example shows the setting of the property. This code example is part of a larger example provided for the class :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet7"::: @@ -341,12 +341,12 @@ Algorithms are provided for the MD5 and SHA-1 hashes. The GUID value to use for property value is "C:\Temp\Test\OuterLinePragma.txt". + An example of a property value is "C:\Temp\Test\OuterLinePragma.txt". ## Examples - The following code example shows the setting of the property. This code example is part of a larger example provided for the class + The following code example shows the setting of the property. This code example is part of a larger example provided for the class :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet5"::: diff --git a/xml/System.CodeDom/CodeCompileUnit.xml b/xml/System.CodeDom/CodeCompileUnit.xml index b1f4092c824..1308d244f22 100644 --- a/xml/System.CodeDom/CodeCompileUnit.xml +++ b/xml/System.CodeDom/CodeCompileUnit.xml @@ -181,7 +181,7 @@ property. This example is part of a larger example provided for the class. + The following code example shows the use of the property. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet3"::: @@ -327,7 +327,7 @@ property. This example is part of a larger example provided for the class. + The following code example shows the use of the property. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet2"::: diff --git a/xml/System.CodeDom/CodeConditionStatement.xml b/xml/System.CodeDom/CodeConditionStatement.xml index f376c0ca7ad..e279831e964 100644 --- a/xml/System.CodeDom/CodeConditionStatement.xml +++ b/xml/System.CodeDom/CodeConditionStatement.xml @@ -54,13 +54,13 @@ ## Remarks can be used to represent code that consists of a conditional expression, a collection of statements to execute if the conditional expression evaluates to `true`, and an optional collection of statements to execute if the conditional expression evaluates to `false`. A is generated in many languages as an `if` statement. - The property indicates the expression to test. The property contains the statements to execute if the expression to test evaluates to `true`. The property contains the statements to execute if the expression to test evaluates to `false`. + The property indicates the expression to test. The property contains the statements to execute if the expression to test evaluates to `true`. The property contains the statements to execute if the expression to test evaluates to `false`. ## Examples This example demonstrates using a to represent an `if` statement with an `else` block. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeConditionStatement/Overview/codeconditionstatementexample.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeConditionStatement/Overview/codeconditionstatementexample.vb" id="Snippet2"::: diff --git a/xml/System.CodeDom/CodeConstructor.xml b/xml/System.CodeDom/CodeConstructor.xml index bda2b452a08..f8b52bb7b32 100644 --- a/xml/System.CodeDom/CodeConstructor.xml +++ b/xml/System.CodeDom/CodeConstructor.xml @@ -54,13 +54,13 @@ ## Remarks can be used to represent a declaration of an instance constructor for a type. Use to declare a static constructor for a type. - If the constructor calls a base class constructor, set the constructor arguments for the base class constructor in the property. If the constructor overloads another constructor for the type, set the constructor arguments to pass to the overloaded type constructor in the property. + If the constructor calls a base class constructor, set the constructor arguments for the base class constructor in the property. If the constructor overloads another constructor for the type, set the constructor arguments to pass to the overloaded type constructor in the property. ## Examples This example demonstrates using a to declare several types of constructors. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeConstructor/Overview/codeconstructorexample.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeConstructor/Overview/codeconstructorexample.vb" id="Snippet2"::: diff --git a/xml/System.CodeDom/CodeDefaultValueExpression.xml b/xml/System.CodeDom/CodeDefaultValueExpression.xml index 00f770a588e..d150282c526 100644 --- a/xml/System.CodeDom/CodeDefaultValueExpression.xml +++ b/xml/System.CodeDom/CodeDefaultValueExpression.xml @@ -48,62 +48,62 @@ Represents a reference to a default value. - can be used to represent a reference to a default value. - - The property specifies the reference to the value type. The class is used in the generation of generics-based code. For more information on generics, see [Generics in the .NET Framework Class Library](/dotnet/csharp/programming-guide/generics/generics-in-the-net-framework-class-library). The following code steps are provided in this section to further describe the use of the class to add a new default value to a code graph. - - The code in part 1 is part of a larger example provided for the class. This code, when run through the C# code generator, results in the C# code that appears in part 2. When this code is called in the statement in part 3, the result is the output shown in part 4. - -```csharp -// Part 1: Code to create a generic Print method. - CodeMemberMethod printMethod = new CodeMemberMethod(); - CodeTypeParameter sType = new CodeTypeParameter("S"); - sType.HasConstructorConstraint = true; - CodeTypeParameter tType = new CodeTypeParameter("T"); - sType.HasConstructorConstraint = true; - - printMethod.Name = "Print"; - printMethod.TypeParameters.Add(sType); - printMethod.TypeParameters.Add(tType); - printMethod.Statements.Add(ConsoleWriteLineStatement( - new CodeDefaultValueExpression(new CodeTypeReference("T")))); - printMethod.Statements.Add(ConsoleWriteLineStatement( - new CodeDefaultValueExpression(new CodeTypeReference("S")))); -``` - -```csharp -// Part 2: Code generated by code in part 1. -public virtual void Print() - where S : new() - { - Console.WriteLine(default(T)); - Console.WriteLine(default(S)); - } -``` - -```csharp -// Part 3: Call to the generated method. -dict.Print(); -``` - -``` -// Part 4: Output of the generated method. -0 -0 - -``` - - - -## Examples - The following code example shows the use of the to create default values for decimal and integer parameters. This example is part of a larger example provided for the class. - + can be used to represent a reference to a default value. + + The property specifies the reference to the value type. The class is used in the generation of generics-based code. For more information on generics, see [Generics in the .NET Framework Class Library](/dotnet/csharp/programming-guide/generics/generics-in-the-net-framework-class-library). The following code steps are provided in this section to further describe the use of the class to add a new default value to a code graph. + + The code in part 1 is part of a larger example provided for the class. This code, when run through the C# code generator, results in the C# code that appears in part 2. When this code is called in the statement in part 3, the result is the output shown in part 4. + +```csharp +// Part 1: Code to create a generic Print method. + CodeMemberMethod printMethod = new CodeMemberMethod(); + CodeTypeParameter sType = new CodeTypeParameter("S"); + sType.HasConstructorConstraint = true; + CodeTypeParameter tType = new CodeTypeParameter("T"); + sType.HasConstructorConstraint = true; + + printMethod.Name = "Print"; + printMethod.TypeParameters.Add(sType); + printMethod.TypeParameters.Add(tType); + printMethod.Statements.Add(ConsoleWriteLineStatement( + new CodeDefaultValueExpression(new CodeTypeReference("T")))); + printMethod.Statements.Add(ConsoleWriteLineStatement( + new CodeDefaultValueExpression(new CodeTypeReference("S")))); +``` + +```csharp +// Part 2: Code generated by code in part 1. +public virtual void Print() + where S : new() + { + Console.WriteLine(default(T)); + Console.WriteLine(default(S)); + } +``` + +```csharp +// Part 3: Call to the generated method. +dict.Print(); +``` + +``` +// Part 4: Output of the generated method. +0 +0 + +``` + + + +## Examples + The following code example shows the use of the to create default values for decimal and integer parameters. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.CodeDom/CodeDelegateCreateExpression.xml b/xml/System.CodeDom/CodeDelegateCreateExpression.xml index f1736024a68..dc46f436cf4 100644 --- a/xml/System.CodeDom/CodeDelegateCreateExpression.xml +++ b/xml/System.CodeDom/CodeDelegateCreateExpression.xml @@ -54,7 +54,7 @@ ## Remarks represents code that creates a delegate. is often used with or to represent an event handler to attach or remove from an event. - The property specifies the type of delegate to create. The property indicates the object that contains the event-handler method. The property indicates the name of the event-handler method whose method signature matches the method signature of the delegate. + The property specifies the type of delegate to create. The property indicates the object that contains the event-handler method. The property indicates the name of the event-handler method whose method signature matches the method signature of the delegate. In C#, a delegate creation expression is typically of the following form: `new EventHandler(this.HandleEventMethod)`. In Visual Basic, a delegate creation expression is typically of the following form: `AddressOf Me.HandleEventMethod`. @@ -62,7 +62,7 @@ ## Examples The following example code uses a to create a delegate. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeAttachEventStatement/Overview/codeattacheventstatementexample.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeAttachEventStatement/Overview/codeattacheventstatementexample.vb" id="Snippet3"::: diff --git a/xml/System.CodeDom/CodeDelegateInvokeExpression.xml b/xml/System.CodeDom/CodeDelegateInvokeExpression.xml index 88f8eda1eef..eeddf84ba1e 100644 --- a/xml/System.CodeDom/CodeDelegateInvokeExpression.xml +++ b/xml/System.CodeDom/CodeDelegateInvokeExpression.xml @@ -54,13 +54,13 @@ ## Remarks can be used to represent code that invokes an event. Invoking an event invokes all delegates that are registered with the event using the specified parameters. - The property specifies the event to invoke. The property specifies the parameters to pass to the delegates for the event. + The property specifies the event to invoke. The property specifies the parameters to pass to the delegates for the event. ## Examples The following example demonstrates use of a to invoke an event named `TestEvent`. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeDelegateInvokeExpression/Overview/codedelegateinvokeexpressionexample.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDelegateInvokeExpression/Overview/codedelegateinvokeexpressionexample.vb" id="Snippet3"::: diff --git a/xml/System.CodeDom/CodeDirectionExpression.xml b/xml/System.CodeDom/CodeDirectionExpression.xml index a30db81fcc3..ff336932878 100644 --- a/xml/System.CodeDom/CodeDirectionExpression.xml +++ b/xml/System.CodeDom/CodeDirectionExpression.xml @@ -54,7 +54,7 @@ ## Remarks can represent a parameter passed to a method and the reference direction of the parameter. - The property indicates the expression to qualify with a direction. The property indicates the direction of the parameter using one of the enumeration values. + The property indicates the expression to qualify with a direction. The property indicates the direction of the parameter using one of the enumeration values. > [!NOTE] > is intended to be used as a method invoke parameter, and should not be used when declaring methods. @@ -63,7 +63,7 @@ ## Examples The following example demonstrates use of a to specify a field direction modifier for an expression to pass as a method parameter. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeDirectionExpression/Overview/codemultiexample.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDirectionExpression/Overview/codemultiexample.vb" id="Snippet4"::: diff --git a/xml/System.CodeDom/CodeEventReferenceExpression.xml b/xml/System.CodeDom/CodeEventReferenceExpression.xml index 252ee676ce9..6d356795d44 100644 --- a/xml/System.CodeDom/CodeEventReferenceExpression.xml +++ b/xml/System.CodeDom/CodeEventReferenceExpression.xml @@ -54,13 +54,13 @@ ## Remarks can be used to represent a reference to an event. - The property specifies the object that contains the event. The property specifies the name of the event. + The property specifies the object that contains the event. The property specifies the name of the event. ## Examples The following example demonstrates use of to reference an event named TestEvent. - + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeDirectionExpression/Overview/codemultiexample.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDirectionExpression/Overview/codemultiexample.vb" id="Snippet2"::: diff --git a/xml/System.CodeDom/CodeFieldReferenceExpression.xml b/xml/System.CodeDom/CodeFieldReferenceExpression.xml index ed5da789f7c..8b3d619b5f0 100644 --- a/xml/System.CodeDom/CodeFieldReferenceExpression.xml +++ b/xml/System.CodeDom/CodeFieldReferenceExpression.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent a reference to a field. - The property specifies the object that contains the field. The property specifies the name of the field to reference. + The property specifies the object that contains the field. The property specifies the name of the field to reference. diff --git a/xml/System.CodeDom/CodeGotoStatement.xml b/xml/System.CodeDom/CodeGotoStatement.xml index 64d97462cf6..d407df5da12 100644 --- a/xml/System.CodeDom/CodeGotoStatement.xml +++ b/xml/System.CodeDom/CodeGotoStatement.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent a `goto` statement, which is used in some languages to redirect program flow to a specified label. - The property indicates the name of the label at which to continue program execution. + The property indicates the name of the label at which to continue program execution. > [!NOTE] > Not all languages support `goto` statements. Call the method with the flag to determine whether a code generator supports `goto` statements. @@ -118,7 +118,7 @@ property to indicate the name of the label at which to continue program execution. + If you use this constructor you must also set the property to indicate the name of the label at which to continue program execution. ]]> diff --git a/xml/System.CodeDom/CodeIterationStatement.xml b/xml/System.CodeDom/CodeIterationStatement.xml index 2ff69beddde..38d2c32f75a 100644 --- a/xml/System.CodeDom/CodeIterationStatement.xml +++ b/xml/System.CodeDom/CodeIterationStatement.xml @@ -54,7 +54,7 @@ ## Remarks A can represent a `for` loop or `while` loop. - The property specifies the statement to execute before the first loop iteration. The property specifies the loop continuation expression, which must evaluate to `true` at the end of each loop iteration for another iteration to begin. The property specifies the statement to execute at the end of each loop iteration. The property specifies the collection of statements to execute within the loop. + The property specifies the statement to execute before the first loop iteration. The property specifies the loop continuation expression, which must evaluate to `true` at the end of each loop iteration for another iteration to begin. The property specifies the statement to execute at the end of each loop iteration. The property specifies the collection of statements to execute within the loop. diff --git a/xml/System.CodeDom/CodeLabeledStatement.xml b/xml/System.CodeDom/CodeLabeledStatement.xml index 2e37509d26e..e3d5b5e74a5 100644 --- a/xml/System.CodeDom/CodeLabeledStatement.xml +++ b/xml/System.CodeDom/CodeLabeledStatement.xml @@ -54,7 +54,7 @@ ## Remarks represents a label and optionally, an associated statement. A label can be used to indicate the target of a . - The property is optional. To create only a label, leave the property uninitialized. + The property is optional. To create only a label, leave the property uninitialized. > [!NOTE] > Not all languages support `goto` statements and labels, so you should test whether a code generator supports `goto` statements and labels by calling the method with the flag. diff --git a/xml/System.CodeDom/CodeMemberField.xml b/xml/System.CodeDom/CodeMemberField.xml index 622343958c5..eb8787e5eb8 100644 --- a/xml/System.CodeDom/CodeMemberField.xml +++ b/xml/System.CodeDom/CodeMemberField.xml @@ -284,7 +284,7 @@ property. + The following example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeMemberField/InitExpression/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeMemberField/InitExpression/program.vb" id="Snippet1"::: diff --git a/xml/System.CodeDom/CodeMemberMethod.xml b/xml/System.CodeDom/CodeMemberMethod.xml index b4adde199b1..8094f91f826 100644 --- a/xml/System.CodeDom/CodeMemberMethod.xml +++ b/xml/System.CodeDom/CodeMemberMethod.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent the declaration for a method. - The property specifies the data type of the method's return value. The property contains the method's parameters. The property contains the statements of the method. + The property specifies the data type of the method's return value. The property contains the method's parameters. The property contains the statements of the method. @@ -154,7 +154,7 @@ If this represents a declaration for a public method, and this method implements a method on an interface, the interface or interfaces this method implements a method of should be referenced in this collection. - The method should still have the same name as the method of the interface that is implemented by this method. For some languages, like C#, this has no effect on the syntax. For others, like Visual Basic, there is a special syntax for implementing interfaces. If the method is privately implementing a single interface, the property should be used instead. + The method should still have the same name as the method of the interface that is implemented by this method. For some languages, like C#, this has no effect on the syntax. For others, like Visual Basic, there is a special syntax for implementing interfaces. If the method is privately implementing a single interface, the property should be used instead. ]]> @@ -513,7 +513,7 @@ ## Examples - The following code example shows the use of the property to add two type parameters to the `printMethod`. This example is part of a larger example provided for the class. + The following code example shows the use of the property to add two type parameters to the `printMethod`. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet6"::: diff --git a/xml/System.CodeDom/CodeMemberProperty.xml b/xml/System.CodeDom/CodeMemberProperty.xml index 740ed705fa3..eb1ed29d072 100644 --- a/xml/System.CodeDom/CodeMemberProperty.xml +++ b/xml/System.CodeDom/CodeMemberProperty.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent the declaration for a property of a type. - The property specifies the data type of the property. The property contains any get statement methods for the property. The property contains any set statement methods for the property. The property specifies any parameters for the property, such as are required for an indexer property. + The property specifies the data type of the property. The property contains any get statement methods for the property. The property contains any set statement methods for the property. The property specifies any parameters for the property, such as are required for an indexer property. diff --git a/xml/System.CodeDom/CodeMethodInvokeExpression.xml b/xml/System.CodeDom/CodeMethodInvokeExpression.xml index 12065d6bd55..2120c3bb78b 100644 --- a/xml/System.CodeDom/CodeMethodInvokeExpression.xml +++ b/xml/System.CodeDom/CodeMethodInvokeExpression.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent an expression that invokes a method. - The property specifies the method to invoke. The property indicates the parameters to pass to the method. Use a to specify the field direction of a parameter. + The property specifies the method to invoke. The property indicates the parameters to pass to the method. Use a to specify the field direction of a parameter. diff --git a/xml/System.CodeDom/CodeMethodReferenceExpression.xml b/xml/System.CodeDom/CodeMethodReferenceExpression.xml index 03e6e7ee036..779b017390b 100644 --- a/xml/System.CodeDom/CodeMethodReferenceExpression.xml +++ b/xml/System.CodeDom/CodeMethodReferenceExpression.xml @@ -54,7 +54,7 @@ ## Remarks A can be used to represent an expression of the form Object.Method. - The property indicates the object that contains the method. The property indicates the name of the method. + The property indicates the object that contains the method. The property indicates the name of the method. A is used with a to indicate the method to invoke, and with a to indicate the method to handle the event. @@ -342,7 +342,7 @@ property represents a collection of type references to be substituted for the type parameter references of the current generic method. + The property represents a collection of type references to be substituted for the type parameter references of the current generic method. ]]> diff --git a/xml/System.CodeDom/CodeMethodReturnStatement.xml b/xml/System.CodeDom/CodeMethodReturnStatement.xml index cad44101364..c4fc4bb3ac4 100644 --- a/xml/System.CodeDom/CodeMethodReturnStatement.xml +++ b/xml/System.CodeDom/CodeMethodReturnStatement.xml @@ -52,7 +52,7 @@ can be used to represent a return value statement. The property specifies the value to return. + can be used to represent a return value statement. The property specifies the value to return. diff --git a/xml/System.CodeDom/CodeNamespace.xml b/xml/System.CodeDom/CodeNamespace.xml index 052b6c39a38..a1a317d9612 100644 --- a/xml/System.CodeDom/CodeNamespace.xml +++ b/xml/System.CodeDom/CodeNamespace.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent a namespace declaration. - The property specifies the name of the namespace. The property contains the namespace import directives for the namespace. The property contains the type declarations for the namespace. The property contains the comments that apply at the namespace level. + The property specifies the name of the namespace. The property contains the namespace import directives for the namespace. The property contains the type declarations for the namespace. The property contains the comments that apply at the namespace level. In some languages, a namespace can function as a container for type declarations; all types in the same namespace are accessible without using fully-qualified type references, if there is no conflict between type names. diff --git a/xml/System.CodeDom/CodeObjectCreateExpression.xml b/xml/System.CodeDom/CodeObjectCreateExpression.xml index b651656e7ff..ae8ffec13dc 100644 --- a/xml/System.CodeDom/CodeObjectCreateExpression.xml +++ b/xml/System.CodeDom/CodeObjectCreateExpression.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent an expression that creates an instance of a type. - The property specifies the data type to create a new instance of. The property specifies the parameters to pass to the constructor of the type to create a new instance of. + The property specifies the data type to create a new instance of. The property specifies the parameters to pass to the constructor of the type to create a new instance of. diff --git a/xml/System.CodeDom/CodeParameterDeclarationExpression.xml b/xml/System.CodeDom/CodeParameterDeclarationExpression.xml index cb88f167b4a..f68d2fed9e2 100644 --- a/xml/System.CodeDom/CodeParameterDeclarationExpression.xml +++ b/xml/System.CodeDom/CodeParameterDeclarationExpression.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent code that declares a parameter for a method, property, or constructor. - The property specifies the name of the parameter. The property specifies the data type of the parameter. The property specifies the direction modifier of the parameter. The property specifies the attributes associated with the parameter. + The property specifies the name of the parameter. The property specifies the data type of the parameter. The property specifies the direction modifier of the parameter. The property specifies the attributes associated with the parameter. diff --git a/xml/System.CodeDom/CodePrimitiveExpression.xml b/xml/System.CodeDom/CodePrimitiveExpression.xml index a7434e00ad9..d113e4b7ab1 100644 --- a/xml/System.CodeDom/CodePrimitiveExpression.xml +++ b/xml/System.CodeDom/CodePrimitiveExpression.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent an expression that indicates a primitive data type value. - The property specifies the primitive data type value to represent. + The property specifies the primitive data type value to represent. Primitive data types that can be represented using include `null`; string; 16-, 32-, and 64-bit signed integers; and single-precision and double-precision floating-point numbers. diff --git a/xml/System.CodeDom/CodePropertyReferenceExpression.xml b/xml/System.CodeDom/CodePropertyReferenceExpression.xml index 40150c3eba9..eb4fa9765d0 100644 --- a/xml/System.CodeDom/CodePropertyReferenceExpression.xml +++ b/xml/System.CodeDom/CodePropertyReferenceExpression.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent a reference to the value of a property. - The property specifies the object that contains the property to reference. The property specifies the name of the property to reference. + The property specifies the object that contains the property to reference. The property specifies the name of the property to reference. This object does not have a property to indicate whether the reference is used in a `get` or `set`. If the property reference occurs on the left, assigned to, side of an assignment statement, then it is a `set`. diff --git a/xml/System.CodeDom/CodeRegionDirective.xml b/xml/System.CodeDom/CodeRegionDirective.xml index 33c6024c6f3..8886a350476 100644 --- a/xml/System.CodeDom/CodeRegionDirective.xml +++ b/xml/System.CodeDom/CodeRegionDirective.xml @@ -48,22 +48,22 @@ Specifies the name and mode for a code region. - property specifies whether an instance represents the start or end of the region. - + property specifies whether an instance represents the start or end of the region. + > [!NOTE] -> Not all compilers support code region directives. To prevent compiler errors, code providers normally do not include code region directives in the provider output for compilers that do not support them. - - - -## Examples - The following code example shows the use of the in the creation of a graph that is used to produce code that is also compiled. - +> Not all compilers support code region directives. To prevent compiler errors, code providers normally do not include code region directives in the provider output for compilers that do not support them. + + + +## Examples + The following code example shows the use of the in the creation of a graph that is used to produce code that is also compiled. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet1"::: + ]]> @@ -111,11 +111,11 @@ Initializes a new instance of the class with default values. - and properties. - + and properties. + ]]> @@ -154,14 +154,14 @@ The name for the region. Initializes a new instance of the class, specifying its mode and name. - constructor. This code example is part of a larger example provided for the class. - + constructor. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet9"::: + ]]> @@ -208,14 +208,14 @@ Gets or sets the mode for the region directive. One of the values. The default is . - property. This example is part of a larger example provided for the class. - + property. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet11"::: + ]]> @@ -258,14 +258,14 @@ Gets or sets the name of the region. The name of the region. - property. This example is part of a larger example provided for the class. - + property. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet12"::: + ]]> diff --git a/xml/System.CodeDom/CodeRemoveEventStatement.xml b/xml/System.CodeDom/CodeRemoveEventStatement.xml index 8fbe81ed73b..a679ff19a9a 100644 --- a/xml/System.CodeDom/CodeRemoveEventStatement.xml +++ b/xml/System.CodeDom/CodeRemoveEventStatement.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent a statement that removes an event handler for an event. - The property specifies the event to remove the event handler from. The property specifies the event handler to remove. + The property specifies the event to remove the event handler from. The property specifies the event handler to remove. diff --git a/xml/System.CodeDom/CodeSnippetCompileUnit.xml b/xml/System.CodeDom/CodeSnippetCompileUnit.xml index c1f3c2443a4..6b20689e5ab 100644 --- a/xml/System.CodeDom/CodeSnippetCompileUnit.xml +++ b/xml/System.CodeDom/CodeSnippetCompileUnit.xml @@ -56,7 +56,7 @@ A stores a section of code, exactly in its original format, as a string. The CodeDOM does not translate literal code fragments. Literal code fragments are stored and output in their original format. CodeDOM objects that contain literal code are provided so developers can encapsulate code that is already in the target language. - The property contains the literal code fragment as a string. The property is optional and specifies the position of the code within a source code document. + The property contains the literal code fragment as a string. The property is optional and specifies the position of the code within a source code document. @@ -116,7 +116,7 @@ property. + If you use this constructor you should also set the property. ]]> diff --git a/xml/System.CodeDom/CodeSnippetExpression.xml b/xml/System.CodeDom/CodeSnippetExpression.xml index a7ff8cfe75b..e648e2bbacc 100644 --- a/xml/System.CodeDom/CodeSnippetExpression.xml +++ b/xml/System.CodeDom/CodeSnippetExpression.xml @@ -54,7 +54,7 @@ ## Remarks A literal expression stores the code of an expression as a literal code fragment. The CodeDOM does not translate literal code fragments. Literal code fragments are stored and output just as they are. CodeDOM objects that contain literal code are provided so developers can encapsulate code that is already in the target language. - The property contains the literal code for this snippet expression. + The property contains the literal code for this snippet expression. diff --git a/xml/System.CodeDom/CodeSnippetStatement.xml b/xml/System.CodeDom/CodeSnippetStatement.xml index 281e3855efe..f228e46effb 100644 --- a/xml/System.CodeDom/CodeSnippetStatement.xml +++ b/xml/System.CodeDom/CodeSnippetStatement.xml @@ -49,23 +49,23 @@ Represents a statement using a literal code fragment. - can represent a statement using a literal code fragment that will be included directly in the source without modification. - - A stores a section of code exactly in its original format as a string. The CodeDOM does not translate literal code fragments. Literal code fragments are stored and output in their original format. CodeDOM objects that contain literal code are provided so developers can encapsulate code that is already in the target language. - - The property contains the literal code for the snippet statement. - - - -## Examples - The following example creates an instance of the class using a literal code fragment. This code example is part of a larger example provided for the class. - + can represent a statement using a literal code fragment that will be included directly in the source without modification. + + A stores a section of code exactly in its original format as a string. The CodeDOM does not translate literal code fragments. Literal code fragments are stored and output in their original format. CodeDOM objects that contain literal code are provided so developers can encapsulate code that is already in the target language. + + The property contains the literal code for the snippet statement. + + + +## Examples + The following example creates an instance of the class using a literal code fragment. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet16"::: + ]]> @@ -149,14 +149,14 @@ The literal code fragment of the statement to represent. Initializes a new instance of the class using the specified code fragment. - class using a literal code fragment. This code example is part of a larger example provided for the class. - + class using a literal code fragment. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeChecksumPragma/Overview/codedirective.cs" id="Snippet16"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet16"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeChecksumPragma/Overview/codedirective.vb" id="Snippet16"::: + ]]> diff --git a/xml/System.CodeDom/CodeSnippetTypeMember.xml b/xml/System.CodeDom/CodeSnippetTypeMember.xml index d48ad84c98b..c4cdea19b97 100644 --- a/xml/System.CodeDom/CodeSnippetTypeMember.xml +++ b/xml/System.CodeDom/CodeSnippetTypeMember.xml @@ -49,23 +49,23 @@ Represents a member of a type using a literal code fragment. - can represent a member of a type using a literal code fragment that is included directly in the source without modification. This code can be included in the type declaration. - - A stores a section of code, exactly in its original format, as a string. The CodeDOM does not translate literal code fragments. Literal code fragments are stored and output in their original format. CodeDOM objects that contain literal code are provided so developers can encapsulate code that is already in the target language. - - The property contains the literal code for the type member. - - - -## Examples - The following example demonstrates the use of the class to store literal code in a string format. This code example is part of a larger example provided for the method. - + can represent a member of a type using a literal code fragment that is included directly in the source without modification. This code can be included in the type declaration. + + A stores a section of code, exactly in its original format, as a string. The CodeDOM does not translate literal code fragments. Literal code fragments are stored and output in their original format. CodeDOM objects that contain literal code are provided so developers can encapsulate code that is already in the target language. + + The property contains the literal code for the type member. + + + +## Examples + The following example demonstrates the use of the class to store literal code in a string format. This code example is part of a larger example provided for the method. + :::code language="csharp" source="~/snippets/csharp/Microsoft.CSharp/CSharpCodeProvider/GenerateCodeFromMember/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/Microsoft.CSharp/CSharpCodeProvider/GenerateCodeFromMember/module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/Microsoft.CSharp/CSharpCodeProvider/GenerateCodeFromMember/module1.vb" id="Snippet3"::: + ]]> @@ -149,14 +149,14 @@ The literal code fragment for the type member. Initializes a new instance of the class using the specified text. - constructor to create an instance of the class. This code example is part of a larger example provided for the method. - + constructor to create an instance of the class. This code example is part of a larger example provided for the method. + :::code language="csharp" source="~/snippets/csharp/Microsoft.CSharp/CSharpCodeProvider/GenerateCodeFromMember/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/Microsoft.CSharp/CSharpCodeProvider/GenerateCodeFromMember/module1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/Microsoft.CSharp/CSharpCodeProvider/GenerateCodeFromMember/module1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.CodeDom/CodeThrowExceptionStatement.xml b/xml/System.CodeDom/CodeThrowExceptionStatement.xml index 92d39136aa4..ca1a4ef3357 100644 --- a/xml/System.CodeDom/CodeThrowExceptionStatement.xml +++ b/xml/System.CodeDom/CodeThrowExceptionStatement.xml @@ -54,7 +54,7 @@ ## Remarks can represent a statement that throws an exception. The expression should be, or evaluate to, a reference to an instance of a type that derives from the class. - The property specifies the exception to throw. + The property specifies the exception to throw. diff --git a/xml/System.CodeDom/CodeTryCatchFinallyStatement.xml b/xml/System.CodeDom/CodeTryCatchFinallyStatement.xml index 4ea49625671..fda171fa112 100644 --- a/xml/System.CodeDom/CodeTryCatchFinallyStatement.xml +++ b/xml/System.CodeDom/CodeTryCatchFinallyStatement.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent a `try`/`catch` block of code. - The property contains the statements to execute within a `try` block. The property contains the `catch` clauses to handle caught exceptions. The property contains the statements to execute within a `finally` block. + The property contains the statements to execute within a `try` block. The property contains the `catch` clauses to handle caught exceptions. The property contains the statements to execute within a `finally` block. > [!NOTE] > Not all languages support `try`/`catch` blocks. Call the method with the flag to determine whether a code generator supports `try`/`catch` blocks. diff --git a/xml/System.CodeDom/CodeTypeDeclaration.xml b/xml/System.CodeDom/CodeTypeDeclaration.xml index d1eeca73705..bc1fb1b7a3d 100644 --- a/xml/System.CodeDom/CodeTypeDeclaration.xml +++ b/xml/System.CodeDom/CodeTypeDeclaration.xml @@ -54,12 +54,12 @@ ## Remarks can be used to represent code that declares a class, structure, interface, or enumeration. can be used to declare a type that is nested within another type. - The property specifies the base type or base types of the type being declared. The property contains the type members, which can include methods, fields, properties, comments and other types. The property indicates the values for the type declaration, which indicate the type category of the type. The , , , and methods indicate whether the type is a class, structure, enumeration, or interface type, respectively. + The property specifies the base type or base types of the type being declared. The property contains the type members, which can include methods, fields, properties, comments and other types. The property indicates the values for the type declaration, which indicate the type category of the type. The , , , and methods indicate whether the type is a class, structure, enumeration, or interface type, respectively. > [!NOTE] > Some programming languages only support the declaration of reference types, or classes. To check a language-specific CodeDOM code generator for support for declaring interfaces, enumerations, or value types, call the method to test for the appropriate flags. indicates support for interfaces, indicates support for enumerations, and indicates support for value types such as structures. - You can build a class or a structure implementation in one complete declaration, or spread the implementation across multiple declarations. The property indicates whether the type declaration is complete or partial. Not all code generators support partial type declarations, so you should test for this support by calling the method with the flag . + You can build a class or a structure implementation in one complete declaration, or spread the implementation across multiple declarations. The property indicates whether the type declaration is complete or partial. Not all code generators support partial type declarations, so you should test for this support by calling the method with the flag . @@ -387,7 +387,7 @@ Implements Interface1 property to `false`, which indicates that the type declaration represents all details for the class or structure implementation. + You can build a class or structure implementation in one complete declaration, or spread the implementation across multiple declarations. Implementations are commonly supplied in one complete type declaration. In this case, set the type declaration property to `false`, which indicates that the type declaration represents all details for the class or structure implementation. A partial type declaration makes it easier to build different portions of a class or structure implementation in different modules of your application. The partial type declarations can be stored in one source file, or spread across multiple source files that are eventually compiled together to form the combined type implementation. @@ -396,19 +396,19 @@ Implements Interface1 > [!NOTE] > Partial type declarations are supported for classes and structures. If you specify a partial type declaration for an enumeration or interface, the generated code produces compiler errors. - When supplying a class or structure implementation across multiple declarations, set the property to `true` for the initial declaration and all supplemental declarations. The initial declaration must fully specify the type signature, including access modifiers, inherited types, and implemented interfaces. The supplementary declarations do not need to re-specify the type signature. A compiler error typically results if you redefine the type signature in a supplementary declaration. + When supplying a class or structure implementation across multiple declarations, set the property to `true` for the initial declaration and all supplemental declarations. The initial declaration must fully specify the type signature, including access modifiers, inherited types, and implemented interfaces. The supplementary declarations do not need to re-specify the type signature. A compiler error typically results if you redefine the type signature in a supplementary declaration. Visual Studio 2005 uses partial types to separate user-generated code from designer code. In Visual Basic Windows Application projects, the user code is placed in a partial class that is not qualified by the `Partial` keyword; the designer-provided code appears in the partial class that has the `Partial` keyword. In C#, both the user code and designer code appear in partial classes identified by the `partial` keyword. ## Examples - This example demonstrates using a to supply a class implementation across multiple declarations. The example builds the initial class declaration statement and sets the property to `true`. + This example demonstrates using a to supply a class implementation across multiple declarations. The example builds the initial class declaration statement and sets the property to `true`. :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeTypeDeclaration/IsPartial/source.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeTypeDeclaration/IsPartial/source.vb" id="Snippet3"::: - A different method in the example extends the class implementation. This method builds a new type declaration statement for the existing class and sets the property to `true`. The compiler combines the two partial type declarations together for the complete class implementation. + A different method in the example extends the class implementation. This method builds a new type declaration statement for the existing class and sets the property to `true`. The compiler combines the two partial type declarations together for the complete class implementation. :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeTypeDeclaration/IsPartial/source.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeTypeDeclaration/IsPartial/source.vb" id="Snippet7"::: @@ -615,10 +615,10 @@ Implements Interface1 The property contains the same type of values used by when investigating a type at run time. Many of these flags do not correspond to the type declaration syntax for some languages. As a result, only the following flags are significant to : , , , , , , , and . > [!NOTE] -> Some of the flags such as overlap with the meaning of flags in the property of that is inherited from . The property is a side effect of the class inheriting from so that classes can be nested. The flags in the property should be used instead of the flags in the property. +> Some of the flags such as overlap with the meaning of flags in the property of that is inherited from . The property is a side effect of the class inheriting from so that classes can be nested. The flags in the property should be used instead of the flags in the property. > [!NOTE] -> The pattern for setting the visibility flags (flags containing the words `Public` or `Nested`) is to mask out all visibility flags using the and then set the desired visibility flag. For example, the C# code statement to identify the (named `cd`) as an internal class is `cd.TypeAttributes = (cd.TypeAttributes & ~TypeAttributes.VisibilityMask) | TypeAttributes.NotPublic;`. The code to set the same value in Visual Basic is `cd.TypeAttributes = (cd.TypeAttributes And (TypeAttributes.VisibilityMask Xor -1)) Or TypeAttributes.NotPublic`. Setting the property directly to a visibility flag (`cd.TypeAttributes = TypeAttributes.NotPublic;`) erases all other flags that might be set. +> The pattern for setting the visibility flags (flags containing the words `Public` or `Nested`) is to mask out all visibility flags using the and then set the desired visibility flag. For example, the C# code statement to identify the (named `cd`) as an internal class is `cd.TypeAttributes = (cd.TypeAttributes & ~TypeAttributes.VisibilityMask) | TypeAttributes.NotPublic;`. The code to set the same value in Visual Basic is `cd.TypeAttributes = (cd.TypeAttributes And (TypeAttributes.VisibilityMask Xor -1)) Or TypeAttributes.NotPublic`. Setting the property directly to a visibility flag (`cd.TypeAttributes = TypeAttributes.NotPublic;`) erases all other flags that might be set. ]]> diff --git a/xml/System.CodeDom/CodeTypeDelegate.xml b/xml/System.CodeDom/CodeTypeDelegate.xml index 03658b24b5f..ac69bbf1c62 100644 --- a/xml/System.CodeDom/CodeTypeDelegate.xml +++ b/xml/System.CodeDom/CodeTypeDelegate.xml @@ -54,7 +54,7 @@ ## Remarks can be used to declare a delegate type, or event handler. A delegate defines a method signature that can be used by callback methods or event handlers. Delegates can be declared at the namespace level or nested inside other types. Delegates cannot be nested inside other delegates. - The property specifies the data type of the event handler returned by the delegate. The property contains the parameters for the delegate type. + The property specifies the data type of the event handler returned by the delegate. The property contains the parameters for the delegate type. should not be used for enumeration, interface, or type declaration. Instead, use for those. diff --git a/xml/System.CodeDom/CodeTypeMember.xml b/xml/System.CodeDom/CodeTypeMember.xml index 3e11b45d782..af1e8ba7bc8 100644 --- a/xml/System.CodeDom/CodeTypeMember.xml +++ b/xml/System.CodeDom/CodeTypeMember.xml @@ -49,11 +49,11 @@ Provides a base class for a member of a type. Type members include fields, methods, properties, constructors and nested types. - class can be used to represent the declaration for a member of a type. is a base class from which more specific types of members are derived, such as and . This class contains properties and methods common to all type members. - + class can be used to represent the declaration for a member of a type. is a base class from which more specific types of members are derived, such as and . This class contains properties and methods common to all type members. + ]]> @@ -135,13 +135,13 @@ Gets or sets the attributes of the member. A bitwise combination of the values used to indicate the attributes of the member. The default value is | . - , , , , and . The mask identifies the access attributes. The mask identifies the scope attributes. The default value for the property includes flags from both access and scope. To change either access or scope, first mask out the existing flags and then set the new value. For example, the code statement to identify a constructor (named `constructor1`) as public is `constructor1.Attributes = (constructor1.Attributes & ~MemberAttributes.AccessMask) | MemberAttributes.Public;`. - + , , , , and . The mask identifies the access attributes. The mask identifies the scope attributes. The default value for the property includes flags from both access and scope. To change either access or scope, first mask out the existing flags and then set the new value. For example, the code statement to identify a constructor (named `constructor1`) as public is `constructor1.Attributes = (constructor1.Attributes & ~MemberAttributes.AccessMask) | MemberAttributes.Public;`. + ]]> @@ -186,11 +186,11 @@ Gets the collection of comments for the type member. A that indicates the comments for the member. - @@ -235,14 +235,14 @@ Gets or sets the custom attributes of the member. A that indicates the custom attributes of the member. - [!CAUTION] -> This property is `null` by default and should be checked for content before being referenced. - +> This property is `null` by default and should be checked for content before being referenced. + ]]> @@ -325,14 +325,14 @@ Gets or sets the line on which the type member statement occurs. A object that indicates the location of the type member declaration. - [!CAUTION] -> This value is `null` by default and should be checked for content before being referenced. - +> This value is `null` by default and should be checked for content before being referenced. + ]]> diff --git a/xml/System.CodeDom/CodeTypeOfExpression.xml b/xml/System.CodeDom/CodeTypeOfExpression.xml index a042e610652..470fff08b11 100644 --- a/xml/System.CodeDom/CodeTypeOfExpression.xml +++ b/xml/System.CodeDom/CodeTypeOfExpression.xml @@ -54,7 +54,7 @@ ## Remarks A represents a `typeof` expression that returns a at runtime. - The property specifies the data type to return a object for. + The property specifies the data type to return a object for. Use to represent source code that refers to a type by name, such as when creating a to cast an object to a name-specified type. diff --git a/xml/System.CodeDom/CodeTypeParameter.xml b/xml/System.CodeDom/CodeTypeParameter.xml index 75d759e95d4..820edd5e2de 100644 --- a/xml/System.CodeDom/CodeTypeParameter.xml +++ b/xml/System.CodeDom/CodeTypeParameter.xml @@ -48,23 +48,23 @@ Represents a type parameter of a generic type or method. - class represents a type parameter in the declaration of a generic type or method. - - A generic type or method declaration contains one or more unspecified types known as type parameters. A type parameter name stands for the type within the body of the generic declaration. For example, the generic declaration for the class contains the type parameter `T`. - - For more information on generics, see [Generics in the .NET Framework Class Library](/dotnet/csharp/programming-guide/generics/generics-in-the-net-framework-class-library). - - - -## Examples - The following code example shows the use of the class to create a CodeDOM graph to generate an application containing generics code. - + class represents a type parameter in the declaration of a generic type or method. + + A generic type or method declaration contains one or more unspecified types known as type parameters. A type parameter name stands for the type within the body of the generic declaration. For example, the generic declaration for the class contains the type parameter `T`. + + For more information on generics, see [Generics in the .NET Framework Class Library](/dotnet/csharp/programming-guide/generics/generics-in-the-net-framework-class-library). + + + +## Examples + The following code example shows the use of the class to create a CodeDOM graph to generate an application containing generics code. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet1"::: + ]]> @@ -112,11 +112,11 @@ Initializes a new instance of the class. - property. - + property. + ]]> @@ -159,14 +159,14 @@ The name of the type parameter. Initializes a new instance of the class with the specified type parameter name. - constructor to add a type parameter. This example is part of a larger example provided for the class. - + constructor to add a type parameter. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet10"::: + ]]> @@ -203,19 +203,19 @@ Gets the constraints for the type parameter. A object that contains the constraints for the type parameter. - property to add a new constraint. This example is part of a larger example provided for the class. - + property to add a new constraint. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet4"::: + ]]> @@ -252,22 +252,22 @@ Gets the custom attributes of the type parameter. A that indicates the custom attributes of the type parameter. The default is . - [!CAUTION] -> This property is `null` by default and should be checked before referencing. - - - -## Examples - The following code example shows the use of the property to add a new custom attribute. This example is part of a larger example provided for the class. - +> This property is `null` by default and should be checked before referencing. + + + +## Examples + The following code example shows the use of the property to add a new custom attribute. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet5"::: + ]]> @@ -316,19 +316,19 @@ if the type parameter has a constructor constraint; otherwise, . The default is . - property in determining if the type parameter has a constructor constraint. This example is part of a larger example provided for the class. - + property in determining if the type parameter has a constructor constraint. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.CodeDom/CodeDefaultValueExpression/Overview/codedomgenerics.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.CodeDom/CodeTypeReference.xml b/xml/System.CodeDom/CodeTypeReference.xml index 16989694764..fea0ca7c7df 100644 --- a/xml/System.CodeDom/CodeTypeReference.xml +++ b/xml/System.CodeDom/CodeTypeReference.xml @@ -52,11 +52,11 @@ object is used to represent a type for CodeDOM objects. When CodeDOM types have a `Type` property, it is of type . For example, the property is a that represents a field's data type. + A object is used to represent a type for CodeDOM objects. When CodeDOM types have a `Type` property, it is of type . For example, the property is a that represents a field's data type. A can be initialized with a object or a string. It is generally recommended to use a to do this, although it may not always be possible. If initializing an instance of this class with a string, it is strongly recommended to always use fully qualified types, such as "System.Console" instead of just "Console", because not all languages support importing namespaces. Array types can be specified by either passing in a type object for an array or using one of the constructors that accept rank as a parameter. - The property specifies the name of the type to reference. For references to array types, the property indicates the type of the elements of the array, and the property indicates the number of dimensions in the array. + The property specifies the name of the type to reference. For references to array types, the property indicates the type of the elements of the array, and the property indicates the number of dimensions in the array. @@ -489,7 +489,7 @@ property is greater than or equal to 1. + This is disregarded unless the property is greater than or equal to 1. ]]> @@ -582,7 +582,7 @@ > The name of the property may be misleading. This property contains just the type name with any array adornments or generic type arguments removed, not the base or parent type as might be expected. For example, the value for ``System.Collections.Generic.Dictionary`2[[System.String], [System.Collections.Generic.List`1[[System.Int32]]]]`` is ``System.Collections.Generic.Dictionary`2``. ## Representation of Generic Types - The information in this section is intended for CodeDom provider developers and only applies to CLS-compliant languages. The return value can contain generic types. Generic types are formatted with the name of the type followed by a grave accent ("`") followed by a count of the generic type arguments. The generic type arguments can be found in the returned by the property. The values returned by and the associated contain the same content as the value of the type returned by reflection. + The information in this section is intended for CodeDom provider developers and only applies to CLS-compliant languages. The return value can contain generic types. Generic types are formatted with the name of the type followed by a grave accent ("`") followed by a count of the generic type arguments. The generic type arguments can be found in the returned by the property. The values returned by and the associated contain the same content as the value of the type returned by reflection. For example, a constructed where `K` is a string and `V` is a constructed of integers is represented by reflection as the following (with the assembly information removed): @@ -590,27 +590,27 @@ System.Collections.Generic.Dictionary`2[[System.String], [System.Collections.Generic.List`1[[System.Int32]]]] ``` - Recursively parsing the property from the for yields the same strings as the reflection representation above: + Recursively parsing the property from the for yields the same strings as the reflection representation above: -- The property for the parent returns the following: +- The property for the parent returns the following: ``` System.Collections.Generic.Dictionary`2 ``` -- The property for the first object in the collection returns the following: +- The property for the first object in the collection returns the following: ``` System.String ``` -- The property for the second object in the collection returns the following: +- The property for the second object in the collection returns the following: ``` System.Collections.Generic.List`1 ``` -- The property in the object for ``System.Collections.Generic.List`1`` returns the following: +- The property in the object for ``System.Collections.Generic.List`1`` returns the following: ``` System.Int32 @@ -714,7 +714,7 @@ System.Collections.Generic.Dictionary`2[[System.String], [System.Collections.Gen property is a collection of type references to be substituted for the type parameter references of the current generic type. The collection contains all the type arguments for all nested types. For an example, see the property. + The property is a collection of type references to be substituted for the type parameter references of the current generic type. The collection contains all the type arguments for all nested types. For an example, see the property. ]]> diff --git a/xml/System.CodeDom/CodeTypeReferenceExpression.xml b/xml/System.CodeDom/CodeTypeReferenceExpression.xml index ae0392b276f..8f29d77e36f 100644 --- a/xml/System.CodeDom/CodeTypeReferenceExpression.xml +++ b/xml/System.CodeDom/CodeTypeReferenceExpression.xml @@ -54,7 +54,7 @@ ## Remarks can be used to reference a particular data type. - The property specifies the data type to reference. + The property specifies the data type to reference. diff --git a/xml/System.CodeDom/CodeVariableDeclarationStatement.xml b/xml/System.CodeDom/CodeVariableDeclarationStatement.xml index a1989fbad21..7a44c174529 100644 --- a/xml/System.CodeDom/CodeVariableDeclarationStatement.xml +++ b/xml/System.CodeDom/CodeVariableDeclarationStatement.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent code that declares a variable. - The property specifies the type of the variable to declare. The property specifies the name of the variable to declare. The property is optional, and specifies an initialization expression to assign to the variable after it is created. + The property specifies the type of the variable to declare. The property specifies the name of the variable to declare. The property is optional, and specifies an initialization expression to assign to the variable after it is created. > [!NOTE] > Some languages can implement the optional variable initialization expression by making a separate assignment statement after the variable declaration. diff --git a/xml/System.CodeDom/CodeVariableReferenceExpression.xml b/xml/System.CodeDom/CodeVariableReferenceExpression.xml index 81a9eeebcf5..2394899a4b3 100644 --- a/xml/System.CodeDom/CodeVariableReferenceExpression.xml +++ b/xml/System.CodeDom/CodeVariableReferenceExpression.xml @@ -54,7 +54,7 @@ ## Remarks can be used to represent a reference to a local variable. - The property specifies the name of the local variable to reference. + The property specifies the name of the local variable to reference. Use to reference a field. Use to reference a property. Use to reference an event. diff --git a/xml/System.CodeDom/MemberAttributes.xml b/xml/System.CodeDom/MemberAttributes.xml index 2ed008ddf46..f47612c2f03 100644 --- a/xml/System.CodeDom/MemberAttributes.xml +++ b/xml/System.CodeDom/MemberAttributes.xml @@ -54,10 +54,10 @@ The identifiers defined in the enumeration can be used to indicate the scope and access attributes of a class member. > [!NOTE] -> There is no `Virtual` member attribute. A member is declared virtual by setting its member access to Public (`property1.Attributes = MemberAttributes.Public`) without specifying it as Final. The absence of the Final flag makes a member `virtual` in C# (`public virtual`), `overridable` in Visual Basic (`Public Overridable`). To avoid declaring the member as `virtual` or `overridable`, set both the Public and Final flags in the property. See the property for more information on setting member attributes. +> There is no `Virtual` member attribute. A member is declared virtual by setting its member access to Public (`property1.Attributes = MemberAttributes.Public`) without specifying it as Final. The absence of the Final flag makes a member `virtual` in C# (`public virtual`), `overridable` in Visual Basic (`Public Overridable`). To avoid declaring the member as `virtual` or `overridable`, set both the Public and Final flags in the property. See the property for more information on setting member attributes. > [!NOTE] -> The pattern for setting the access flags (flags containing the terms `Public`, `Private`, `Assembly`, or `Family`) is to mask out all access flags using the AccessMask mask and then set the desired access flag. For example, the code statement to identify a constructor (named `constructor1`) as public is `constructor1.Attributes = (constructor1.Attributes & ~MemberAttributes.AccessMask) | MemberAttributes.Public;`. Setting the property directly to an access flag (for example, `constructor1.Attributes = MemberAttributes.Public;`) erases all other flags that might be set. This pattern should also be used for setting the scope flags (Abstract, Final, Static, Override or Const) using the ScopeMask mask. +> The pattern for setting the access flags (flags containing the terms `Public`, `Private`, `Assembly`, or `Family`) is to mask out all access flags using the AccessMask mask and then set the desired access flag. For example, the code statement to identify a constructor (named `constructor1`) as public is `constructor1.Attributes = (constructor1.Attributes & ~MemberAttributes.AccessMask) | MemberAttributes.Public;`. Setting the property directly to an access flag (for example, `constructor1.Attributes = MemberAttributes.Public;`) erases all other flags that might be set. This pattern should also be used for setting the scope flags (Abstract, Final, Static, Override or Const) using the ScopeMask mask. diff --git a/xml/System.Collections.Concurrent/BlockingCollection`1.xml b/xml/System.Collections.Concurrent/BlockingCollection`1.xml index bf5d82b39cb..589ed8f53c0 100644 --- a/xml/System.Collections.Concurrent/BlockingCollection`1.xml +++ b/xml/System.Collections.Concurrent/BlockingCollection`1.xml @@ -119,9 +119,9 @@ represents a collection that allows for thread-safe adding and removal of data. is used as a wrapper for an instance, and allows removal attempts from the collection to block until data is available to be removed. Similarly, you can create a to enforce an upper bound on the number of data elements allowed in the ; addition attempts to the collection may then block until space is available to store the added items. In this manner, is similar to a traditional blocking queue data structure, except that the underlying data storage mechanism is abstracted away as an . - supports bounding and blocking. Bounding means that you can set the maximum capacity of the collection. Bounding is important in certain scenarios because it enables you to control the maximum size of the collection in memory, and it prevents the producing threads from moving too far ahead of the consuming threads.Multiple threads or tasks can add items to the collection concurrently, and if the collection reaches its specified maximum capacity, the producing threads will block until an item is removed. Multiple consumers can remove items concurrently, and if the collection becomes empty, the consuming threads will block until a producer adds an item. A producing thread can call the method to indicate that no more items will be added. Consumers monitor the property to know when the collection is empty and no more items will be added. + supports bounding and blocking. Bounding means that you can set the maximum capacity of the collection. Bounding is important in certain scenarios because it enables you to control the maximum size of the collection in memory, and it prevents the producing threads from moving too far ahead of the consuming threads.Multiple threads or tasks can add items to the collection concurrently, and if the collection reaches its specified maximum capacity, the producing threads will block until an item is removed. Multiple consumers can remove items concurrently, and if the collection becomes empty, the consuming threads will block until a producer adds an item. A producing thread can call the method to indicate that no more items will be added. Consumers monitor the property to know when the collection is empty and no more items will be added. - and operations are typically performed in a loop. You can cancel a loop by passing in a object to the or method, and then checking the value of the token's property on each iteration. If the value is `true`, it is up to you to respond the cancellation request by cleaning up any resources and exiting the loop. + and operations are typically performed in a loop. You can cancel a loop by passing in a object to the or method, and then checking the value of the token's property on each iteration. If the value is `true`, it is up to you to respond the cancellation request by cleaning up any resources and exiting the loop. When you create a object, you can specify not only the bounded capacity but also the type of collection to use. For example, you could specify a object for first in, first out (FIFO) behavior, or a object for last in, first out (LIFO) behavior. You can use any collection class that implements the interface. The default collection type for is . diff --git a/xml/System.Collections.Concurrent/ConcurrentQueue`1.xml b/xml/System.Collections.Concurrent/ConcurrentQueue`1.xml index cbb967d6a4e..73ceb9ea06e 100644 --- a/xml/System.Collections.Concurrent/ConcurrentQueue`1.xml +++ b/xml/System.Collections.Concurrent/ConcurrentQueue`1.xml @@ -108,22 +108,22 @@ The type of the elements contained in the queue. Represents a thread-safe first in-first out (FIFO) collection. - [!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. - - - -## Examples - The following example shows how to use a to enqueue and dequeue items: - +> implements the interface starting with the .NET Framework 4.6; in previous versions of the .NET Framework, the class did not implement this interface. + + + +## Examples + The following example shows how to use a to enqueue and dequeue items: + :::code language="csharp" source="~/snippets/csharp/System.Collections.Concurrent/ConcurrentQueueT/Overview/concqueue.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Concurrent/ConcurrentQueueT/Overview/concqueue.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Collections.Concurrent/ConcurrentQueueT/Overview/concqueue.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Collections.Concurrent/ConcurrentQueueT/Overview/concqueue.vb" id="Snippet1"::: + ]]> All public and protected members of are thread-safe and may be used concurrently from multiple threads. @@ -357,11 +357,11 @@ Gets the number of elements contained in the . The number of elements contained in the . - property is recommended rather than retrieving the number of items from the property and comparing it to 0. - + property is recommended rather than retrieving the number of items from the property and comparing it to 0. + ]]> Thread-Safe Collections @@ -455,13 +455,13 @@ Returns an enumerator that iterates through the . An enumerator for the contents of the . - was called. The enumerator is safe to use concurrently with reads from and writes to the queue. - - The enumerator returns the collection elements in the order in which they were added, which is FIFO order (first-in, first-out). - + was called. The enumerator is safe to use concurrently with reads from and writes to the queue. + + The enumerator returns the collection elements in the order in which they were added, which is FIFO order (first-in, first-out). + ]]> Thread-Safe Collections @@ -507,11 +507,11 @@ if the is empty; otherwise, . - property and comparing it to 0. However, as this collection is intended to be accessed concurrently, it may be the case that another thread will modify the collection after returns, thus invalidating the result. - + property and comparing it to 0. However, as this collection is intended to be accessed concurrently, it may be the case that another thread will modify the collection after returns, thus invalidating the result. + ]]> Thread-Safe Collections @@ -564,11 +564,11 @@ if the object was added successfully; otherwise, . - , this operation will always add the object to the end of the and return true. - + , this operation will always add the object to the end of the and return true. + ]]> Thread-Safe Collections @@ -628,11 +628,11 @@ if an element was removed and returned successfully; otherwise, . - , this operation will attempt to remove the object from the beginning of the . - + , this operation will attempt to remove the object from the beginning of the . + ]]> Thread-Safe Collections @@ -952,13 +952,13 @@ This member is an explicit interface member implementation. It can be used only if an element was removed and returned from the beginning of the successfully; otherwise, . - handles all synchronization internally. If two threads call at precisely the same moment, neither operation is blocked. When a conflict is detected between two threads, one thread has to try again to retrieve the next element, and the synchronization is handled internally. - - tries to remove an element from the queue. If the method is successful, the item is removed and the method returns `true`; otherwise, it returns `false`. That happens atomically with respect to other operations on the queue. If the queue was populated with code such as `q.Enqueue("a"); q.Enqueue("b"); q.Enqueue("c");` and two threads concurrently try to dequeue an element, one thread will dequeue `a` and the other thread will dequeue `b`. Both calls to will return `true`, because they were both able to dequeue an element. If each thread goes back to dequeue an additional element, one of the threads will dequeue `c` and return `true`, whereas the other thread will find the queue empty and will return `false`. - + handles all synchronization internally. If two threads call at precisely the same moment, neither operation is blocked. When a conflict is detected between two threads, one thread has to try again to retrieve the next element, and the synchronization is handled internally. + + tries to remove an element from the queue. If the method is successful, the item is removed and the method returns `true`; otherwise, it returns `false`. That happens atomically with respect to other operations on the queue. If the queue was populated with code such as `q.Enqueue("a"); q.Enqueue("b"); q.Enqueue("c");` and two threads concurrently try to dequeue an element, one thread will dequeue `a` and the other thread will dequeue `b`. Both calls to will return `true`, because they were both able to dequeue an element. If each thread goes back to dequeue an additional element, one of the threads will dequeue `c` and return `true`, whereas the other thread will find the queue empty and will return `false`. + ]]> Thread-Safe Collections diff --git a/xml/System.Collections.Concurrent/ConcurrentStack`1.xml b/xml/System.Collections.Concurrent/ConcurrentStack`1.xml index 5cdb808a95d..e44a6493301 100644 --- a/xml/System.Collections.Concurrent/ConcurrentStack`1.xml +++ b/xml/System.Collections.Concurrent/ConcurrentStack`1.xml @@ -367,7 +367,7 @@ property is recommended rather than retrieving the number of items from the property and comparing it to 0. + For determining whether the collection contains any items, use of the property is recommended rather than retrieving the number of items from the property and comparing it to 0. ]]> @@ -469,7 +469,7 @@ property and comparing it to 0. However, as this collection is intended to be accessed concurrently, it may be the case that another thread will modify the collection after returns, thus invalidating the result. + For determining whether the collection contains any items, use of this property is recommended rather than retrieving the number of items from the property and comparing it to 0. However, as this collection is intended to be accessed concurrently, it may be the case that another thread will modify the collection after returns, thus invalidating the result. For a code example, see . diff --git a/xml/System.Collections.Concurrent/OrderablePartitioner`1.xml b/xml/System.Collections.Concurrent/OrderablePartitioner`1.xml index 1d968404bf1..da5de150f0a 100644 --- a/xml/System.Collections.Concurrent/OrderablePartitioner`1.xml +++ b/xml/System.Collections.Concurrent/OrderablePartitioner`1.xml @@ -66,19 +66,19 @@ Type of the elements in the collection. Represents a particular manner of splitting an orderable data source into multiple partitions. - All public members of are thread-safe and may be called from multiple threads concurrently. @@ -129,11 +129,11 @@ Indicates whether keys are normalized. If true, all order keys are distinct integers in the range [0 .. numberOfElements-1]. If false, order keys must still be distinct, but only their relative order is considered, not their absolute values. Called from constructors in derived classes to initialize the class with the specified constraints on the index keys. - Custom Partitioners for PLINQ and TPL @@ -182,17 +182,17 @@ Creates an object that can partition the underlying collection into a variable number of partitions. An object that can create partitions over the underlying data source. - interface. Calling on the object creates another partition over the sequence. - - The default implementation provides the same behavior as except that the returned set of partitions does not provide the keys for the elements. - - The method is only supported if the property returns true. - - For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). - + interface. Calling on the object creates another partition over the sequence. + + The default implementation provides the same behavior as except that the returned set of partitions does not provide the keys for the elements. + + The method is only supported if the property returns true. + + For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). + ]]> Dynamic partitioning is not supported by the base class. It must be implemented in derived classes. @@ -242,17 +242,17 @@ Creates an object that can partition the underlying collection into a variable number of partitions. An object that can create partitions over the underlying data source. - interface. Calling on the object creates another partition over the sequence. - - Each partition is represented as an enumerator over key-value pairs. The value in the pair is the element itself, and the key is an integer which determines the relative ordering of this element against other elements. - - The method is only supported if the property returns true. - - For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). - + interface. Calling on the object creates another partition over the sequence. + + Each partition is represented as an enumerator over key-value pairs. The value in the pair is the element itself, and the key is an integer which determines the relative ordering of this element against other elements. + + The method is only supported if the property returns true. + + For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). + ]]> Dynamic partitioning is not supported by this partitioner. @@ -305,15 +305,15 @@ Partitions the underlying collection into the specified number of orderable partitions. A list containing enumerators. - Custom Partitioners for PLINQ and TPL @@ -365,13 +365,13 @@ Partitions the underlying collection into the given number of ordered partitions. A list containing enumerators. - except that the returned set of partitions does not provide the keys for the elements. - - For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). - + except that the returned set of partitions does not provide the keys for the elements. + + For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). + ]]> Custom Partitioners for PLINQ and TPL @@ -420,13 +420,13 @@ if the keys are normalized; otherwise, . - returns true, all order keys are distinct integers in the range [0 .. numberOfElements-1]. If the property returns false, order keys must still be distinct, but only their relative order is considered, not their absolute values. - - For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). - + returns true, all order keys are distinct integers in the range [0 .. numberOfElements-1]. If the property returns false, order keys must still be distinct, but only their relative order is considered, not their absolute values. + + For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). + ]]> @@ -471,13 +471,13 @@ if the elements in an earlier partition always come before elements in a later partition; otherwise, . - returns true, each element in partition 0 has a smaller order key than any element in partition 1, each element in partition 1 has a smaller order key than any element in partition 2, and so on. - - For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). - + returns true, each element in partition 0 has a smaller order key than any element in partition 1, each element in partition 1 has a smaller order key than any element in partition 2, and so on. + + For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). + ]]> Custom Partitioners for PLINQ and TPL @@ -526,11 +526,11 @@ if the elements in each partition are yielded in the order of increasing keys; otherwise, . - Custom Partitioners for PLINQ and TPL diff --git a/xml/System.Collections.Concurrent/Partitioner`1.xml b/xml/System.Collections.Concurrent/Partitioner`1.xml index 9746b7127ff..d254d19f606 100644 --- a/xml/System.Collections.Concurrent/Partitioner`1.xml +++ b/xml/System.Collections.Concurrent/Partitioner`1.xml @@ -63,19 +63,19 @@ Type of the elements in the collection. Represents a particular manner of splitting a data source into multiple partitions. - The static methods on are all thread-safe and may be used concurrently from multiple threads. However, while a created partitioner is in use, the underlying data source should not be modified, whether from the same thread that is using a partitioner or from a separate thread. @@ -163,13 +163,13 @@ Creates an object that can partition the underlying collection into a variable number of partitions. An object that can create partitions over the underlying data source. - interface. Calling on the object creates another partition over the sequence. - - The method is only supported if the property returns true. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). - + interface. Calling on the object creates another partition over the sequence. + + The method is only supported if the property returns true. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). + ]]> Dynamic partitioning is not supported by the base class. You must implement it in a derived class. @@ -221,11 +221,11 @@ Partitions the underlying collection into the given number of partitions. A list containing enumerators. - @@ -273,11 +273,11 @@ if the can create partitions dynamically as they are requested; if the can only allocate partitions statically. - , should return false. The value of should not vary over the lifetime of this instance. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). - + , should return false. The value of should not vary over the lifetime of this instance. For more information, see [Custom Partitioners for PLINQ and TPL](/dotnet/standard/parallel-programming/custom-partitioners-for-plinq-and-tpl). + ]]> diff --git a/xml/System.Collections.Generic/Comparer`1.xml b/xml/System.Collections.Generic/Comparer`1.xml index 4d1800c0bcb..90955327145 100644 --- a/xml/System.Collections.Generic/Comparer`1.xml +++ b/xml/System.Collections.Generic/Comparer`1.xml @@ -89,7 +89,7 @@ - To define a comparer to use instead of the default comparer, derive from the class. You can then use this comparer in sort operations that take a comparer as a parameter. - The object returned by the property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, the property returns a that uses the interface. + The object returned by the property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, the property returns a that uses the interface. @@ -364,7 +364,7 @@ The returned by this property uses the generic interface (`IComparable` in C#, `IComparable(Of T)` in Visual Basic) to compare two objects. If type `T` does not implement the generic interface, this property returns a that uses the interface. ## Examples - The following example shows how to use the property to get an object that performs the default comparison. This example is part of a larger example provided for the class. + The following example shows how to use the property to get an object that performs the default comparison. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ComparerT/Overview/program.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/ComparerT/Overview/program.fs" id="Snippet3"::: diff --git a/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml b/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml index c057812e374..9f0f840042a 100644 --- a/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml +++ b/xml/System.Collections.Generic/Dictionary`2+Enumerator.xml @@ -166,7 +166,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -337,7 +337,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -409,7 +409,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -482,7 +482,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -556,7 +556,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -619,7 +619,7 @@ method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + After calling the method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . diff --git a/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml b/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml index 0ce97e5a21e..f4b6170c277 100644 --- a/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml +++ b/xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml @@ -161,7 +161,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -344,7 +344,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -408,7 +408,7 @@ method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + After calling the method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to or throws an . diff --git a/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml b/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml index 3d41632e16d..0b543860e2a 100644 --- a/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml +++ b/xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml @@ -103,7 +103,7 @@ property returns an instance of this type, containing all the keys in that . The order of the keys in the is unspecified, but it is the same order as the associated values in the returned by the property. + The property returns an instance of this type, containing all the keys in that . The order of the keys in the is unspecified, but it is the same order as the associated values in the returned by the property. The is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . @@ -938,7 +938,7 @@ 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. + 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. ```csharp ICollection ic = ...; diff --git a/xml/System.Collections.Generic/Dictionary`2+ValueCollection+Enumerator.xml b/xml/System.Collections.Generic/Dictionary`2+ValueCollection+Enumerator.xml index 5626f75ddc6..7680f479af1 100644 --- a/xml/System.Collections.Generic/Dictionary`2+ValueCollection+Enumerator.xml +++ b/xml/System.Collections.Generic/Dictionary`2+ValueCollection+Enumerator.xml @@ -160,7 +160,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -338,7 +338,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -402,7 +402,7 @@ method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + After calling the method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . diff --git a/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml b/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml index aca339ca80c..e6c3dd543ea 100644 --- a/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml +++ b/xml/System.Collections.Generic/Dictionary`2+ValueCollection.xml @@ -103,7 +103,7 @@ property returns an instance of this type, containing all the values in that . The order of the values in the is unspecified, but it is the same order as the associated keys in the returned by the property. + The property returns an instance of this type, containing all the values in that . The order of the values in the is unspecified, but it is the same order as the associated keys in the returned by the property. The is not a static copy; instead, the refers back to the values in the original . Therefore, changes to the continue to be reflected in the . @@ -915,7 +915,7 @@ 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, which 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. + returns an object, which 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. ```csharp ICollection ic = ...; diff --git a/xml/System.Collections.Generic/Dictionary`2.xml b/xml/System.Collections.Generic/Dictionary`2.xml index 4fa445ea0b8..92079ccc4c8 100644 --- a/xml/System.Collections.Generic/Dictionary`2.xml +++ b/xml/System.Collections.Generic/Dictionary`2.xml @@ -169,11 +169,11 @@ The following code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - The example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. The example shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary, and it shows how to use the method to test whether a key exists before calling the method. - The example shows how to enumerate the keys and values in the dictionary and how to enumerate the keys and values alone using the property and the property. + The example shows how to enumerate the keys and values in the dictionary and how to enumerate the keys and values alone using the property and the property. Finally, the example demonstrates the method. @@ -889,9 +889,9 @@ property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection[myKey] = myValue` (in Visual Basic, `myCollection(myKey) = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method throws an exception if a value with the specified key already exists. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection[myKey] = myValue` (in Visual Basic, `myCollection(myKey) = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method throws an exception if a value with the specified key already exists. - If the property value already equals the capacity, 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 the property value already equals the capacity, 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. A key cannot be `null`, but a value can be, if `TValue` is a reference type. @@ -996,7 +996,7 @@ property is set to 0, and references to other objects from elements of the collection are also released. The capacity remains unchanged. + The property is set to 0, and references to other objects from elements of the collection are also released. The capacity remains unchanged. This method is an O(`n`) operation, where `n` is the capacity of the dictionary. @@ -1116,7 +1116,7 @@ ## Examples - The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method to retrieve values, which is an efficient way to retrieve values when a program frequently tries keys that are not in the dictionary. Finally, it shows the least efficient way to test whether keys exist, by using the property (the indexer in C#). + The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method to retrieve values, which is an efficient way to retrieve values when a program frequently tries keys that are not in the dictionary. Finally, it shows the least efficient way to test whether keys exist, by using the property (the indexer in C#). This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). @@ -1245,7 +1245,7 @@ is the number of elements that the can store. The property is the number of elements that are actually in the . + The capacity of a is the number of elements that the can store. The property is the number of elements that are actually in the . The capacity is always greater than or equal to . If exceeds the capacity while adding elements, the capacity is increased by automatically reallocating the internal array before copying the old elements and adding the new elements. @@ -1395,7 +1395,7 @@ Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . - The property returns the same element until the method is called. sets to the next element. + The property returns the same element until the method 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. @@ -1544,11 +1544,11 @@ ## Remarks This property provides the ability to access a specific element in the collection by using the following C# syntax: `myCollection[key]` (`myCollection(key)` in Visual Basic). - You can also use the property to add new elements by setting the value of a key that does not exist in the . When you set the property value, if the key is in the , the value associated with that key is replaced by the assigned value. If the key is not in the , the key and value are added to the dictionary. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the . When you set the property value, if the key is in the , the value associated with that key is replaced by the assigned value. If the key is not in the , the key and value are added to the dictionary. In contrast, the method does not modify existing elements. A key cannot be `null`, but a value can be, if the value type `TValue` is a reference type. - 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. + 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. Getting or setting the value of this property approaches an O(1) operation. @@ -1556,7 +1556,7 @@ ## Examples - The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. @@ -1627,7 +1627,7 @@ is unspecified, but it is the same order as the associated values in the returned by the property. + The order of the keys in the is unspecified, but it is the same order as the associated values in the returned by the property. The returned is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . @@ -1636,7 +1636,7 @@ ## Examples - The following code example shows how to enumerate the keys in the dictionary using the property, and how to enumerate the keys and values in the dictionary. + The following code example shows how to enumerate the keys in the dictionary using the property, and how to enumerate the keys and values in the dictionary. This code is part of a larger example that can be compiled and executed (`openWith` is the name of the Dictionary used in this example). See . @@ -2459,7 +2459,7 @@ Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which can cause the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. + The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. Getting the value of this property is an O(1) operation. @@ -2519,7 +2519,7 @@ 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. - The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. The following code shows the use of the property. + The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. The following code shows the use of the property. ```csharp ICollection ic = ...; @@ -2595,7 +2595,7 @@ Getting the value of this property is an O(1) operation. ## Remarks - You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method throws an exception if the specified key already exists. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method throws an exception if the specified key already exists. If is less than the capacity, this method approaches 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 . @@ -2753,7 +2753,7 @@ Getting the value of this property is an O(1) operation. Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, 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 element until either the or method is called. sets to the next element. + The property returns the same element until either the or method 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 . @@ -2958,16 +2958,16 @@ Getting the value of this property is an O(1) operation. ## Remarks This property provides the ability to access a specific value in the collection by using the following C# syntax: `myCollection[key]` (`myCollection(key)` in Visual Basic). - You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - 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. + 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. Getting or setting the value of this property approaches an O(1) operation. ## Examples - The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. + The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. - The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the dictionary. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the dictionary, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. + The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the dictionary. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the dictionary, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Item/source.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Item/source.fs"::: @@ -3032,14 +3032,14 @@ Getting the value of this property is an O(1) operation. is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. + The order of the keys in the returned is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. Getting the value of this property is an O(1) operation. ## Examples - The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Keys/source.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Keys/source.fs"::: @@ -3164,14 +3164,14 @@ Getting the value of this property is an O(1) operation. is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. + The order of the values in the returned is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. Getting the value of this property is an O(1) operation. ## Examples - The following code example shows how to use the property of the interface with a , to list the values in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the values in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Values/source.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/DictionaryTKey,TValue/System.Collections.IDictionary.Values/source.fs"::: @@ -3235,9 +3235,9 @@ Getting the value of this property is an O(1) operation. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. The method 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 . + Initially, the enumerator is positioned before the first element in the collection. The method 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 element until either the or method is called. sets to the next element. + The property returns the same element until either the or method 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 . @@ -3509,18 +3509,18 @@ Unlike the method, this method and the property. + This method combines the functionality of the method and the property. If the key is not found, then the `value` parameter gets the appropriate default value for the type `TValue`; for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. - Use the method if your code frequently attempts to access keys that are not in the dictionary. Using this method is more efficient than catching the thrown by the property. + Use the method if your code frequently attempts to access keys that are not in the dictionary. Using this method is more efficient than catching the thrown by the property. This method approaches an O(1) operation. ## Examples - The example shows how to use the method as a more efficient way to retrieve values in a program that frequently tries keys that are not in the dictionary. For contrast, the example also shows how the property (the indexer in C#) throws exceptions when attempting to retrieve nonexistent keys. + The example shows how to use the method as a more efficient way to retrieve values in a program that frequently tries keys that are not in the dictionary. For contrast, the example also shows how the property (the indexer in C#) throws exceptions when attempting to retrieve nonexistent keys. This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). @@ -3583,7 +3583,7 @@ Unlike the method, this is unspecified, but it is the same order as the associated keys in the returned by the property. + The order of the values in the is unspecified, but it is the same order as the associated keys in the returned by the property. The returned is not a static copy; instead, the refers back to the values in the original . Therefore, changes to the continue to be reflected in the . @@ -3592,7 +3592,7 @@ Unlike the method, this ## Examples - This code example shows how to enumerate the values in the dictionary using the property, and how to enumerate the keys and values in the dictionary. + This code example shows how to enumerate the values in the dictionary using the property, and how to enumerate the keys and values in the dictionary. This code example is part of a larger example provided for the class (`openWith` is the name of the Dictionary used in this example). diff --git a/xml/System.Collections.Generic/EqualityComparer`1.xml b/xml/System.Collections.Generic/EqualityComparer`1.xml index 8dc8f469b83..e2b4f800909 100644 --- a/xml/System.Collections.Generic/EqualityComparer`1.xml +++ b/xml/System.Collections.Generic/EqualityComparer`1.xml @@ -78,21 +78,21 @@ The type of objects to compare. Provides a base class for implementations of the generic interface. - generic interface for use with collection classes such as the generic class, or with methods such as . -The property checks whether type `T` implements the generic interface and, if so, returns an that invokes the implementation of the method. Otherwise, it returns an , as provided by `T`. +The property checks whether type `T` implements the generic interface and, if so, returns an that invokes the implementation of the method. Otherwise, it returns an , as provided by `T`. In .NET 8 and later versions, we recommend using the method to create instances of this type. -## Examples - The following example creates a dictionary collection of objects of type `Box` with an equality comparer. Two boxes are considered equal if their dimensions are the same. It then adds the boxes to the collection. - - The dictionary is recreated with an equality comparer that defines equality in a different way: Two boxes are considered equal if their volumes are the same. - +## Examples + The following example creates a dictionary collection of objects of type `Box` with an equality comparer. Two boxes are considered equal if their dimensions are the same. It then adds the boxes to the collection. + + The dictionary is recreated with an equality comparer that defines equality in a different way: Two boxes are considered equal if their volumes are the same. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/EqualityComparerT/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/EqualityComparerT/Overview/program.vb" id="Snippet1"::: @@ -243,20 +243,20 @@ In .NET 8 and later versions, we recommend using the Returns a default equality comparer for the type specified by the generic argument. The default instance of the class for type . - property checks whether type `T` implements the interface and, if so, returns an that uses that implementation. Otherwise, it returns an that uses the overrides of and provided by `T`. - - - -## Examples + property checks whether type `T` implements the interface and, if so, returns an that uses that implementation. Otherwise, it returns an that uses the overrides of and provided by `T`. + + + +## Examples The following example creates a collection that contains elements of the `Box` type and then searches it for a box matching another box by calling the `FindFirst` method, twice. - + The first search does not specify any equality comparer, which means `FindFirst` uses to determine equality of boxes. That in turn uses the implementation of the method in the `Box` class. Two boxes are considered equal if their dimensions are the same. - + The second search specifies an equality comparer (`BoxEqVolume`) that defines equality by volume. Two boxes are considered equal if their volumes are the same. - + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/EqualityComparerT/Default/program.cs" interactive="try-dotnet"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/EqualityComparerT/Default/program.vb"::: @@ -333,11 +333,11 @@ In .NET 8 and later versions, we recommend using the if the specified objects are equal; otherwise, . - method is reflexive, symmetric, and transitive. That is, it returns `true` if used to compare an object with itself; `true` for two objects `x` and `y` if it is `true` for `y` and `x`; and `true` for two objects `x` and `z` if it is `true` for `x` and `y` and also `true` for `y` and `z`. - + method is reflexive, symmetric, and transitive. That is, it returns `true` if used to compare an object with itself; `true` for two objects `x` and `y` if it is `true` for `y` and `x`; and `true` for two objects `x` and `z` if it is `true` for `x` and `y` and also `true` for `y` and `z`. + ]]> @@ -457,13 +457,13 @@ In .NET 8 and later versions, we recommend using the if the specified objects are equal; otherwise, . - method, so `obj` must be cast to the type specified by the generic argument `T` of the current instance. If it cannot be cast to `T`, an is thrown. - - Comparing `null` is allowed and does not generate an exception. - + method, so `obj` must be cast to the type specified by the generic argument `T` of the current instance. If it cannot be cast to `T`, an is thrown. + + Comparing `null` is allowed and does not generate an exception. + ]]> @@ -518,17 +518,17 @@ In .NET 8 and later versions, we recommend using the Returns a hash code for the specified object. A hash code for the specified object. - method, so `obj` must be a type that can be cast to the type specified by the generic type argument `T` of the current instance. - + method, so `obj` must be a type that can be cast to the type specified by the generic type argument `T` of the current instance. + ]]> - The type of is a reference type and is . - - -or- - + The type of is a reference type and is . + + -or- + is of a type that cannot be cast to type . diff --git a/xml/System.Collections.Generic/HashSet`1+Enumerator.xml b/xml/System.Collections.Generic/HashSet`1+Enumerator.xml index cc9ef685c04..b78a27c2999 100644 --- a/xml/System.Collections.Generic/HashSet`1+Enumerator.xml +++ b/xml/System.Collections.Generic/HashSet`1+Enumerator.xml @@ -83,7 +83,7 @@ Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 . + Initially, the enumerator is positioned before the first element in the collection. 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 . returns the same object until is called. sets to the next element. @@ -159,7 +159,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -334,7 +334,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -394,7 +394,7 @@ , you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + After calling , you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . diff --git a/xml/System.Collections.Generic/HashSet`1.xml b/xml/System.Collections.Generic/HashSet`1.xml index dc82bd91f44..f5f89aba673 100644 --- a/xml/System.Collections.Generic/HashSet`1.xml +++ b/xml/System.Collections.Generic/HashSet`1.xml @@ -1401,9 +1401,9 @@ The following example demonstrates how to merge two disparate sets. This example Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 . + Initially, the enumerator is positioned before the first element in the collection. 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 is called. sets to the next element. + 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. @@ -2467,9 +2467,9 @@ The following example demonstrates how to merge two disparate sets. This example Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 . + Initially, the enumerator is positioned before the first element in the collection. 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 is called. sets to the next element. + 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. @@ -2538,9 +2538,9 @@ The following example demonstrates how to merge two disparate sets. This example Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. 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 . + Initially, the enumerator is positioned before the first element in 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. + 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 . diff --git a/xml/System.Collections.Generic/ICollection`1.xml b/xml/System.Collections.Generic/ICollection`1.xml index a055ee9dc87..572c84982be 100644 --- a/xml/System.Collections.Generic/ICollection`1.xml +++ b/xml/System.Collections.Generic/ICollection`1.xml @@ -66,27 +66,27 @@ The type of the elements in the collection. Defines methods to manipulate generic collections. - interface is the base interface for classes in the namespace. - - The interface extends ; and are more specialized interfaces that extend . A implementation is a collection of key/value pairs, like the class. A implementation is a collection of values, and its members can be accessed by index, like the class. - - If neither the interface nor the interface meet the requirements of the required collection, derive the new collection class from the interface instead for more flexibility. - - - -## Examples - The following example implements the interface to create a collection of custom `Box` objects named `BoxCollection`. Each `Box` has height, length, and width properties, which are used to define equality. Equality can be defined as all dimensions being the same or the volume being the same. The `Box` class implements the interface to define the default equality as the dimensions being the same. - - The `BoxCollection` class implements the method to use the default equality to determine whether a `Box` is in the collection. This method is used by the method so that each `Box` added to the collection has a unique set of dimensions. The `BoxCollection` class also provides an overload of the method that takes a specified object, such as `BoxSameDimensions` and `BoxSameVol` classes in the example. - - This example also implements an interface for the `BoxCollection` class so that the collection can be enumerated. - + interface is the base interface for classes in the namespace. + + The interface extends ; and are more specialized interfaces that extend . A implementation is a collection of key/value pairs, like the class. A implementation is a collection of values, and its members can be accessed by index, like the class. + + If neither the interface nor the interface meet the requirements of the required collection, derive the new collection class from the interface instead for more flexibility. + + + +## Examples + The following example implements the interface to create a collection of custom `Box` objects named `BoxCollection`. Each `Box` has height, length, and width properties, which are used to define equality. Equality can be defined as all dimensions being the same or the volume being the same. The `Box` class implements the interface to define the default equality as the dimensions being the same. + + The `BoxCollection` class implements the method to use the default equality to determine whether a `Box` is in the collection. This method is used by the method so that each `Box` added to the collection has a unique set of dimensions. The `BoxCollection` class also provides an overload of the method that takes a specified object, such as `BoxSameDimensions` and `BoxSameVol` classes in the example. + + This example also implements an interface for the `BoxCollection` class so that the collection can be enumerated. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ICollectionT/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ICollectionT/Overview/program.vb" id="Snippet1"::: - + ]]> @@ -187,11 +187,11 @@ Removes all items from the . - must be set to 0, and references to other objects from elements of the collection must be released. - + must be set to 0, and references to other objects from elements of the collection must be released. + ]]> The is read-only. @@ -246,11 +246,11 @@ if is found in the ; otherwise, . - uses , whereas allows the user to specify the implementation to use for comparing keys. - + uses , whereas allows the user to specify the implementation to use for comparing keys. + ]]> @@ -399,11 +399,11 @@ if the is read-only; otherwise, . - interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. - + interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. + ]]> @@ -456,13 +456,13 @@ if was successfully removed from the ; otherwise, . This method also returns if is not found in the original . - uses , whereas, allows the user to specify the implementation to use for comparing keys. - - In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - + uses , whereas, allows the user to specify the implementation to use for comparing keys. + + In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + ]]> The is read-only. diff --git a/xml/System.Collections.Generic/IComparer`1.xml b/xml/System.Collections.Generic/IComparer`1.xml index c4e2736450a..f86e2b0335e 100644 --- a/xml/System.Collections.Generic/IComparer`1.xml +++ b/xml/System.Collections.Generic/IComparer`1.xml @@ -60,25 +60,25 @@ The type of objects to compare. Defines a method that a type implements to compare two objects. - and methods. It provides a way to customize the sort order of a collection. Classes that implement this interface include the and generic classes. - - The default implementation of this interface is the class. The class implements this interface for type . - - This interface supports ordering comparisons. That is, when the method returns 0, it means that two objects sort the same. Implementation of exact equality comparisons is provided by the generic interface. - - We recommend that you derive from the class instead of implementing the interface, because the class provides an explicit interface implementation of the method and the property that gets the default comparer for the object. - - - -## Examples - The following example implements the interface to compare objects of type `Box` according to their dimensions. This example is part of a larger example provided for the class. - + and methods. It provides a way to customize the sort order of a collection. Classes that implement this interface include the and generic classes. + + The default implementation of this interface is the class. The class implements this interface for type . + + This interface supports ordering comparisons. That is, when the method returns 0, it means that two objects sort the same. Implementation of exact equality comparisons is provided by the generic interface. + + We recommend that you derive from the class instead of implementing the interface, because the class provides an explicit interface implementation of the method and the property that gets the default comparer for the object. + + + +## Examples + The following example implements the interface to compare objects of type `Box` according to their dimensions. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ComparerT/Overview/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ComparerT/Overview/program.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ComparerT/Overview/program.vb" id="Snippet7"::: + ]]> @@ -151,41 +151,41 @@ The first object to compare. The second object to compare. Compares two objects and returns a value indicating whether one is less than, equal to, or greater than the other. - A signed integer that indicates the relative values of and , as shown in the following table. - - Value - - Meaning - - 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 + + Meaning + + Less than zero + + is less than . + + Zero + + equals . + + Greater than zero + + is greater than . + - interface to compare objects of type `Box` according to their dimensions. This example is part of a larger example provided for the class. - + interface to compare objects of type `Box` according to their dimensions. This example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ComparerT/Overview/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ComparerT/Overview/program.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ComparerT/Overview/program.vb" id="Snippet7"::: + ]]> diff --git a/xml/System.Collections.Generic/IDictionary`2.xml b/xml/System.Collections.Generic/IDictionary`2.xml index ae3ace54ec6..6566a5a9ce1 100644 --- a/xml/System.Collections.Generic/IDictionary`2.xml +++ b/xml/System.Collections.Generic/IDictionary`2.xml @@ -107,11 +107,11 @@ The code example uses the method to add some elements. The example demonstrates that the method throws when attempting to add a duplicate key. - The example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. The example shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary, and how to use the method to test whether a key exists prior to calling the method. - Finally, the example shows how to enumerate the keys and values in the dictionary, and how to enumerate the values alone using the property. + Finally, the example shows how to enumerate the keys and values in the dictionary, and how to enumerate the values alone using the property. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/IDictionaryTKey,TValue/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/IDictionaryTKey,TValue/Overview/source.vb" id="Snippet1"::: @@ -176,7 +176,7 @@ property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. @@ -258,7 +258,7 @@ Implementations can vary in whether they allow `key` to be `null`. ## Examples - The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method, which can be a more efficient way to retrieve values if a program frequently tries key values that are not in the dictionary. Finally, it shows how to insert items using property (the indexer in C#). + The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method, which can be a more efficient way to retrieve values if a program frequently tries key values that are not in the dictionary. Finally, it shows how to insert items using property (the indexer in C#). This code is part of a larger example that can be compiled and executed. See . @@ -327,18 +327,18 @@ ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[key]` (`myCollection(key)` in Visual Basic). - You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue` in C# (`myCollection("myNonexistentKey") = myValue` in Visual Basic). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. Implementations can vary in how they determine equality of objects; for example, the class uses , whereas the class allows the user to specify the implementation to use for comparing keys. - 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. + 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. Implementations can vary in whether they allow `key` to be `null`. ## Examples - The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. @@ -408,12 +408,12 @@ is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. + The order of the keys in the returned is unspecified, but it is guaranteed to be the same order as the corresponding values in the returned by the property. ## Examples - The following code example shows how to enumerate keys alone using the property. + The following code example shows how to enumerate keys alone using the property. This code is part of a larger example that can be compiled and executed. See . @@ -556,14 +556,14 @@ method and the property. + This method combines the functionality of the method and the property. If the key is not found, then the `value` parameter gets the appropriate default value for the type `TValue`; for example, zero (0) for integer types, `false` for Boolean types, and `null` for reference types. ## Examples - The example shows how to use the method to retrieve values. If a program frequently tries key values that are not in a dictionary, the method can be more efficient than using the property (the indexer in C#), which throws exceptions when attempting to retrieve nonexistent keys. + The example shows how to use the method to retrieve values. If a program frequently tries key values that are not in a dictionary, the method can be more efficient than using the property (the indexer in C#), which throws exceptions when attempting to retrieve nonexistent keys. This code is part of a larger example that can be compiled and executed. See . @@ -626,12 +626,12 @@ is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. + The order of the values in the returned is unspecified, but it is guaranteed to be the same order as the corresponding keys in the returned by the property. ## Examples - The following code example shows how to enumerate values alone using the property. + The following code example shows how to enumerate values alone using the property. This code is part of a larger example that can be compiled and executed. See . diff --git a/xml/System.Collections.Generic/IEnumerable`1.xml b/xml/System.Collections.Generic/IEnumerable`1.xml index 3ca13a1b4cb..bd4a35a3044 100644 --- a/xml/System.Collections.Generic/IEnumerable`1.xml +++ b/xml/System.Collections.Generic/IEnumerable`1.xml @@ -70,23 +70,23 @@ The type of objects to enumerate. Exposes the enumerator, which supports a simple iteration over a collection of a specified type. - is the base interface for collections in the namespace such as , , and and other generic collections such as and . Collections that implement can be enumerated by using the `foreach` statement. - - For the non-generic version of this interface, see . - - contains a single method that you must implement when implementing this interface; , which returns an object. The returned provides the ability to iterate through the collection by exposing a property. - - - -## Examples - The following example demonstrates how to implement the interface and how to use that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](/dotnet/csharp/language-reference/keywords/yield) keyword. Implementing also requires to be implemented, which you will see in this example. - + is the base interface for collections in the namespace such as , , and and other generic collections such as and . Collections that implement can be enumerated by using the `foreach` statement. + + For the non-generic version of this interface, see . + + contains a single method that you must implement when implementing this interface; , which returns an object. The returned provides the ability to iterate through the collection by exposing a property. + + + +## Examples + The following example demonstrates how to implement the interface and how to use that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](/dotnet/csharp/language-reference/keywords/yield) keyword. Implementing also requires to be implemented, which you will see in this example. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/IEnumerableT/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/IEnumerableT/Overview/module1.vb" id="Snippet1"::: - + ]]> @@ -145,29 +145,29 @@ Returns an enumerator that iterates through the collection. An enumerator that can be used to iterate through the collection. - provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. - - Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - - returns the same object until is called again as 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. - - If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - - An enumerator does not have exclusive access to the collection so 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 invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. - + provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. + + Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + + returns the same object until is called again as 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. + + If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + + An enumerator does not have exclusive access to the collection so 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 invalidated and you may get unexpected results. Also, enumerating a collection is not a thread-safe procedure. To guarantee thread-safety, you should lock the collection during enumerator or implement synchronization on the collection. + Default implementations of collections in the namespace aren't synchronized. - -## Examples - The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](/dotnet/csharp/language-reference/keywords/yield) keyword. Implementing also requires to be implemented, which you will see in this example. - + +## Examples + The following example demonstrates how to implement the interface and uses that implementation to create a LINQ query. When you implement , you must also implement or, for C# only, you can use the [yield](/dotnet/csharp/language-reference/keywords/yield) keyword. Implementing also requires to be implemented, which you will see in this example. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/IEnumerableT/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/IEnumerableT/Overview/module1.vb" id="Snippet1"::: - + ]]> diff --git a/xml/System.Collections.Generic/IEqualityComparer`1.xml b/xml/System.Collections.Generic/IEqualityComparer`1.xml index 00d9af3f160..601c57f7163 100644 --- a/xml/System.Collections.Generic/IEqualityComparer`1.xml +++ b/xml/System.Collections.Generic/IEqualityComparer`1.xml @@ -60,22 +60,22 @@ The type of objects to compare. Defines methods to support the comparison of objects for equality. - generic interface. In the .NET Framework, constructors of the generic collection type accept this interface. - - A default implementation of this interface is provided by the property of the generic class. The class implements of type . - - This interface supports only equality comparisons. Customization of comparisons for sorting and ordering is provided by the generic interface. - - We recommend that you derive from the class instead of implementing the interface, because the class tests for equality using the method instead of the method. This is consistent with the `Contains`, `IndexOf`, `LastIndexOf`, and `Remove` methods of the class and other generic collections. - - - -## Examples - The following example adds custom `Box` objects to a dictionary collection. The `Box` objects are considered equal if their dimensions are the same. - + generic interface. In the .NET Framework, constructors of the generic collection type accept this interface. + + A default implementation of this interface is provided by the property of the generic class. The class implements of type . + + This interface supports only equality comparisons. Customization of comparisons for sorting and ordering is provided by the generic interface. + + We recommend that you derive from the class instead of implementing the interface, because the class tests for equality using the method instead of the method. This is consistent with the `Contains`, `IndexOf`, `LastIndexOf`, and `Remove` methods of the class and other generic collections. + + + +## Examples + The following example adds custom `Box` objects to a dictionary collection. The `Box` objects are considered equal if their dimensions are the same. + :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/IEqualityComparerT/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/IEqualityComparerT/Overview/program.vb" id="Snippet1"::: @@ -152,16 +152,16 @@ if the specified objects are equal; otherwise, . - - Implementations are required to ensure that if the method returns for two objects and , then the value returned by the method for must equal the value returned for . - + Implementations are required to ensure that if the method returns for two objects and , then the value returned by the method for must equal the value returned for . + The method is reflexive, symmetric, and transitive. That is, it returns if used to compare an object with itself; for two objects and if it is for and ; and for two objects and if it is for and and also for and . @@ -220,11 +220,11 @@ Returns a hash code for the specified object. A hash code for the specified object. - method. - + method. + ]]> The type of is a reference type and is . diff --git a/xml/System.Collections.Generic/IList`1.xml b/xml/System.Collections.Generic/IList`1.xml index 6885c1c6243..64d8655d5f7 100644 --- a/xml/System.Collections.Generic/IList`1.xml +++ b/xml/System.Collections.Generic/IList`1.xml @@ -69,11 +69,11 @@ The type of elements in the list. Represents a collection of objects that can be individually accessed by index. - generic interface is a descendant of the generic interface and is the base interface of all generic lists. - + generic interface is a descendant of the generic interface and is the base interface of all generic lists. + ]]> @@ -127,11 +127,11 @@ Determines the index of a specific item in the . The index of if found in the list; otherwise, -1. - method always returns the first instance found. - + method always returns the first instance found. + ]]> @@ -184,13 +184,13 @@ The object to insert into the . Inserts an item to the at the specified index. - , then `item` is appended to the list. - - In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. - + , then `item` is appended to the list. + + In collections of contiguous elements, such as lists, the elements that follow the insertion point move down to accommodate the new element. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. + ]]> @@ -246,13 +246,13 @@ Gets or sets the element at the specified index. The element at the specified index. - property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. - + property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + ]]> @@ -307,11 +307,11 @@ The zero-based index of the item to remove. Removes the item at the specified index. - diff --git a/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml b/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml index cdb6c47a6ba..89fedc9d74e 100644 --- a/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml +++ b/xml/System.Collections.Generic/IReadOnlyDictionary`2.xml @@ -149,7 +149,7 @@ might use the property, or it might implement the method. + Implementations can vary in how they determine the equality of objects; for example, the class that implements might use the property, or it might implement the method. Implementations can vary in whether they allow `key` to be `null`. @@ -210,7 +210,7 @@ ## Remarks This property lets you access a specific element in the collection by using the following syntax: `myCollection[key]` (`myCollection(key)` in Visual Basic). - Implementations can vary in how they determine the equality of objects: for example, the class that implements might use the property, or it might implement the method. + Implementations can vary in how they determine the equality of objects: for example, the class that implements might use the property, or it might implement the method. Implementations can vary in whether they allow `key` to be `null`. @@ -266,7 +266,7 @@ property. + The order of the keys in the enumerable collection is unspecified, but the implementation must guarantee that the keys are in the same order as the corresponding values in the enumerable collection that is returned by the property. ]]> @@ -331,7 +331,7 @@ method and the property. + This method combines the functionality of the method and the property. If the key is not found, the `value` parameter gets the appropriate default value for the type `TValue`: for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. @@ -386,7 +386,7 @@ property. + The order of the values in the enumerable collection is unspecified, but the implementation must guarantee that the values are in the same order as the corresponding keys in the enumerable collection that is returned by the property. ]]> diff --git a/xml/System.Collections.Generic/KeyNotFoundException.xml b/xml/System.Collections.Generic/KeyNotFoundException.xml index e9833b40655..6f24c481376 100644 --- a/xml/System.Collections.Generic/KeyNotFoundException.xml +++ b/xml/System.Collections.Generic/KeyNotFoundException.xml @@ -145,7 +145,7 @@ property of the new instance to a system-supplied message that describes the error, such as "The given key was not present in the dictionary." This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "The given key was not present in the dictionary." This message takes into account the current system culture. The following table shows the initial property values for an instance of the class. @@ -331,7 +331,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 the class. diff --git a/xml/System.Collections.Generic/KeyValuePair`2.xml b/xml/System.Collections.Generic/KeyValuePair`2.xml index cadcb97aa2f..8e9ad58b834 100644 --- a/xml/System.Collections.Generic/KeyValuePair`2.xml +++ b/xml/System.Collections.Generic/KeyValuePair`2.xml @@ -89,7 +89,7 @@ property returns an instance of this type. + The property returns an instance of this type. The `foreach` statement of the C# language (`For Each` in Visual Basic) returns an object of the type of the elements in the collection. Since each element of a collection based on is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is . For example: diff --git a/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml b/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml index 4b32278fa5d..d180c7dfb7a 100644 --- a/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml +++ b/xml/System.Collections.Generic/LinkedList`1+Enumerator.xml @@ -171,7 +171,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -348,7 +348,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. diff --git a/xml/System.Collections.Generic/LinkedList`1.xml b/xml/System.Collections.Generic/LinkedList`1.xml index aac9e81eae2..43366c8609c 100644 --- a/xml/System.Collections.Generic/LinkedList`1.xml +++ b/xml/System.Collections.Generic/LinkedList`1.xml @@ -127,11 +127,11 @@ provides separate nodes of type , so insertion and removal are O(1) operations. - You can remove nodes and reinsert them, either in the same list or in another list, which results in no additional objects allocated on the heap. Because the list also maintains an internal count, getting the property is an O(1) operation. + You can remove nodes and reinsert them, either in the same list or in another list, which results in no additional objects allocated on the heap. Because the list also maintains an internal count, getting the property is an O(1) operation. Each node in a object is of the type . Because the is doubly linked, each node points forward to the node and backward to the node. - Lists that contain reference types perform better when a node and its value are created at the same time. accepts `null` as a valid property for reference types and allows duplicate values. + Lists that contain reference types perform better when a node and its value are created at the same time. accepts `null` as a valid property for reference types and allows duplicate values. If the is empty, the and properties contain `null`. @@ -2363,7 +2363,7 @@ 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. + 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. ```csharp ICollection ic = ...; diff --git a/xml/System.Collections.Generic/List`1+Enumerator.xml b/xml/System.Collections.Generic/List`1+Enumerator.xml index 7128dde4262..98f1a85daf2 100644 --- a/xml/System.Collections.Generic/List`1+Enumerator.xml +++ b/xml/System.Collections.Generic/List`1+Enumerator.xml @@ -156,7 +156,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -339,7 +339,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. diff --git a/xml/System.Collections.Generic/List`1.xml b/xml/System.Collections.Generic/List`1.xml index eeb188fe354..cbb700c09a2 100644 --- a/xml/System.Collections.Generic/List`1.xml +++ b/xml/System.Collections.Generic/List`1.xml @@ -182,13 +182,13 @@ 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 . + 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 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. @@ -249,7 +249,7 @@ 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. + 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="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ListT/.ctor/source2.vb" id="Snippet1"::: @@ -316,7 +316,7 @@ 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 . + 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. @@ -397,7 +397,7 @@ :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ListT/Add/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. + 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. @@ -536,7 +536,7 @@ ## 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. + 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="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/.ctor/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ListT/.ctor/source.vb" id="Snippet1"::: @@ -604,7 +604,7 @@ 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 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 . The must already be sorted according to the comparer implementation; otherwise, the result is incorrect. @@ -888,7 +888,7 @@ 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. + 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. @@ -899,9 +899,9 @@ :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ListT/Capacity/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 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 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="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ListT/.ctor/source1.vb" id="Snippet1"::: @@ -965,7 +965,7 @@ ## Remarks 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. + 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 . @@ -1432,7 +1432,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Capacity/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ListT/Capacity/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="csharp" source="~/snippets/csharp/System.Collections.Generic/ListT/Overview/source.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/ListT/.ctor/source1.vb" id="Snippet1"::: @@ -2540,9 +2540,9 @@ Public Function StartsWith(e As Employee) As Boolean Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 . + Initially, the enumerator is positioned before the first element in the collection. 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 is called. sets to the next element. + 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. @@ -3107,12 +3107,12 @@ Public Function StartsWith(e As Employee) As Boolean 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 .) + 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. +> 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. + 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/System.Collections.Generic/ListT/.ctor/source1.vb" id="Snippet2"::: @@ -3569,7 +3569,7 @@ Public Function StartsWith(e As Employee) As Boolean 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. + When you call 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`). @@ -3907,7 +3907,7 @@ Public Function StartsWith(e As Employee) As Boolean 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 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: @@ -4352,9 +4352,9 @@ Public Function StartsWith(e As Employee) As Boolean Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 . + Initially, the enumerator is positioned before the first element in the collection. 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 is called. sets to the next element. + 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. @@ -4569,7 +4569,7 @@ Public Function StartsWith(e As Employee) As Boolean 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. + 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. ```csharp ICollection ic = ...; @@ -4651,9 +4651,9 @@ Retrieving the value of this property is an O(1) operation. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. 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 . + Initially, the enumerator is positioned before the first element in 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. + 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 . @@ -5110,7 +5110,7 @@ Retrieving the value of this property is an O(1) operation. property. Visual Basic implements as a default property, which provides the same indexing functionality. + 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. Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. @@ -5299,7 +5299,7 @@ Retrieving the value of this property is an O(1) operation. 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. + The capacity can also be set using the property. ## Examples diff --git a/xml/System.Collections.Generic/Queue`1+Enumerator.xml b/xml/System.Collections.Generic/Queue`1+Enumerator.xml index ab2aae0161a..7b28b55a958 100644 --- a/xml/System.Collections.Generic/Queue`1+Enumerator.xml +++ b/xml/System.Collections.Generic/Queue`1+Enumerator.xml @@ -156,7 +156,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -335,7 +335,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. diff --git a/xml/System.Collections.Generic/Queue`1.xml b/xml/System.Collections.Generic/Queue`1.xml index 80b7e344d46..5793bea03ed 100644 --- a/xml/System.Collections.Generic/Queue`1.xml +++ b/xml/System.Collections.Generic/Queue`1.xml @@ -128,7 +128,7 @@ An array twice the size of the queue is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a second copy of the queue containing three null elements at the beginning. - The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. + The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/QueueT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/QueueT/Overview/source.fs" id="Snippet1"::: @@ -161,7 +161,7 @@ An array twice the size of the queue is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a second copy of the queue containing three null elements at the beginning. - The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. + The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/QueueT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/QueueT/Overview/source.fs" id="Snippet1"::: @@ -431,7 +431,7 @@ An array twice the size of the queue is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a second copy of the queue containing three null elements at the beginning. - The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. + The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/QueueT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/QueueT/Overview/source.fs" id="Snippet1"::: @@ -506,7 +506,7 @@ An array twice the size of the queue is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a second copy of the queue containing three null elements at the beginning. - The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. + The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/QueueT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/QueueT/Overview/source.fs" id="Snippet1"::: @@ -642,7 +642,7 @@ ## Examples - The following code example demonstrates several properties and methods of the generic class, including the property. + The following code example demonstrates several properties and methods of the generic class, including the property. The code example creates a queue of strings with default capacity and uses the method to queue five strings. The elements of the queue are enumerated, which does not change the state of the queue. The method is used to dequeue the first string. The method is used to look at the next item in the queue, and then the method is used to dequeue it. @@ -650,7 +650,7 @@ An array twice the size of the queue is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a second copy of the queue containing three null elements at the beginning. - The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. + The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/QueueT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/QueueT/Overview/source.fs" id="Snippet1"::: @@ -722,7 +722,7 @@ An array twice the size of the queue is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a second copy of the queue containing three null elements at the beginning. - The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. + The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/QueueT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/QueueT/Overview/source.fs" id="Snippet1"::: @@ -797,7 +797,7 @@ An array twice the size of the queue is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a second copy of the queue containing three null elements at the beginning. - The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. + The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/QueueT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/QueueT/Overview/source.fs" id="Snippet1"::: @@ -919,7 +919,7 @@ An array twice the size of the queue is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a second copy of the queue containing three null elements at the beginning. - The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. + The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/QueueT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/QueueT/Overview/source.fs" id="Snippet1"::: @@ -993,7 +993,7 @@ An array twice the size of the queue is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a second copy of the queue containing three null elements at the beginning. - The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. + The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/QueueT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/QueueT/Overview/source.fs" id="Snippet1"::: @@ -1272,7 +1272,7 @@ 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, which 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. + returns an object, which 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. ```csharp ICollection ic = ...; @@ -1428,7 +1428,7 @@ Retrieving the value of this property is an O(1) operation. An array twice the size of the queue is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a second copy of the queue containing three null elements at the beginning. - The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. + The method is used to show that the string "four" is in the first copy of the queue, after which the method clears the copy and the property shows that the queue is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/QueueT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/QueueT/Overview/source.fs" id="Snippet1"::: diff --git a/xml/System.Collections.Generic/SortedDictionary`2+Enumerator.xml b/xml/System.Collections.Generic/SortedDictionary`2+Enumerator.xml index 07896ad35aa..a4129f33acf 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+Enumerator.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+Enumerator.xml @@ -84,7 +84,7 @@ Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . - The property returns the same object until is called. sets to the next element. + 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. @@ -157,7 +157,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -327,7 +327,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -399,7 +399,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -472,7 +472,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -546,7 +546,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -610,7 +610,7 @@ method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + After calling the method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . diff --git a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml index 52c30e69815..a0c7cb4b01e 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection+Enumerator.xml @@ -79,7 +79,7 @@ Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . - The property returns the same object until is called. sets to the next element. + 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. @@ -153,7 +153,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -331,7 +331,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -395,7 +395,7 @@ method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + After calling the method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . diff --git a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml index 9422776d4c9..404ff616d3a 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+KeyCollection.xml @@ -103,7 +103,7 @@ property returns an instance of this type, containing all the keys in that . The order of the keys in the is the same as the order of elements in the , the same as the order of the associated values in the returned by the property. + The property returns an instance of this type, containing all the keys in that . The order of the keys in the is the same as the order of elements in the , the same as the order of the associated values in the returned by the property. The is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . @@ -372,7 +372,7 @@ Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . - The property returns the same object until is called. sets to the next element. + 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. @@ -488,7 +488,7 @@ property is set to 0, and references to other objects from elements of the collection are also released. + The property is set to 0, and references to other objects from elements of the collection are also released. ]]> @@ -720,9 +720,9 @@ Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 . + Initially, the enumerator is positioned before the first element in the collection. 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 is called. sets to the next element. + 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. @@ -873,7 +873,7 @@ 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. - The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. + The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. Getting the value of this property is an O(1) operation. @@ -939,7 +939,7 @@ 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. - The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. The following code shows the use of the property. + The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. The following code shows the use of the property. ```csharp ICollection ic = ...; @@ -1015,9 +1015,9 @@ Getting the value of this property is an O(1) operation. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. 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 . + Initially, the enumerator is positioned before the first element in 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. + 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 . diff --git a/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection+Enumerator.xml b/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection+Enumerator.xml index 6c2f3e8201d..f31a4778fd7 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection+Enumerator.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection+Enumerator.xml @@ -79,7 +79,7 @@ Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . - The property returns the same object until is called. sets to the next element. + 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. @@ -153,7 +153,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -331,7 +331,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -395,7 +395,7 @@ method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. + After calling the method, you must call the method to advance the enumerator to the first element of the collection before reading the value of the property. An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to or throws an . diff --git a/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml b/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml index 08e917e5d79..04a77989ebd 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2+ValueCollection.xml @@ -103,7 +103,7 @@ property returns an instance of this type, containing all the values in that . The order of the values in the is the same as the order of the elements in the , and the same as the order of the associated keys in the returned by the property. + The property returns an instance of this type, containing all the values in that . The order of the values in the is the same as the order of the elements in the , and the same as the order of the associated keys in the returned by the property. The is not a static copy; instead, the refers back to the values in the original . Therefore, changes to the continue to be reflected in the . @@ -340,7 +340,7 @@ Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. You must call the method to advance the enumerator to the first element of the collection before reading the value of . - The property returns the same object until is called. sets to the next element. + 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. @@ -456,7 +456,7 @@ property is set to 0, and references to other objects from elements of the collection are also released. + The property is set to 0, and references to other objects from elements of the collection are also released. ]]> @@ -692,9 +692,9 @@ Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 . + Initially, the enumerator is positioned before the first element in the collection. 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 is called. sets to the next element. + 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. @@ -845,7 +845,7 @@ 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. - The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. + The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. Getting the value of this property is an O(1) operation. @@ -911,7 +911,7 @@ 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. - The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. The following code shows the use of the property. + The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. The following code shows the use of the property. ```csharp ICollection ic = ...; @@ -987,9 +987,9 @@ Getting the value of this property is an O(1) operation. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. 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 . + Initially, the enumerator is positioned before the first element in 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. + 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 . diff --git a/xml/System.Collections.Generic/SortedDictionary`2.xml b/xml/System.Collections.Generic/SortedDictionary`2.xml index f9d1bbf954a..9dce542d43f 100644 --- a/xml/System.Collections.Generic/SortedDictionary`2.xml +++ b/xml/System.Collections.Generic/SortedDictionary`2.xml @@ -142,11 +142,11 @@ ## Examples The following code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - The example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. The example shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary, and it shows how to use the method to test whether a key exists before calling the method. - The example shows how to enumerate the keys and values in the dictionary and how to enumerate the keys and values alone using the property and the property. + The example shows how to enumerate the keys and values in the dictionary and how to enumerate the keys and values alone using the property and the property. Finally, the example demonstrates the method. @@ -525,7 +525,7 @@ property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue` (in Visual Basic, `myCollection("myNonexistantKey") = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method throws an exception if an element with the specified key already exists. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue` (in Visual Basic, `myCollection("myNonexistantKey") = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method throws an exception if an element with the specified key already exists. A key cannot be `null`, but a value can be, if the value type `TValue` is a reference type. @@ -599,7 +599,7 @@ property is set to 0, and references to other objects from elements of the collection are also released. + The property is set to 0, and references to other objects from elements of the collection are also released. This method is an O(1) operation, since the root of the internal data structures is simply released for garbage collection. @@ -718,7 +718,7 @@ ## Examples - The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method to retrieve values, which is an efficient way to retrieve values when a program frequently tries keys that are not in the dictionary. Finally, it shows the least efficient way to test whether keys exist, by using the property (the indexer in C#). + The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method to retrieve values, which is an efficient way to retrieve values when a program frequently tries keys that are not in the dictionary. Finally, it shows the least efficient way to test whether keys exist, by using the property (the indexer in C#). This code example is part of a larger example provided for the class. @@ -787,7 +787,7 @@ ## Remarks This method determines equality using the default equality comparer for the value type `TValue`. - This method performs a linear search; therefore, the average execution time is proportional to the property. That is, this method is an O(`n`) operation, where `n` is . + This method performs a linear search; therefore, the average execution time is proportional to the property. That is, this method is an O(`n`) operation, where `n` is . ]]> @@ -977,9 +977,9 @@ The dictionary is maintained in a sorted order using an internal tree. Every new element is positioned at the correct sort position, and the tree is adjusted to maintain the sort order whenever an element is removed. While enumerating, the sort order is maintained. - Initially, the enumerator is positioned before the first element in the collection. 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 . + Initially, the enumerator is positioned before the first element in the collection. 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 element until the method is called. sets to the next element. + The property returns the same element until the method 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. @@ -1050,18 +1050,18 @@ ## Remarks This property provides the ability to access a specific element in the collection by using the following C# syntax: `myCollection[key]` (`myCollection(key)` in Visual Basic). - You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. A key cannot be `null`, but a value can be, if the value type `TValue` is a reference type. - 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. + 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. Getting the value of this property is an O(log `n`) operation; setting the property is also an O(log `n`) operation. ## Examples - The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the dictionary. @@ -1126,7 +1126,7 @@ are sorted according to the property and are in the same order as the associated values in the returned by the property. + The keys in the are sorted according to the property and are in the same order as the associated values in the returned by the property. The returned is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . @@ -1135,7 +1135,7 @@ ## Examples - The following code example shows how to enumerate the keys in the dictionary using the property, and how to enumerate the keys and values in the dictionary. + The following code example shows how to enumerate the keys in the dictionary using the property, and how to enumerate the keys and values in the dictionary. This code is part of a larger example that can be compiled and executed. See . @@ -1797,7 +1797,7 @@ Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which can cause the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. + The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. Getting the value of this property is an O(1) operation. @@ -1857,7 +1857,7 @@ 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. - The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. The following code shows the use of the property. + The property returns an object that can be used to synchronize access to the . Synchronization is effective only if all threads lock the object before accessing the collection. The following code shows the use of the property. ```csharp ICollection ic = ...; @@ -1933,7 +1933,7 @@ Getting the value of this property is an O(1) operation. property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. This method is an O(log `n`) operation, where `n` is . @@ -2096,7 +2096,7 @@ Getting the value of this property is an O(1) operation. Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, 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. + 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 . @@ -2304,18 +2304,18 @@ Getting the value of this property is an O(1) operation. ## Remarks This property provides the ability to access a specific element in the collection by using the following C# syntax: `myCollection[key]` (`myCollection(key)` in Visual Basic). - You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - 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. + 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. Getting the value of this property is an O(log `n`) operation; setting the property is also an O(log `n`) operation. ## Examples - The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. + The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. - The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the dictionary. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the dictionary, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. + The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the dictionary. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the dictionary, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. The code example is part of a larger example, including output, provided for the method. @@ -2393,14 +2393,14 @@ Getting the value of this property is an O(1) operation. are sorted according to the property and are guaranteed to be in the same order as the corresponding values in the returned by the property. + The keys in the returned are sorted according to the property and are guaranteed to be in the same order as the corresponding values in the returned by the property. Getting the value of this property is an O(1) operation. ## Examples - The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -2543,14 +2543,14 @@ Getting the value of this property is an O(1) operation. are sorted according to the property, and are guaranteed to be in the same order as the corresponding keys in the returned by the property. + The values in the returned are sorted according to the property, and are guaranteed to be in the same order as the corresponding keys in the returned by the property. Getting the value of this property is an O(1) operation. ## Examples - The following code example shows how to use the property of the interface with a , to list the values in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the values in the dictionary. The example also shows how to enumerate the key/value pairs in the dictionary; note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -2621,9 +2621,9 @@ Getting the value of this property is an O(1) operation. Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 . + Initially, the enumerator is positioned before the first element in the collection. 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 element until the method is called. sets to the next element. + The property returns the same element until the method 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. @@ -2703,7 +2703,7 @@ Getting the value of this property is an O(1) operation. method and the property. + This method combines the functionality of the method and the property. If the key is not found, then the `value` parameter gets the appropriate default value for the value type `TValue`; for example, 0 (zero) for integer types, `false` for Boolean types, and `null` for reference types. @@ -2712,7 +2712,7 @@ Getting the value of this property is an O(1) operation. ## Examples - The example shows how to use the method as a more efficient way to retrieve values in a program that frequently tries keys that are not in the dictionary. For contrast, the example also shows how the property (the indexer in C#) throws exceptions when attempting to retrieve nonexistent keys. + The example shows how to use the method as a more efficient way to retrieve values in a program that frequently tries keys that are not in the dictionary. For contrast, the example also shows how the property (the indexer in C#) throws exceptions when attempting to retrieve nonexistent keys. This code example is part of a larger example provided for the class. @@ -2773,7 +2773,7 @@ Getting the value of this property is an O(1) operation. are sorted according to the property, and are in the same order as the associated keys in the returned by the property. + The values in the are sorted according to the property, and are in the same order as the associated keys in the returned by the property. The returned is not a static copy; instead, the refers back to the values in the original . Therefore, changes to the continue to be reflected in the . @@ -2782,7 +2782,7 @@ Getting the value of this property is an O(1) operation. ## Examples - This code example shows how to enumerate the values in the dictionary using the property, and how to enumerate the keys and values in the dictionary. + This code example shows how to enumerate the values in the dictionary using the property, and how to enumerate the keys and values in the dictionary. This code example is part of a larger example provided for the class. diff --git a/xml/System.Collections.Generic/SortedList`2.xml b/xml/System.Collections.Generic/SortedList`2.xml index 56a6287ebac..e82afde981d 100644 --- a/xml/System.Collections.Generic/SortedList`2.xml +++ b/xml/System.Collections.Generic/SortedList`2.xml @@ -127,7 +127,7 @@ - If the list is populated all at once from sorted data, is faster than . - Another difference between the and classes is that supports efficient indexed retrieval of keys and values through the collections returned by the and properties. It is not necessary to regenerate the lists when the properties are accessed, because the lists are just wrappers for the internal arrays of keys and values. The following code shows the use of the property for indexed retrieval of values from a sorted list of strings: + Another difference between the and classes is that supports efficient indexed retrieval of keys and values through the collections returned by the and properties. It is not necessary to regenerate the lists when the properties are accessed, because the lists are just wrappers for the internal arrays of keys and values. The following code shows the use of the property for indexed retrieval of values from a sorted list of strings: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedListTKey,TValue/Overview/remarks.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/SortedListTKey,TValue/Overview/remarks.vb" id="Snippet11"::: @@ -139,7 +139,7 @@ requires a comparer implementation to sort and to perform comparisons. The default comparer checks whether the key type `TKey` implements and uses that implementation, if available. If not, checks whether the key type `TKey` implements . If the key type `TKey` does not implement either interface, you can specify a implementation in a constructor overload that accepts a `comparer` parameter. - The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. The capacity can be decreased by calling or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . + The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required by reallocating the internal array. The capacity can be decreased by calling or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . **.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. @@ -156,11 +156,11 @@ ## Examples The following code example creates an empty of strings with string keys and uses the method to add some elements. The example demonstrates that the method throws an when attempting to add a duplicate key. - The example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. The example shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the sorted list, and it shows how to use the method to test whether a key exists before calling the method. - The example shows how to enumerate the keys and values in the sorted list and how to enumerate the keys and values alone using the property and the property. + The example shows how to enumerate the keys and values in the sorted list and how to enumerate the keys and values alone using the property and the property. Finally, the example demonstrates the method. @@ -458,7 +458,7 @@ 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 or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . + The capacity can be decreased by calling or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . This constructor uses the default comparer for `TKey`. To specify a comparer, use the constructor. The default comparer checks whether the key type `TKey` implements and uses that implementation, if available. If not, checks whether the key type `TKey` implements . If the key type `TKey` does not implement either interface, you can specify a implementation in a constructor overload that accepts a `comparer` parameter. @@ -629,7 +629,7 @@ 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 or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . + The capacity can be decreased by calling or by setting the property explicitly. Decreasing the capacity reallocates memory and copies all the elements in the . This constructor is an O(`n`) operation, where `n` is `capacity`. @@ -705,7 +705,7 @@ ## Remarks A key cannot be `null`, but a value can be, if the type of values in the sorted list, `TValue`, is a reference type. - You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing 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. @@ -779,7 +779,7 @@ 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. - The capacity can be decreased by calling or by setting the property explicitly. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity. + The capacity can be decreased by calling or by setting the property explicitly. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity. 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. @@ -841,7 +841,7 @@ ## Remarks is set to zero, and references to other objects from elements of the collection are also released. - remains unchanged. To reset the capacity of the , call or set the property directly. Trimming an empty sets the capacity of the to the default capacity. + remains unchanged. To reset the capacity of the , call or set the property directly. Trimming an empty sets the capacity of the to the default capacity. This method is an O(`n`) operation, where `n` is . @@ -964,7 +964,7 @@ ## Examples - The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method to retrieve values, which is an efficient way to retrieve values when a program frequently tries keys that are not in the sorted list. Finally, it shows the least efficient way to test whether keys exist, by using the property (the indexer in C#). + The following code example shows how to use the method to test whether a key exists prior to calling the method. It also shows how to use the method to retrieve values, which is an efficient way to retrieve values when a program frequently tries keys that are not in the sorted list. Finally, it shows the least efficient way to test whether keys exist, by using the property (the indexer in C#). This code example is part of a larger example provided for the class. @@ -1417,16 +1417,16 @@ If the key is not found when a value is being retrieved, is thrown. If the key is not found when a value is being set, the key and value are added. - You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. - 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. + 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. Retrieving the value of this property is an O(log `n`) operation, where n is . Setting the property is an O(log `n`) operation if the key is already in the . If the key is not in the list, setting the property is an O(`n`) operation for unsorted data, or O(log `n`) if the new element is added at the end of the list. If insertion causes a resize, the operation is O(`n`). ## Examples - The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. + The following code example uses the property (the indexer in C#) to retrieve values, demonstrating that a is thrown when a requested key is not present, and showing that the value associated with a key can be replaced. The example also shows how to use the method as a more efficient way to retrieve values if a program often must try key values that are not in the sorted list. @@ -1503,7 +1503,7 @@ The returned is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the continue to be reflected in the . - The collection returned by the property provides an efficient way to retrieve keys by index. It is not necessary to regenerate the list when the property is accessed, because the list is just a wrapper for the internal array of keys. The following code shows the use of the property for indexed retrieval of keys from a sorted list of elements with string keys: + The collection returned by the property provides an efficient way to retrieve keys by index. It is not necessary to regenerate the list when the property is accessed, because the list is just a wrapper for the internal array of keys. The following code shows the use of the property for indexed retrieval of keys from a sorted list of elements with string keys: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedListTKey,TValue/Overview/remarks.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/SortedListTKey,TValue/Overview/remarks.vb" id="Snippet11"::: @@ -1514,9 +1514,9 @@ ## Examples - The following code example shows how to enumerate the keys in the sorted list using the property, and how to enumerate the keys and values in the sorted list. + The following code example shows how to enumerate the keys in the sorted list using the property, and how to enumerate the keys and values in the sorted list. - The example also shows how to use the property for efficient indexed retrieval of keys. + The example also shows how to use the property for efficient indexed retrieval of keys. This code is part of a larger example that can be compiled and executed. See . @@ -2324,7 +2324,7 @@ 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. - The property 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 property 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. @@ -2383,7 +2383,7 @@ 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. - The property 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. + The property 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. ```csharp ICollection ic = ...; @@ -2457,7 +2457,7 @@ Retrieving the value of this property is an O(1) operation. property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. This method is an O(`n`) operation for unsorted data, where `n` is . It is an O(log `n`) operation if the new element is added at the end of the list. If insertion causes a resize, the operation is O(`n`). @@ -2829,18 +2829,18 @@ Retrieving the value of this property is an O(1) operation. This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[key]`. - You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. - 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. + 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. Retrieving the value of this property is an O(log `n`) operation, where n is . Setting the property is an O(log `n`) operation if the key is already in the . If the key is not in the list, setting the property is an O(`n`) operation for unsorted data, or O(log `n`) if the new element is added at the end of the list. If insertion causes a resize, the operation is O(`n`). ## Examples - The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. + The following code example shows how to use the property (the indexer in C#) of the interface with a , and ways the property differs from the property. - The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the sorted list. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the sorted list, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. + The example shows that, like the property, the property can change the value associated with an existing key and can be used to add a new key/value pair if the specified key is not in the sorted list. The example also shows that unlike the property, the property does not throw an exception if `key` is not in the sorted list, returning a null reference instead. Finally, the example demonstrates that getting the property returns a null reference if `key` is not the correct data type, and that setting the property throws an exception if `key` is not the correct data type. The code example is part of a larger example, including output, provided for the method. @@ -2925,7 +2925,7 @@ Retrieving the value of this property is an O(1) operation. ## Examples - The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the sorted list; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the keys in the dictionary. The example also shows how to enumerate the key/value pairs in the sorted list; note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -3077,7 +3077,7 @@ Retrieving the value of this property is an O(1) operation. ## Examples - The following code example shows how to use the property of the interface with a , to list the values in the sorted list. The example also shows how to enumerate the key/value pairs in the sorted list; note that the enumerator for the interface returns objects rather than objects. + The following code example shows how to use the property of the interface with a , to list the values in the sorted list. The example also shows how to enumerate the key/value pairs in the sorted list; note that the enumerator for the interface returns objects rather than objects. The code example is part of a larger example, including output, provided for the method. @@ -3217,7 +3217,7 @@ Retrieving the value of this property is an O(1) operation. To reset a to its initial state, call the method before calling method. Trimming an empty sets the capacity of the to the default capacity. - The capacity can also be set using the property. + The capacity can also be set using the property. ]]> @@ -3287,7 +3287,7 @@ Retrieving the value of this property is an O(1) operation. method and the property. + This method combines the functionality of the method and the property. If the key is not found, then the `value` parameter gets the appropriate default value for the value type `TValue`; for example, zero (0) for integer types, `false` for Boolean types, and `null` for reference types. @@ -3296,7 +3296,7 @@ Retrieving the value of this property is an O(1) operation. ## Examples - The example shows how to use the method as a more efficient way to retrieve values in a program that frequently tries keys that are not in the sorted list. For contrast, the example also shows how the property (the indexer in C#) throws exceptions when attempting to retrieve nonexistent keys. + The example shows how to use the method as a more efficient way to retrieve values in a program that frequently tries keys that are not in the sorted list. For contrast, the example also shows how the property (the indexer in C#) throws exceptions when attempting to retrieve nonexistent keys. This code example is part of a larger example provided for the class. @@ -3370,7 +3370,7 @@ Retrieving the value of this property is an O(1) operation. The returned is not a static copy; instead, the refers back to the values in the original . Therefore, changes to the continue to be reflected in the . - The collection returned by the property provides an efficient way to retrieve values by index. It is not necessary to regenerate the list when the property is accessed, because the list is just a wrapper for the internal array of values. The following code shows the use of the property for indexed retrieval of values from a sorted list of strings: + The collection returned by the property provides an efficient way to retrieve values by index. It is not necessary to regenerate the list when the property is accessed, because the list is just a wrapper for the internal array of values. The following code shows the use of the property for indexed retrieval of values from a sorted list of strings: :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/SortedListTKey,TValue/Overview/remarks.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Generic/SortedListTKey,TValue/Overview/remarks.vb" id="Snippet11"::: @@ -3381,9 +3381,9 @@ Retrieving the value of this property is an O(1) operation. ## Examples - This code example shows how to enumerate the values in the sorted list using the property, and how to enumerate the keys and values in the sorted list. + This code example shows how to enumerate the values in the sorted list using the property, and how to enumerate the keys and values in the sorted list. - The example also shows how to use the property for efficient indexed retrieval of values. + The example also shows how to use the property for efficient indexed retrieval of values. This code example is part of a larger example provided for the class. diff --git a/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml b/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml index 3b8b8a3f5c9..519d4262974 100644 --- a/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml +++ b/xml/System.Collections.Generic/SortedSet`1+Enumerator.xml @@ -93,7 +93,7 @@ Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. At this position, 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 . + Initially, the enumerator is positioned before the first element in the collection. 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 . returns the same object until is called. sets to the next element. @@ -164,7 +164,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -336,7 +336,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. diff --git a/xml/System.Collections.Generic/SortedSet`1.xml b/xml/System.Collections.Generic/SortedSet`1.xml index 9b32c3a33f6..d59e69154b7 100644 --- a/xml/System.Collections.Generic/SortedSet`1.xml +++ b/xml/System.Collections.Generic/SortedSet`1.xml @@ -1682,7 +1682,7 @@ has no elements, then the property returns the default value of `T`. + If the has no elements, then the property returns the default value of `T`. ]]> @@ -1738,7 +1738,7 @@ has no elements, then the property returns the default value of `T`. + If the has no elements, then the property returns the default value of `T`. ]]> diff --git a/xml/System.Collections.Generic/Stack`1+Enumerator.xml b/xml/System.Collections.Generic/Stack`1+Enumerator.xml index 2cdc40d4658..854001d6013 100644 --- a/xml/System.Collections.Generic/Stack`1+Enumerator.xml +++ b/xml/System.Collections.Generic/Stack`1+Enumerator.xml @@ -156,7 +156,7 @@ ## Remarks is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. @@ -335,7 +335,7 @@ is undefined under any of the following conditions: -- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. +- The enumerator is positioned before the first element of the collection. That happens after an enumerator is created or after the method is called. The method must be called to advance the enumerator to the first element of the collection before reading the value of the property. - The last call to returned `false`, which indicates the end of the collection and that the enumerator is positioned after the last element of the collection. diff --git a/xml/System.Collections.Generic/Stack`1.xml b/xml/System.Collections.Generic/Stack`1.xml index e7a3ae0cbd2..ee945f04822 100644 --- a/xml/System.Collections.Generic/Stack`1.xml +++ b/xml/System.Collections.Generic/Stack`1.xml @@ -136,7 +136,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -221,7 +221,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -296,7 +296,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -458,7 +458,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -532,7 +532,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -607,7 +607,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -686,7 +686,7 @@ ## Examples - The following code example demonstrates several properties and methods of the generic class, including the property. + The following code example demonstrates several properties and methods of the generic class, including the property. The code example creates a stack of strings with default capacity and uses the method to push five strings onto the stack. The elements of the stack are enumerated, which does not change the state of the stack. The method is used to pop the first string off the stack. The method is used to look at the next item on the stack, and then the method is used to pop it off. @@ -694,7 +694,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -812,7 +812,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -886,7 +886,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -961,7 +961,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -1040,7 +1040,7 @@ An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: @@ -1316,7 +1316,7 @@ 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. + 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. ```csharp ICollection ic = ...; @@ -1472,7 +1472,7 @@ Retrieving the value of this property is an O(1) operation. An array twice the size of the stack is created, and the method is used to copy the array elements beginning at the middle of the array. The constructor is used again to create a copy of the stack with the order of elements reversed; thus, the three null elements are at the end. - The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. + The method is used to show that the string "four" is in the first copy of the stack, after which the method clears the copy and the property shows that the stack is empty. :::code language="csharp" source="~/snippets/csharp/System.Collections.Generic/StackT/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Collections.Generic/StackT/Overview/source.fs" id="Snippet1"::: diff --git a/xml/System.Collections.Generic/SynchronizedCollection`1.xml b/xml/System.Collections.Generic/SynchronizedCollection`1.xml index 7ced82e401f..fec3b0a9da6 100644 --- a/xml/System.Collections.Generic/SynchronizedCollection`1.xml +++ b/xml/System.Collections.Generic/SynchronizedCollection`1.xml @@ -72,11 +72,11 @@ The type of object contained as items in the thread-safe collection. Provides a thread-safe collection that contains objects of a type specified by the generic parameter as elements. - stores data in a container and provides an object that can be set and used to synchronize access to the collection so that it is thread-safe. The container can be recovered using the property. The synchronized object can be recovered using the property. It can only be set using one of the constructors that take the `syncRoot` parameter. - + stores data in a container and provides an object that can be set and used to synchronize access to the collection so that it is thread-safe. The container can be recovered using the property. The synchronized object can be recovered using the property. It can only be set using one of the constructors that take the `syncRoot` parameter. + ]]> @@ -147,11 +147,11 @@ The object used to synchronize access the thread-safe collection. Initializes a new instance of the class with the object used to synchronize access to the thread-safe collection. - are created using the same `syncRoot`, then access is protected across all instances. - + are created using the same `syncRoot`, then access is protected across all instances. + ]]> @@ -563,11 +563,11 @@ The object to be inserted into the collection as an element. Inserts an item into the collection at a specified index. - The specified is less than zero or greater than the number of items in the collection. @@ -608,11 +608,11 @@ The object to be inserted into the collection. Inserts an item into the collection at a specified index. - The specified is less than zero or greater than the number of items in the collection. @@ -732,11 +732,11 @@ if item was successfully removed from the collection; otherwise, . - @@ -777,11 +777,11 @@ The zero-based index of the element to be retrieved from the collection. Removes an item at a specified index from the collection. - The specified is less than zero or greater than the number of items in the collection. @@ -930,11 +930,11 @@ - @@ -1012,11 +1012,11 @@ - @@ -1053,11 +1053,11 @@ Gets the object used to synchronize access to the thread-safe collection. An object used to synchronize access to the thread-safe collection. - constructor. - + constructor. + ]]> @@ -1141,11 +1141,11 @@ This member is an explicit interface member implementation. It can be used only Adds an element to the collection. The position into which the new element was inserted. - @@ -1266,11 +1266,11 @@ This member is an explicit interface member implementation. It can be used only The object to insert into the collection. Inserts an object into the collection at a specified index. - The specified is less than zero or greater than the number of items in the collection. @@ -1311,11 +1311,11 @@ This member is an explicit interface member implementation. It can be used only - @@ -1354,11 +1354,11 @@ This member is an explicit interface member implementation. It can be used only - @@ -1438,11 +1438,11 @@ This member is an explicit interface member implementation. It can be used only The object to be removed from the collection. Removes the first occurrence of a specified object as an element from the collection. - diff --git a/xml/System.Collections.Generic/SynchronizedReadOnlyCollection`1.xml b/xml/System.Collections.Generic/SynchronizedReadOnlyCollection`1.xml index 9f9ce52e217..d6462ab53c2 100644 --- a/xml/System.Collections.Generic/SynchronizedReadOnlyCollection`1.xml +++ b/xml/System.Collections.Generic/SynchronizedReadOnlyCollection`1.xml @@ -61,7 +61,7 @@ stores data in an container and provides an object that can be set and used to synchronize access to the collection so that it is thread safe. The container can be recovered using the property. The synchronized object can be recovered using the property. It can only be set using one of the constructors that take the `syncRoot` parameter. + The stores data in an container and provides an object that can be set and used to synchronize access to the collection so that it is thread safe. The container can be recovered using the property. The synchronized object can be recovered using the property. It can only be set using one of the constructors that take the `syncRoot` parameter. ]]> diff --git a/xml/System.Collections.ObjectModel/Collection`1.xml b/xml/System.Collections.ObjectModel/Collection`1.xml index dff240d985e..5f86e274180 100644 --- a/xml/System.Collections.ObjectModel/Collection`1.xml +++ b/xml/System.Collections.ObjectModel/Collection`1.xml @@ -137,14 +137,14 @@ Example 1 - The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. + The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/CollectionT/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.ObjectModel/CollectionT/Overview/source.vb" id="Snippet1"::: Example 2 - The following code example shows how to derive a collection class from a constructed type of the generic class, and how to override the protected , , , and methods to provide custom behavior for the , , , and methods, and for setting the property. + The following code example shows how to derive a collection class from a constructed type of the generic class, and how to override the protected , , , and methods to provide custom behavior for the , , , and methods, and for setting the property. The custom behavior provided by this example is a `Changed` notification event that is raised at the end of each of the protected methods. The `Dinosaurs` class inherits `Collection` (`Collection(Of String)` in Visual Basic) and defines the `Changed` event, which uses a `DinosaursChangedEventArgs` class for the event information, and an enumeration to identify the kind of change. @@ -231,7 +231,7 @@ ## Examples - The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings with the constructor, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. + The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings with the constructor, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/CollectionT/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.ObjectModel/CollectionT/Overview/source.vb" id="Snippet1"::: @@ -355,7 +355,7 @@ ## Examples - The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. + The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/CollectionT/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.ObjectModel/CollectionT/Overview/source.vb" id="Snippet1"::: @@ -433,7 +433,7 @@ ## Examples - The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. + The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/CollectionT/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.ObjectModel/CollectionT/Overview/source.vb" id="Snippet1"::: @@ -505,7 +505,7 @@ ## Examples - The following code example shows how to derive a collection class from a constructed type of the generic class, and how to override the protected , , , and methods to provide custom behavior for the , , , and methods, and for setting the property. + The following code example shows how to derive a collection class from a constructed type of the generic class, and how to override the protected , , , and methods to provide custom behavior for the , , , and methods, and for setting the property. The custom behavior provided by this example is a `Changed` notification event that is raised at the end of each of the protected methods. The `Dinosaurs` class inherits `Collection` (`Collection(Of String)` in Visual Basic) and defines the `Changed` event, which uses a `DinosaursChangedEventArgs` class for the event information, and an enumeration to identify the kind of change. @@ -731,7 +731,7 @@ ## Examples - The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. + The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/CollectionT/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.ObjectModel/CollectionT/Overview/source.vb" id="Snippet1"::: @@ -881,7 +881,7 @@ ## Examples - The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. + The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/CollectionT/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.ObjectModel/CollectionT/Overview/source.vb" id="Snippet1"::: @@ -1035,7 +1035,7 @@ ## Examples - The following code example shows how to derive a collection class from a constructed type of the generic class, and how to override the protected , , , and methods to provide custom behavior for the , , , and methods, and for setting the property. + The following code example shows how to derive a collection class from a constructed type of the generic class, and how to override the protected , , , and methods to provide custom behavior for the , , , and methods, and for setting the property. The custom behavior provided by this example is a `Changed` notification event that is raised at the end of each of the protected methods. The `Dinosaurs` class inherits `Collection` (`Collection(Of String)` in Visual Basic) and defines the `Changed` event, which uses a `DinosaursChangedEventArgs` class for the event information, and an enumeration to identify the kind of change. @@ -1118,14 +1118,14 @@ This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - 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. + 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. Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. ## Examples - The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. + The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/CollectionT/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.ObjectModel/CollectionT/Overview/source.vb" id="Snippet1"::: @@ -1259,7 +1259,7 @@ ## Examples - The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. + The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/CollectionT/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.ObjectModel/CollectionT/Overview/source.vb" id="Snippet1"::: @@ -1333,7 +1333,7 @@ ## Examples - The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. + The following code example demonstrates many of the properties and methods of . The code example creates a collection of strings, uses the method to add several strings, displays the , and lists the strings. The example uses the method to find the index of a string and the method to determine whether a string is in the collection. The example inserts a string using the method and retrieves and sets strings using the default property (the indexer in C#). The example removes strings by string identity using the method and by index using the method. Finally, the method is used to clear all strings from the collection. :::code language="csharp" source="~/snippets/csharp/System.Collections.ObjectModel/CollectionT/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.ObjectModel/CollectionT/Overview/source.vb" id="Snippet1"::: @@ -1414,7 +1414,7 @@ ## Examples - The following code example shows how to derive a collection class from a constructed type of the generic class, and how to override the protected , , , and methods to provide custom behavior for the , , , and methods, and for setting the property. + The following code example shows how to derive a collection class from a constructed type of the generic class, and how to override the protected , , , and methods to provide custom behavior for the , , , and methods, and for setting the property. The custom behavior provided by this example is a `Changed` notification event that is raised at the end of each of the protected methods. The `Dinosaurs` class inherits `Collection` (`Collection(Of String)` in Visual Basic) and defines the `Changed` event, which uses a `DinosaursChangedEventArgs` class for the event information, and an enumeration to identify the kind of change. @@ -1490,7 +1490,7 @@ This method is an O(1) operation. ## Examples - The following code example shows how to derive a collection class from a constructed type of the generic class, and how to override the protected , , , and methods to provide custom behavior for the , , , and methods, and for setting the property. + The following code example shows how to derive a collection class from a constructed type of the generic class, and how to override the protected , , , and methods to provide custom behavior for the , , , and methods, and for setting the property. The custom behavior provided by this example is a `Changed` notification event that is raised at the end of each of the protected methods. The `Dinosaurs` class inherits `Collection` (`Collection(Of String)` in Visual Basic) and defines the `Changed` event, which uses a `DinosaursChangedEventArgs` class for the event information, and an enumeration to identify the kind of change. @@ -1769,7 +1769,7 @@ 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. + 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. ```csharp ICollection ic = ...; @@ -2301,7 +2301,7 @@ Retrieving the value of this property is an O(1) operation. ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - 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. + 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. Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. diff --git a/xml/System.Collections.ObjectModel/KeyedCollection`2.xml b/xml/System.Collections.ObjectModel/KeyedCollection`2.xml index 7140a29ad55..6c44836ab2a 100644 --- a/xml/System.Collections.ObjectModel/KeyedCollection`2.xml +++ b/xml/System.Collections.ObjectModel/KeyedCollection`2.xml @@ -96,12 +96,12 @@ Unlike dictionaries, an element of is not a key/value pair; instead, the entire element is the value and the key is embedded within the value. For example, an element of a collection derived from `KeyedCollection\` (`KeyedCollection(Of String, String)` in Visual Basic) might be "John Doe Jr." where the value is "John Doe Jr." and the key is "Doe"; or a collection of employee records containing integer keys could be derived from `KeyedCollection\`. The abstract method extracts the key from the element. - By default, the includes a lookup dictionary that you can obtain with the property. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior is overridden by specifying a dictionary creation threshold when you create the . The lookup dictionary is created the first time the number of elements exceeds that threshold. If you specify -1 as the threshold, the lookup dictionary is never created. + By default, the includes a lookup dictionary that you can obtain with the property. When an item is added to the , the item's key is extracted once and saved in the lookup dictionary for faster searches. This behavior is overridden by specifying a dictionary creation threshold when you create the . The lookup dictionary is created the first time the number of elements exceeds that threshold. If you specify -1 as the threshold, the lookup dictionary is never created. > [!NOTE] > When the internal lookup dictionary is used, it contains references to all the items in the collection if `TItem` is a reference type, or copies of all the items in the collection if `TItem` is a value type. Thus, using the lookup dictionary may not be appropriate if `TItem` is a value type. - You can access an item by its index or key by using the property. You can add items without a key, but these items can subsequently be accessed only by index. + You can access an item by its index or key by using the property. You can add items without a key, but these items can subsequently be accessed only by index. @@ -119,7 +119,7 @@ **Example 2** - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. @@ -340,7 +340,7 @@ ## Examples - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. The code example uses the constructor with a threshold of 0, so that the internal dictionary is created the first time an object is added to the collection. @@ -497,7 +497,7 @@ In order to maintain the connection between a `MutableKey` object and the `Mutab Example 1 - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. @@ -859,7 +859,7 @@ In order to maintain the connection between a `MutableKey` object and the `Mutab Example 1 - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. @@ -943,18 +943,18 @@ In order to maintain the connection between a `MutableKey` object and the `Mutab This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[key]` (`myCollection(key)` in Visual Basic). > [!NOTE] -> This property is distinct from the inherited property, which gets and sets elements by numeric index. However, if `TKey` is of type , this property masks the inherited property. In that case, you can access the inherited property by casting the to its base type. For example, `KeyedCollection` (`KeyedCollection(Of Integer, MyType)` in Visual Basic) can be cast to `Collection` (`Collection(Of MyType)` in Visual Basic). +> This property is distinct from the inherited property, which gets and sets elements by numeric index. However, if `TKey` is of type , this property masks the inherited property. In that case, you can access the inherited property by casting the to its base type. For example, `KeyedCollection` (`KeyedCollection(Of Integer, MyType)` in Visual Basic) can be cast to `Collection` (`Collection(Of MyType)` in Visual Basic). If the has a lookup dictionary, `key` is used to retrieve the element from the dictionary. If there is no lookup dictionary, the key of each element is extracted using the method and compared with the specified key. - 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. Retrieving the value of this property is an O(1) operation if the has a lookup dictionary; otherwise it is an O(`n`) operation, where `n` is . ## Examples This code example shows the minimum code necessary to derive a collection class from : overriding the method and providing a public constructor that delegates to a base class constructor. The code example also demonstrates many of the properties and methods inherited from and classes. - The code example calls both the property, which is read-only and retrieves by key, and the property, which is settable and retrieves by index. It shows how to access the latter property when the objects in the derived collection have integer keys, indistinguishable from the integers used for indexed retrieval. + The code example calls both the property, which is read-only and retrieves by key, and the property, which is settable and retrieves by index. It shows how to access the latter property when the objects in the derived collection have integer keys, indistinguishable from the integers used for indexed retrieval. The `SimpleOrder` class is a very simple requisition list that contains `OrderItem` objects, each of which represents a line item in the order. The key of `OrderItem` is immutable, an important consideration for classes that derive from . For a code example that uses mutable keys, see . @@ -1113,7 +1113,7 @@ In order to maintain the connection between a `MutableKey` object and the `Mutab Example 1 - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. @@ -1197,20 +1197,20 @@ In order to maintain the connection between a `MutableKey` object and the `Mutab ## Notes for Implementers - Override this method to provide customized behavior for setting the property inherited from the generic class. + Override this method to provide customized behavior for setting the property inherited from the generic class. > [!NOTE] -> This method does not affect the behavior of the property, which is read-only. +> This method does not affect the behavior of the property, which is read-only. Call the base class implementation of this method to set the item in the underlying collection and to update the lookup dictionary. ## Examples - This section contains two code examples that demonstrate overriding the method to provide custom behavior for setting the property. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. + This section contains two code examples that demonstrate overriding the method to provide custom behavior for setting the property. The first example adds a custom notification event and the second provides support for a collection of objects with mutable keys. Example 1 - The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. + The following code example shows how to override the protected , , , and methods, to provide custom behavior for the , , and methods, and for setting the default property (the indexer in C#). The custom behavior provided in this example is a notification event named `Changed`, which is raised at the end of each of the overridden methods. The code example creates the `SimpleOrder` class, which derives from and represents a simple order form. The order form contains `OrderItem` objects representing items ordered. The code example also creates a `SimpleOrderChangedEventArgs` class to contain the event information, and an enumeration to identify the type of change. diff --git a/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml b/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml index c1a755df436..1b6a2ba432f 100644 --- a/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml +++ b/xml/System.Collections.ObjectModel/ReadOnlyCollection`1.xml @@ -701,7 +701,7 @@ ## Remarks This property provides the ability to access a specific element in the collection by using the following C# syntax: `myCollection[index]` (`myCollection(index)` in Visual Basic). - 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. + 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. Retrieving the value of this property is an O(1) operation. @@ -1415,7 +1415,7 @@ 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. + 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. ```csharp ICollection ic = ...; @@ -2013,7 +2013,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - 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. + 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. Retrieving the value of this property is an O(1) operation. diff --git a/xml/System.Collections.Specialized/BitVector32.xml b/xml/System.Collections.Specialized/BitVector32.xml index 1ff1dbad3a5..75bff006f0d 100644 --- a/xml/System.Collections.Specialized/BitVector32.xml +++ b/xml/System.Collections.Specialized/BitVector32.xml @@ -63,7 +63,7 @@ A structure can be set up to contain either sections for small integers or bit flags for Booleans, but not both. A is a window into the and is composed of the smallest number of consecutive bits that can contain the maximum value specified in . For example, a section with a maximum value of 1 is composed of only one bit, whereas a section with a maximum value of 5 is composed of three bits. You can create a with a maximum value of 1 to serve as a Boolean, thereby allowing you to store integers and Booleans in the same . - Some members can be used for a that is set up as sections, while other members can be used for one that is set up as bit flags. For example, the property is the indexer for a that is set up as sections, and the property is the indexer for a that is set up as bit flags. creates a series of masks that can be used to access individual bits in a that is set up as bit flags. + Some members can be used for a that is set up as sections, while other members can be used for one that is set up as bit flags. For example, the property is the indexer for a that is set up as sections, and the property is the indexer for a that is set up as bit flags. creates a series of masks that can be used to access individual bits in a that is set up as bit flags. Using a mask on a that is set up as sections might cause unexpected results. @@ -71,7 +71,7 @@ ## Examples The following code example uses a as a collection of bit flags. - + :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/BitVector32/Overview/bitvector32_bitflags.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Specialized/BitVector32/Overview/bitvector32_bitflags.vb" id="Snippet1"::: @@ -563,7 +563,7 @@ property. + To access the value of the individual sections or bit flags, use the property. Retrieving the value of this property is an O(1) operation. @@ -799,7 +799,7 @@ A is a window into the and is composed of the smallest number of consecutive bits that can contain the maximum value specified in . For example, a section with a maximum value of 1 is composed of only one bit, whereas a section with a maximum value of 5 is composed of three bits. You can create a with a maximum value of 1 to serve as a Boolean, thereby allowing you to store integers and Booleans in the same . - 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + 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](/dotnet/visual-basic/language-reference/modifiers/default), 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. @@ -863,7 +863,7 @@ Using this property on a that is set up as sections might cause unexpected results. - 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + 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](/dotnet/visual-basic/language-reference/modifiers/default), 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. diff --git a/xml/System.Collections.Specialized/HybridDictionary.xml b/xml/System.Collections.Specialized/HybridDictionary.xml index 9e6d79e0379..9154c4c1c07 100644 --- a/xml/System.Collections.Specialized/HybridDictionary.xml +++ b/xml/System.Collections.Specialized/HybridDictionary.xml @@ -437,7 +437,7 @@ A key cannot be `null`, but a value can. - You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. When the number of elements becomes greater than the optimal size for a , the elements are copied from the to a . However, this only happens once. If the collection is already stored in a and the number of elements falls below the optimal size for a , the collection remains in the . @@ -870,7 +870,7 @@ This method uses the collection's objects' and implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. @@ -930,7 +930,7 @@ This method uses the collection's objects' and implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. @@ -990,9 +990,9 @@ This method uses the collection's objects' and implements the property because it is required by the interface. + implements the property because it is required by the interface. - Derived classes can provide a synchronized version of the using the property. + Derived classes can provide a synchronized version of the using the property. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -1072,11 +1072,11 @@ This method uses the collection's objects' and property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. A key cannot be `null`, but a value can. To distinguish between `null` that is returned because the specified key is not found and `null` that is returned because the value of the specified key is `null`, use the method to determine if the key exists in the list. - 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. + 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. Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. @@ -1286,7 +1286,7 @@ This method uses the collection's objects' and using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections.Specialized/IOrderedDictionary.xml b/xml/System.Collections.Specialized/IOrderedDictionary.xml index 1fb21161aeb..fc8e3fcc231 100644 --- a/xml/System.Collections.Specialized/IOrderedDictionary.xml +++ b/xml/System.Collections.Specialized/IOrderedDictionary.xml @@ -66,7 +66,7 @@ Each pair must have a unique key that is not `null`, but the value can be `null` and does not have to be unique. The interface allows the contained keys and values to be enumerated, but it does not imply any particular sort order. The `foreach` statement of the C# language (`For Each` in Visual Basic) returns an object of the type of the elements in the collection. Because each element of the is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is , as the following example shows. - + :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/IOrderedDictionary/Overview/remarks.cs" id="Snippet03"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Specialized/IOrderedDictionary/Overview/remarks.vb" id="Snippet03"::: @@ -142,7 +142,7 @@ Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + Initially, the enumerator is positioned before the first element in the collection. also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . returns the same object until either or is called. sets to the next element. @@ -313,7 +313,7 @@ accepts `null` as a valid value and allows duplicate elements. -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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. +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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. This property allows you to access a specific element in the collection by using the following syntax: diff --git a/xml/System.Collections.Specialized/ListDictionary.xml b/xml/System.Collections.Specialized/ListDictionary.xml index 9c8f75ca771..aeadaf88cd7 100644 --- a/xml/System.Collections.Specialized/ListDictionary.xml +++ b/xml/System.Collections.Specialized/ListDictionary.xml @@ -314,7 +314,7 @@ ## Remarks An object that has no correlation between its state and its hash code value should typically not be used as the key. For example, String objects are better than StringBuilder objects for use as keys. - You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. This method is an O(`n`) operation, where `n` is . @@ -754,7 +754,7 @@ This method uses the collection's objects' and implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements. @@ -814,7 +814,7 @@ This method uses the collection's objects' and implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. @@ -874,9 +874,9 @@ This method uses the collection's objects' and implements the property because it is required by the interface. + implements the property because it is required by the interface. - Derived classes can provide a synchronized version of the using the property. + Derived classes can provide a synchronized version of the using the property. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -956,11 +956,11 @@ This method uses the collection's objects' and property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. A key cannot be `null`, but a value can. To distinguish between `null` that is returned because the specified key is not found and `null` that is returned because the value of the specified key is `null`, use the method to determine if the key exists in the list. - 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. + 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. This method is an O(`n`) operation, where `n` is . @@ -1168,7 +1168,7 @@ This method uses the collection's objects' and using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections.Specialized/NameObjectCollectionBase+KeysCollection.xml b/xml/System.Collections.Specialized/NameObjectCollectionBase+KeysCollection.xml index 2bbcf0fab03..eea666a47d1 100644 --- a/xml/System.Collections.Specialized/NameObjectCollectionBase+KeysCollection.xml +++ b/xml/System.Collections.Specialized/NameObjectCollectionBase+KeysCollection.xml @@ -314,7 +314,7 @@ ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]` (In Visual Basic, `myCollection(index)`). - 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + 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](/dotnet/visual-basic/language-reference/modifiers/default), 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. @@ -446,7 +446,7 @@ using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -454,7 +454,7 @@ ## Examples The following code example shows how to lock the collection using the during the entire enumeration. - + :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase+KeysCollection/System.Collections.ICollection.IsSynchronized/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Specialized/NameObjectCollectionBase+KeysCollection/System.Collections.ICollection.IsSynchronized/source.vb" id="Snippet1"::: @@ -518,7 +518,7 @@ using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections.Specialized/NameObjectCollectionBase.xml b/xml/System.Collections.Specialized/NameObjectCollectionBase.xml index 3908325843c..6b8f13e883c 100644 --- a/xml/System.Collections.Specialized/NameObjectCollectionBase.xml +++ b/xml/System.Collections.Specialized/NameObjectCollectionBase.xml @@ -1985,11 +1985,11 @@ object is not synchronized. Derived classes can provide a synchronized version of the using the property. + A object is not synchronized. Derived classes can provide a synchronized version of the using the property. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. + The following code example shows how to lock the collection using the property during the entire enumeration. :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/NameObjectCollectionBase/Overview/remarks.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Specialized/NameObjectCollectionBase/Overview/remarks.vb" id="Snippet2"::: @@ -2054,7 +2054,7 @@ class using the property. The synchronizing code must perform operations on the property of the object, not directly on the object. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the class using the property. The synchronizing code must perform operations on the property of the object, not directly on the object. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections.Specialized/NameValueCollection.xml b/xml/System.Collections.Specialized/NameValueCollection.xml index f7230b72e63..ea32a8cdcc3 100644 --- a/xml/System.Collections.Specialized/NameValueCollection.xml +++ b/xml/System.Collections.Specialized/NameValueCollection.xml @@ -1573,7 +1573,7 @@ This property cannot be set. To set the value at a specified index, use `Item[GetKey(index)]`. - 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. Retrieving the values at the specified index is an O(`n`) operation, where `n` is the number of values. @@ -1654,7 +1654,7 @@ > [!CAUTION] > This property returns `null` in the following cases: 1) if the specified key is not found; and 2) if the specified key is found and its associated value is `null`. This property does not distinguish between the two cases. - 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. Retrieving or setting the values associated with the specified key is an O(`n`) operation, where `n` is the number of values. diff --git a/xml/System.Collections.Specialized/OrderedDictionary.xml b/xml/System.Collections.Specialized/OrderedDictionary.xml index 6913ba5050d..e8ebcab8fbe 100644 --- a/xml/System.Collections.Specialized/OrderedDictionary.xml +++ b/xml/System.Collections.Specialized/OrderedDictionary.xml @@ -493,7 +493,7 @@ ## Remarks A key cannot be `null`, but a value can be. - You can also use the property to add new elements by setting the value of a key that does not exist in the collection; however, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements but instead throws . + You can also use the property to add new elements by setting the value of a key that does not exist in the collection; however, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements but instead throws . @@ -607,7 +607,7 @@ method, the property is set to zero and references to other objects from elements of the collection are also released. The capacity is not changed as a result of calling this method. + After calling the method, the property is set to zero and references to other objects from elements of the collection are also released. The capacity is not changed as a result of calling this method. @@ -674,7 +674,7 @@ property can return a null value if the key does not exist or if the key is `null`. Use the method to determine if a specific key exists in the collection. + Using the property can return a null value if the key does not exist or if the key is `null`. Use the method to determine if a specific key exists in the collection. This method uses the collection's objects' and methods on `item` to determine whether `item` exists. @@ -793,7 +793,7 @@ This method uses the collection's objects' and collection. In this example, the property is used to remove the last item in the . This code is part of a larger code example that can be viewed at . + The following code example demonstrates the modification of an collection. In this example, the property is used to remove the last item in the . This code is part of a larger code example that can be viewed at . :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.vb" id="Snippet02"::: @@ -1082,7 +1082,7 @@ This method uses the collection's objects' and collection. In this example, the property is used to determine whether the can be modified. This code is part of a larger code example that can be viewed at . + The following code example demonstrates the modification of an collection. In this example, the property is used to determine whether the can be modified. This code is part of a larger code example that can be viewed at . :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.vb" id="Snippet02"::: @@ -1161,7 +1161,7 @@ This method uses the collection's objects' and property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. ]]> @@ -1234,14 +1234,14 @@ This method uses the collection's objects' and property to add new elements by setting the value of a key that does not exist in the collection (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the collection (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. A key cannot be `null`, but a value can be. To distinguish between `null` that is returned because the specified key is not found and `null` that is returned because the value of the specified key is `null`, use the method to determine if the key exists in the . ## Examples - The following code example demonstrates the modification of an collection. In this example, the property is used to modify the dictionary entry with the key `"testKey2"`. This code is part of a larger code example that can be viewed at . + The following code example demonstrates the modification of an collection. In this example, the property is used to modify the dictionary entry with the key `"testKey2"`. This code is part of a larger code example that can be viewed at . :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.vb" id="Snippet02"::: @@ -1492,7 +1492,7 @@ This method uses the collection's objects' and collection. In this example, the method is used with the property to remove the last entry from the . This code is part of a larger code example that can be viewed at . + The following code example demonstrates the modification of an collection. In this example, the method is used with the property to remove the last entry from the . This code is part of a larger code example that can be viewed at . :::code language="csharp" source="~/snippets/csharp/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.cs" id="Snippet02"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections.Specialized/OrderedDictionary/Overview/OrderedDictionary1.vb" id="Snippet02"::: diff --git a/xml/System.Collections.Specialized/StringCollection.xml b/xml/System.Collections.Specialized/StringCollection.xml index 4e04641d930..7817a3c213c 100644 --- a/xml/System.Collections.Specialized/StringCollection.xml +++ b/xml/System.Collections.Specialized/StringCollection.xml @@ -839,7 +839,7 @@ This method uses the collection's objects' and implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. @@ -901,7 +901,7 @@ This method uses the collection's objects' and implements the property because it is required by the interface. + implements the property because it is required by the interface. Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -971,7 +971,7 @@ This method uses the collection's objects' and accepts `null` as a valid value and allows duplicate elements. - 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + 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](/dotnet/visual-basic/language-reference/modifiers/default), 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. @@ -1185,7 +1185,7 @@ This method uses the collection's objects' and using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -1809,7 +1809,7 @@ This method uses the collection's objects' and property. Visual Basic implements as a default property, which provides the same indexing functionality. + 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. accepts `null` as a valid value and allows duplicate elements. diff --git a/xml/System.Collections.Specialized/StringDictionary.xml b/xml/System.Collections.Specialized/StringDictionary.xml index e4dffefad67..579e8ddfd27 100644 --- a/xml/System.Collections.Specialized/StringDictionary.xml +++ b/xml/System.Collections.Specialized/StringDictionary.xml @@ -690,7 +690,7 @@ This method uses the collection's objects' and instance is not synchronized. Derived classes can provide a synchronized version of the using the property. + A instance is not synchronized. Derived classes can provide a synchronized version of the using the property. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -768,7 +768,7 @@ This method uses the collection's objects' and method to determine if the key exists in the list. - 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. + 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. Retrieving the value of this property is an O(1) operation; setting the property is also an O(1) operation. @@ -965,7 +965,7 @@ This method uses the collection's objects' and using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections/ArrayList.xml b/xml/System.Collections/ArrayList.xml index 0cd69e7053d..72057f97854 100644 --- a/xml/System.Collections/ArrayList.xml +++ b/xml/System.Collections/ArrayList.xml @@ -127,7 +127,7 @@ The is not guaranteed to be sorted. You must sort the by calling its method prior to performing operations (such as ) that require the to be sorted. To maintain a collection that is automatically sorted as new elements are added, you can use the class. - The capacity of an is the number of elements the can hold. As elements are added to an , the capacity is automatically increased as required through reallocation. The capacity can be decreased by calling or by setting the property explicitly. + The capacity of an is the number of elements the can hold. As elements are added to an , the capacity is automatically increased as required through reallocation. The capacity can be decreased by calling or by setting the property explicitly. **.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. @@ -946,7 +946,7 @@ This method is an `O(1)` operation. is always greater than or equal to . If exceeds while adding elements, the capacity is automatically increased by reallocating the internal array before copying the old elements and adding the new elements. - The capacity can be decreased by calling or by setting the property explicitly. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity. + The capacity can be decreased by calling or by setting the property explicitly. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity. 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. @@ -1014,7 +1014,7 @@ This method is an `O(1)` operation. ## Remarks is set to zero, and references to other objects from elements of the collection are also released. - remains unchanged. To reset the capacity of the , call or set the property directly. Trimming an empty sets the capacity of the to the default capacity. + remains unchanged. To reset the capacity of the , call or set the property directly. Trimming an empty sets the capacity of the to the default capacity. This method is an `O(n)` operation, where `n` is . @@ -2718,19 +2718,19 @@ This method uses the collection's objects' and property. Visual Basic implements as a default property, which provides the same indexing functionality. + 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. Retrieving the value of this property is an `O(1)` operation; setting the property is also an `O(1)` operation. ## Examples - The following code example creates an and adds several items. The example demonstrates accessing elements with the property (the indexer in C#), and changing an element by assigning a new value to the property for a specified index. The example also shows that the property cannot be used to access or add elements outside the current size of the list. + The following code example creates an and adds several items. The example demonstrates accessing elements with the property (the indexer in C#), and changing an element by assigning a new value to the property for a specified index. The example also shows that the property cannot be used to access or add elements outside the current size of the list. :::code language="csharp" source="~/snippets/csharp/System.Collections/ArrayList/Item/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/ArrayList/Item/source.vb" id="Snippet1"::: - The following example uses the property explicitly to assign values to items in the list. The example defines a class that inherits an and adds a method to scramble the list items. + The following example uses the property explicitly to assign values to items in the list. The example defines a class that inherits an and adds a method to scramble the list items. :::code language="csharp" source="~/snippets/csharp/System.Collections/ArrayList/Item/source2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/ArrayList/Item/source2.vb" id="Snippet2"::: @@ -3306,7 +3306,7 @@ This method uses the collection's objects' and property is decreased by one. + After the element is removed, the size of the collection is adjusted and the value of the property is decreased by one. In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hash table. @@ -4230,7 +4230,7 @@ This method uses the collection's objects' and , use the method. However, derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + To create a synchronized version of the , use the method. However, derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections/BitArray.xml b/xml/System.Collections/BitArray.xml index 4e11cad169c..a955d95e6d1 100644 --- a/xml/System.Collections/BitArray.xml +++ b/xml/System.Collections/BitArray.xml @@ -82,7 +82,7 @@ class is a collection class in which the capacity is always the same as the count. Elements are added to a by increasing the property; elements are deleted by decreasing the property. The size of a is controlled by the client; indexing past the end of the throws an . The class provides methods that are not found in other collections, including those that allow multiple elements to be modified at once using a filter, such as , , , , and . + The class is a collection class in which the capacity is always the same as the count. Elements are added to a by increasing the property; elements are deleted by decreasing the property. The size of a is controlled by the client; indexing past the end of the throws an . The class provides methods that are not found in other collections, including those that allow multiple elements to be modified at once using a filter, such as , , , , and . The class is a structure that provides the same functionality as , but with faster performance. is faster because it is a value type and therefore allocated on the stack, whereas is a reference type and, therefore, allocated on the heap. @@ -953,7 +953,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. @@ -1011,7 +1011,7 @@ implements the property because it is required by the interface. + implements the property because it is required by the interface. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -1081,7 +1081,7 @@ ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - 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. + 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. Retrieving the value of this property is an `O(1)` operation; setting the property is also an `O(1)` operation. @@ -1591,7 +1591,7 @@ The current is updated and returned. using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections/CollectionBase.xml b/xml/System.Collections/CollectionBase.xml index f0af4455f34..147b19c3c2b 100644 --- a/xml/System.Collections/CollectionBase.xml +++ b/xml/System.Collections/CollectionBase.xml @@ -83,7 +83,7 @@ A instance is always modifiable. See for a read-only version of this class. - The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required through reallocation. The capacity can be decreased by setting the property explicitly. + The capacity of a is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required through reallocation. The capacity can be decreased by setting the property explicitly. @@ -281,7 +281,7 @@ A instance is always modifiable. See is always greater than or equal to . If exceeds while adding elements, the capacity is automatically increased by reallocating the internal array before copying the old elements and adding the new elements. - The capacity can be decreased by setting the property explicitly. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity. + The capacity can be decreased by setting the property explicitly. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity. 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. @@ -534,7 +534,7 @@ A instance is always modifiable. See property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. ]]> @@ -585,7 +585,7 @@ A instance is always modifiable. See property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. Retrieving the value of this property is an `O(1)` operation. @@ -648,7 +648,7 @@ A instance is always modifiable. See property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. If the process fails, the collection reverts back to its previous state. @@ -714,7 +714,7 @@ A instance is always modifiable. See property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -782,7 +782,7 @@ A instance is always modifiable. See property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. If the process fails, the collection reverts back to its previous state. @@ -865,7 +865,7 @@ A instance is always modifiable. See property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The collection reverts back to its previous state if one of the following occurs: @@ -939,7 +939,7 @@ A instance is always modifiable. See property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. If the process fails, the collection reverts back to its previous state. @@ -1021,7 +1021,7 @@ A instance is always modifiable. See property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The collection reverts back to its previous state if one of the following occurs: @@ -1097,7 +1097,7 @@ A instance is always modifiable. See property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. If the process fails, the collection reverts back to its previous state. @@ -1182,7 +1182,7 @@ A instance is always modifiable. See property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The collection reverts back to its previous state if one of the following occurs: @@ -1253,7 +1253,7 @@ A instance is always modifiable. See . It is intended to be overridden by a derived class to perform additional action when the specified element is validated. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -1471,7 +1471,7 @@ A instance is always modifiable. See instance is not synchronized. Derived classes can provide a synchronized version of the using the property. + A instance is not synchronized. Derived classes can provide a synchronized version of the using the property. Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. @@ -1535,7 +1535,7 @@ A instance is always modifiable. See using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections/DictionaryBase.xml b/xml/System.Collections/DictionaryBase.xml index bb4b698f276..1455cc240b4 100644 --- a/xml/System.Collections/DictionaryBase.xml +++ b/xml/System.Collections/DictionaryBase.xml @@ -391,7 +391,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. Retrieving the value of this property is an `O(1)` operation. @@ -531,7 +531,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. Retrieving the value of this property is an `O(1)` operation. @@ -586,7 +586,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks The default implementation of this method is intended to be overridden by a derived class to perform some action before the collection is cleared. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -650,7 +650,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks The default implementation of this method is intended to be overridden by a derived class to perform some action after the collection is cleared. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -726,7 +726,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks The default implementation of this method returns `currentValue`. It is intended to be overridden by a derived class to perform additional action when the specified element is retrieved. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -799,7 +799,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks The default implementation of this method is intended to be overridden by a derived class to perform some action before the specified element is inserted. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -885,7 +885,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks The default implementation of this method is intended to be overridden by a derived class to perform some action after the specified element is inserted. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -960,7 +960,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks The default implementation of this method is intended to be overridden by a derived class to perform some action before the specified element is removed. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -1045,7 +1045,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks The default implementation of this method is intended to be overridden by a derived class to perform some action after the specified element is removed. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -1122,7 +1122,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks The default implementation of this method is intended to be overridden by a derived class to perform some action before the specified element is set. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -1210,7 +1210,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks The default implementation of this method is intended to be overridden by a derived class to perform some action after the specified element is set. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -1285,7 +1285,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks The default implementation of this method is intended to be overridden by a derived class to perform some action when the specified element is validated. - The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. + The On* methods are invoked only on the instance returned by the property, but not on the instance returned by the property. The default implementation of this method is an `O(1)` operation. @@ -1357,14 +1357,14 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen object is not synchronized. Derived classes can provide a synchronized version of the class using the property. + A object is not synchronized. Derived classes can provide a synchronized version of the class using the property. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. ## Examples - The following code example shows how to lock the collection using the property during the entire enumeration. + The following code example shows how to lock the collection using the property during the entire enumeration. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryBase/Overview/source2.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryBase/Overview/source2.vb" id="Snippet3"::: @@ -1425,14 +1425,14 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen class using the property. The synchronizing code must perform operations on the property of the object, not directly on the object. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the class using the property. The synchronizing code must perform operations on the property of the object, not directly on the object. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. ## Examples - The following code example shows how to lock the collection using the property during the entire enumeration. + The following code example shows how to lock the collection using the property during the entire enumeration. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryBase/Overview/source2.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryBase/Overview/source2.vb" id="Snippet3"::: @@ -1500,7 +1500,7 @@ The C# [foreach](/dotnet/csharp/language-reference/keywords/foreach-in) statemen ## Remarks An object that has no correlation between its state and its hash code value should typically not be used as the key. For example, objects are better than objects for use as keys. - You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. This method is an `O(1)` operation. @@ -1776,7 +1776,7 @@ This method uses the collection's objects' and property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. Retrieving the value of this property is an `O(1)` operation; setting the property is also an `O(1)` operation. @@ -1848,7 +1848,7 @@ This method uses the collection's objects' and object is unspecified, but is the same order as the associated values in the object returned by the property. + The order of the keys in the object is unspecified, but is the same order as the associated values in the object returned by the property. The returned is not a static copy; instead, the refers back to the keys in the original object. Therefore, changes to the continue to be reflected in the returned . @@ -1857,7 +1857,7 @@ This method uses the collection's objects' and class and uses that implementation to create a dictionary of keys and values that have a property of 5 characters or less. + The following code example implements the class and uses that implementation to create a dictionary of keys and values that have a property of 5 characters or less. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryBase/Overview/dictionarybase.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryBase/Overview/dictionarybase.vb" id="Snippet1"::: @@ -1993,7 +1993,7 @@ This method uses the collection's objects' and object is unspecified, but is the same order as the associated keys in the object returned by the property. + The order of the values in the object is unspecified, but is the same order as the associated keys in the object returned by the property. The returned is not a static copy; instead, the refers back to the values in the original object. Therefore, changes to the continue to be reflected in the returned . @@ -2002,7 +2002,7 @@ This method uses the collection's objects' and class and uses that implementation to create a dictionary of keys and values that have a property of 5 characters or less. + The following code example implements the class and uses that implementation to create a dictionary of keys and values that have a property of 5 characters or less. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryBase/Overview/dictionarybase.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryBase/Overview/dictionarybase.vb" id="Snippet1"::: diff --git a/xml/System.Collections/DictionaryEntry.xml b/xml/System.Collections/DictionaryEntry.xml index 0f6ada8e9f0..3543112bdcc 100644 --- a/xml/System.Collections/DictionaryEntry.xml +++ b/xml/System.Collections/DictionaryEntry.xml @@ -257,7 +257,7 @@ The property. This code example is part of a larger example provided for the class. + The following example demonstrates the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet9"::: @@ -320,7 +320,7 @@ The property. This code example is part of a larger example provided for the class. + The following example demonstrates the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet9"::: diff --git a/xml/System.Collections/Hashtable.xml b/xml/System.Collections/Hashtable.xml index 4d9deb0e07b..f12eb671752 100644 --- a/xml/System.Collections/Hashtable.xml +++ b/xml/System.Collections/Hashtable.xml @@ -1757,7 +1757,7 @@ Each element is a key/value pair stored in a property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. If is less than the capacity of the , 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 . @@ -3061,13 +3061,13 @@ This method uses the collection's objects' and property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the ; for example, `myCollection["myNonexistentKey"] = myValue`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. A key cannot be `null`, but a value can be. To distinguish between `null` that is returned because the specified key is not found and `null` that is returned because the value of the specified key is `null`, use the method or the method to determine if the key exists in the list. Retrieving the value of this property is an `O(1)` operation; setting the property is also an `O(1)` operation. - 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. + 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. ]]> @@ -3527,7 +3527,7 @@ This method uses the collection's objects' and , use the method. However, derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + To create a synchronized version of the , use the method. However, derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections/ICollection.xml b/xml/System.Collections/ICollection.xml index e840c11dfa6..ae71e04b0c3 100644 --- a/xml/System.Collections/ICollection.xml +++ b/xml/System.Collections/ICollection.xml @@ -245,8 +245,8 @@ The interface is the base interface for cl Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. - + The following code example shows how to lock the collection using the property during the entire enumeration. + :::code language="csharp" source="~/snippets/csharp/System.Collections/ICollection/IsSynchronized/remarks.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/ICollection/IsSynchronized/remarks.vb" id="Snippet1"::: @@ -304,7 +304,7 @@ The interface is the base interface for cl ## Remarks For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: @@ -313,7 +313,7 @@ The interface is the base interface for cl Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. + The following code example shows how to lock the collection using the property during the entire enumeration. :::code language="csharp" source="~/snippets/csharp/System.Collections/ICollection/IsSynchronized/remarks.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/ICollection/IsSynchronized/remarks.vb" id="Snippet1"::: diff --git a/xml/System.Collections/IDictionary.xml b/xml/System.Collections/IDictionary.xml index d56a48fa396..179d65819cc 100644 --- a/xml/System.Collections/IDictionary.xml +++ b/xml/System.Collections/IDictionary.xml @@ -157,7 +157,7 @@ property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. Implementations can vary in whether they allow the key to be `null`. @@ -360,7 +360,7 @@ This method uses the collection's objects' and also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + Initially, the enumerator is positioned before the first element in the collection. also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . returns the same object until either or is called. sets to the next element. @@ -431,7 +431,7 @@ This method uses the collection's objects' and property. This code example is part of a larger example provided for the class. + The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet6"::: @@ -493,7 +493,7 @@ This method uses the collection's objects' and property. This code example is part of a larger example provided for the class. + The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet4"::: @@ -562,16 +562,16 @@ This method uses the collection's objects' and property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. Implementations can vary in whether they allow the key to be `null`. - The C# language uses the `this`[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. + The C# language uses the `this`[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. ## Examples - The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet13"::: @@ -635,12 +635,12 @@ This method uses the collection's objects' and object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. + The order of the keys in the returned object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. ## Examples - The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet10"::: @@ -768,12 +768,12 @@ This method uses the collection's objects' and object is unspecified, but is guaranteed to be the same order as the corresponding keys in the returned by the property. + The order of the values in the returned object is unspecified, but is guaranteed to be the same order as the corresponding keys in the returned by the property. ## Examples - The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + The following code example demonstrates how to implement the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet11"::: diff --git a/xml/System.Collections/IEnumerable.xml b/xml/System.Collections/IEnumerable.xml index 7ff084dd53e..8c25c823f8f 100644 --- a/xml/System.Collections/IEnumerable.xml +++ b/xml/System.Collections/IEnumerable.xml @@ -59,19 +59,19 @@ Exposes an enumerator, which supports a simple iteration over a non-generic collection. - is the base interface for all non-generic collections that can be enumerated. For the generic version of this interface see . contains a single method, , which returns an . provides the ability to iterate through the collection by exposing a property and and methods. - + is the base interface for all non-generic collections that can be enumerated. For the generic version of this interface see . contains a single method, , which returns an . provides the ability to iterate through the collection by exposing a property and and methods. + It is a best practice to implement and on your collection classes to enable the `foreach` (`For Each` in Visual Basic) syntax, however implementing is not required. If your collection does not implement , you must still follow the iterator pattern to support this syntax by providing a `GetEnumerator` method that returns an interface, class or struct. When using Visual Basic, you must provide an implementation, which is returned by `GetEnumerator`. When developing with C# you must provide a class that contains a `Current` property, and `MoveNext` and `Reset` methods as described by , but the class does not have to implement . - -## Examples + +## Examples The following code example demonstrates the best practice for iterating a custom collection by implementing the and interfaces. In this example, members of these interfaces are not explicitly called, but they are implemented to support the use of `foreach` (`For Each` in Visual Basic) to iterate through the collection. This example is a complete Console app. To compile the Visual Basic app, change the **Startup object** to **Sub Main** in the project's **Properties** page. - + :::code language="csharp" source="~/snippets/csharp/System.Collections/IEnumerable/Overview/ienumerator.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Collections/IEnumerable/Overview/ienumerator.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Collections/IEnumerable/Overview/ienumerator.vb" id="Snippet1"::: + ]]> @@ -131,31 +131,31 @@ Returns an enumerator that iterates through a collection. An object that can be used to iterate through the collection. - method 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 . - - 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 returns `false`, is undefined. To set to the first element of the collection again, you can call followed by . - - If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. - - - -## Examples - The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`For Each` in Visual Basic). This code example is part of a larger example for the interface. - + method 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 . + + 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 returns `false`, is undefined. To set to the first element of the collection again, you can call followed by . + + If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization. + + + +## Examples + The following code example demonstrates the implementation of the interfaces for a custom collection. In this example, is not explicitly called, but it is implemented to support the use of `foreach` (`For Each` in Visual Basic). This code example is part of a larger example for the interface. + :::code language="csharp" source="~/snippets/csharp/System.Collections/IEnumerable/Overview/ienumerator.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Collections/IEnumerable/Overview/ienumerator.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Collections/IEnumerable/Overview/ienumerator.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Collections/IList.xml b/xml/System.Collections/IList.xml index 5c708d42924..6711b38cfa9 100644 --- a/xml/System.Collections/IList.xml +++ b/xml/System.Collections/IList.xml @@ -599,7 +599,7 @@ This method uses the collection's objects' and property. Visual Basic implements as a default property, which provides the same indexing functionality. + 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. diff --git a/xml/System.Collections/IStructuralComparable.xml b/xml/System.Collections/IStructuralComparable.xml index a30c5fb62d1..f3c89e5397b 100644 --- a/xml/System.Collections/IStructuralComparable.xml +++ b/xml/System.Collections/IStructuralComparable.xml @@ -57,7 +57,7 @@ > [!NOTE] > The interface supports only structural comparisons for sorting or ordering. The interface supports custom comparisons for structural equality. - The .NET Framework provides two default comparers. One is returned by the property; the other is returned by the property. + The .NET Framework provides two default comparers. One is returned by the property; the other is returned by the property. The generic tuple classes (, , , and so on) and the class provide explicit implementations of the interface. By casting (in C#) or converting (in Visual Basic) the current instance of an array or tuple to an interface value and providing your implementation as an argument to the method, you can define a custom sort order for the array or collection. However, you do not call the method directly in most cases. Instead, the method is called by sorting methods such as . In this case, you define your implementation and pass it as an argument to a sorting method or collection object's class constructor. The method with your custom comparer is then called automatically whenever the collection is sorted. diff --git a/xml/System.Collections/IStructuralEquatable.xml b/xml/System.Collections/IStructuralEquatable.xml index 53af1691ec3..62ee082b3df 100644 --- a/xml/System.Collections/IStructuralEquatable.xml +++ b/xml/System.Collections/IStructuralEquatable.xml @@ -47,32 +47,32 @@ Defines methods to support the comparison of objects for structural equality. - interface enables you to implement customized comparisons to check for the structural equality of collection objects. That is, you can create your own definition of structural equality and specify that this definition be used with a collection type that accepts the interface. The interface has two members: , which tests for equality by using a specified implementation, and , which returns identical hash codes for objects that are equal. - + interface enables you to implement customized comparisons to check for the structural equality of collection objects. That is, you can create your own definition of structural equality and specify that this definition be used with a collection type that accepts the interface. The interface has two members: , which tests for equality by using a specified implementation, and , which returns identical hash codes for objects that are equal. + > [!NOTE] -> The interface supports only custom comparisons for structural equality. The interface supports custom structural comparisons for sorting and ordering. - - The .NET Framework also provides default equality comparers, which are returned by the and properties. For more information, see the example. - - The generic tuple classes (, , , and so on) and the class provide explicit implementations of the interface. By casting (in C#) or converting (in Visual Basic) the current instance of an array or tuple to an interface value and providing your implementation as an argument to the method, you can define a custom equality comparison for the array or collection. - - - +> The interface supports only custom comparisons for structural equality. The interface supports custom structural comparisons for sorting and ordering. + + The .NET Framework also provides default equality comparers, which are returned by the and properties. For more information, see the example. + + The generic tuple classes (, , , and so on) and the class provide explicit implementations of the interface. By casting (in C#) or converting (in Visual Basic) the current instance of an array or tuple to an interface value and providing your implementation as an argument to the method, you can define a custom equality comparison for the array or collection. + + + ## Examples -The default equality comparer, `EqualityComparer.Default.Equals`, considers two `NaN` values to be equal. However, in some cases, you may want the comparison of `NaN` values for equality to return `false`, which indicates that the values cannot be compared. The following example defines a `NanComparer` class that implements the interface. It is used by the third example as an argument to the method of the interface that tuples implement. It compares two or two values by using the equality operator. It passes values of any other type to the default equality comparer. - +The default equality comparer, `EqualityComparer.Default.Equals`, considers two `NaN` values to be equal. However, in some cases, you may want the comparison of `NaN` values for equality to return `false`, which indicates that the values cannot be compared. The following example defines a `NanComparer` class that implements the interface. It is used by the third example as an argument to the method of the interface that tuples implement. It compares two or two values by using the equality operator. It passes values of any other type to the default equality comparer. + :::code language="csharp" source="~/snippets/csharp/System.Collections/IStructuralEquatable/Overview/nanexample1.cs" id="Snippet1"::: -:::code language="vb" source="~/snippets/visualbasic/System.Collections/IStructuralEquatable/Overview/nanexample1.vb" id="Snippet1"::: - - The following example creates two identical 3-tuple objects whose components consist of three values. The value of the second component is . The example then calls the method, and it calls the method three times. The first time, it passes the default equality comparer that is returned by the property. The second time, it passes the default equality comparer that is returned by the property. The third time, it passes the custom `NanComparer` object. As the output from the example shows, the first three method calls return `true`, whereas the fourth call returns `false`. - +:::code language="vb" source="~/snippets/visualbasic/System.Collections/IStructuralEquatable/Overview/nanexample1.vb" id="Snippet1"::: + + The following example creates two identical 3-tuple objects whose components consist of three values. The value of the second component is . The example then calls the method, and it calls the method three times. The first time, it passes the default equality comparer that is returned by the property. The second time, it passes the default equality comparer that is returned by the property. The third time, it passes the custom `NanComparer` object. As the output from the example shows, the first three method calls return `true`, whereas the fourth call returns `false`. + :::code language="csharp" source="~/snippets/csharp/System.Collections/IStructuralEquatable/Overview/nanexample1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Collections/IStructuralEquatable/Overview/nanexample1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Collections/IStructuralEquatable/Overview/nanexample1.vb" id="Snippet2"::: + ]]> @@ -137,24 +137,24 @@ The default equality comparer, `EqualityComparer.Default.Equals`, consid if the two objects are equal; otherwise, . - method supports custom structural comparison of array and tuple objects. This method in turn calls the `comparer` object's method to compare individual array elements or tuple components, starting with the first element or component. The individual calls to end and the method returns a value either when a method call returns `false` or after all array elements or tuple components have been compared. - - - -## Examples - The default equality comparer, `EqualityComparer.Default.Equals`, considers two `NaN` values to be equal. However, in some cases, you may want the comparison of `NaN` values for equality to return `false`, which indicates that the values cannot be compared. The following example defines a `NanComparer` class that implements the interface. It compares two or two values by using the equality operator. It passes values of any other type to the default equality comparer. - + method supports custom structural comparison of array and tuple objects. This method in turn calls the `comparer` object's method to compare individual array elements or tuple components, starting with the first element or component. The individual calls to end and the method returns a value either when a method call returns `false` or after all array elements or tuple components have been compared. + + + +## Examples + The default equality comparer, `EqualityComparer.Default.Equals`, considers two `NaN` values to be equal. However, in some cases, you may want the comparison of `NaN` values for equality to return `false`, which indicates that the values cannot be compared. The following example defines a `NanComparer` class that implements the interface. It compares two or two values by using the equality operator. It passes values of any other type to the default equality comparer. + :::code language="csharp" source="~/snippets/csharp/System.Collections/IStructuralEquatable/Overview/nanexample1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Collections/IStructuralEquatable/Overview/nanexample1.vb" id="Snippet1"::: - - The following example creates two identical 3-tuple objects whose components consist of three values. The value of the second component is . The example then calls the method, and it calls the method three times. The first time, it passes the default equality comparer that is returned by the property. The second time, it passes the default equality comparer that is returned by the property. The third time, it passes the custom `NanComparer` object. As the output from the example shows, the first three method calls return `true`, whereas the fourth call returns `false`. - + :::code language="vb" source="~/snippets/visualbasic/System.Collections/IStructuralEquatable/Overview/nanexample1.vb" id="Snippet1"::: + + The following example creates two identical 3-tuple objects whose components consist of three values. The value of the second component is . The example then calls the method, and it calls the method three times. The first time, it passes the default equality comparer that is returned by the property. The second time, it passes the default equality comparer that is returned by the property. The third time, it passes the custom `NanComparer` object. As the output from the example shows, the first three method calls return `true`, whereas the fourth call returns `false`. + :::code language="csharp" source="~/snippets/csharp/System.Collections/IStructuralEquatable/Overview/nanexample1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Collections/IStructuralEquatable/Overview/nanexample1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Collections/IStructuralEquatable/Overview/nanexample1.vb" id="Snippet2"::: + ]]> @@ -206,11 +206,11 @@ The default equality comparer, `EqualityComparer.Default.Equals`, consid Returns a hash code for the current instance. The hash code for the current instance. - method. - + method. + ]]> diff --git a/xml/System.Collections/Queue.xml b/xml/System.Collections/Queue.xml index 498766f517a..f588cab8c18 100644 --- a/xml/System.Collections/Queue.xml +++ b/xml/System.Collections/Queue.xml @@ -750,7 +750,7 @@ This method uses the collection's objects' and method, but does not modify the . - `null` can be added to the as a value. To distinguish between a null value and the end of the , check the property or catch the , which is thrown when the is empty. + `null` can be added to the as a value. To distinguish between a null value and the end of the , check the property or catch the , which is thrown when the is empty. This method is an `O(1)` operation. @@ -1029,7 +1029,7 @@ This method uses the collection's objects' and method, but does not modify the . - `null` can be added to the as a value. To distinguish between a null value and the end of the , check the property or catch the , which is thrown when the is empty. + `null` can be added to the as a value. To distinguish between a null value and the end of the , check the property or catch the , which is thrown when the is empty. This method is an `O(1)` operation. @@ -1172,7 +1172,7 @@ This method uses the collection's objects' and , use the method. However, derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + To create a synchronized version of the , use the method. However, derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Collections/ReadOnlyCollectionBase.xml b/xml/System.Collections/ReadOnlyCollectionBase.xml index f8209e9e311..6c637011be3 100644 --- a/xml/System.Collections/ReadOnlyCollectionBase.xml +++ b/xml/System.Collections/ReadOnlyCollectionBase.xml @@ -82,7 +82,7 @@ A instance is always read-only. ## Examples The following code example implements the class. - + :::code language="csharp" source="~/snippets/csharp/System.Collections/ReadOnlyCollectionBase/Overview/readonlycollectionbase.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/ReadOnlyCollectionBase/Overview/readonlycollectionbase.vb" id="Snippet1"::: @@ -475,14 +475,14 @@ A instance is always read-only. object is not synchronized. Derived classes can provide a synchronized version of the class using the property. + A object is not synchronized. Derived classes can provide a synchronized version of the class using the property. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. ## Examples - The following code example shows how to lock the collection using the property during the entire enumeration. + The following code example shows how to lock the collection using the property during the entire enumeration. :::code language="csharp" source="~/snippets/csharp/System.Collections/ReadOnlyCollectionBase/Overview/source2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/ReadOnlyCollectionBase/Overview/source2.vb" id="Snippet2"::: @@ -542,14 +542,14 @@ A instance is always read-only. class using the property. The synchronizing code must perform operations on the property of the object, not directly on the object. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide their own synchronized version of the class using the property. The synchronizing code must perform operations on the property of the object, not directly on the object. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. ## Examples - The following code example shows how to lock the collection using the property during the entire enumeration. + The following code example shows how to lock the collection using the property during the entire enumeration. :::code language="csharp" source="~/snippets/csharp/System.Collections/ReadOnlyCollectionBase/Overview/source2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/ReadOnlyCollectionBase/Overview/source2.vb" id="Snippet2"::: diff --git a/xml/System.Collections/SortedList.xml b/xml/System.Collections/SortedList.xml index 64465a6c62f..d7f2eafb98f 100644 --- a/xml/System.Collections/SortedList.xml +++ b/xml/System.Collections/SortedList.xml @@ -101,7 +101,7 @@ A element can be accessed by its key, like A object internally maintains two arrays to store the elements of the list; that is, one array for the keys and another array for the associated values. Each element is a key/value pair that can be accessed as a object. A key cannot be `null`, but a value can be. - The capacity of a object is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required through reallocation. The capacity can be decreased by calling or by setting the property explicitly. + The capacity of a object is the number of elements the can hold. As elements are added to a , the capacity is automatically increased as required through reallocation. The capacity can be decreased by calling or by setting the property explicitly. **.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. @@ -672,7 +672,7 @@ A element can be accessed by its key, like If already equals , the capacity of the object is increased by automatically reallocating the internal array, and the existing elements are copied to the new array before the new element is added. - You can also use the property to add new elements by setting the value of a key that does not exist in the object (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the object (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. The elements of a object are sorted by the keys either according to a specific implementation specified when the is created or according to the implementation provided by the keys themselves. @@ -759,7 +759,7 @@ A element can be accessed by its key, like is always greater than or equal to . If exceeds while adding elements, the capacity is automatically increased by reallocating the internal array before copying the old elements and adding the new elements. - The capacity can be decreased by calling or by setting the property explicitly. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity. + The capacity can be decreased by calling or by setting the property explicitly. When the value of is set explicitly, the internal array is also reallocated to accommodate the specified capacity. 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. @@ -820,7 +820,7 @@ A element can be accessed by its key, like ## Remarks is set to zero and references to other objects from elements of the collection are also released. - remains unchanged. To reset the capacity of the object, call or set the property directly. Trimming an empty sets the capacity of the to the default capacity. + remains unchanged. To reset the capacity of the object, call or set the property directly. Trimming an empty sets the capacity of the to the default capacity. This method is an `O(n)` operation, where `n` is . @@ -1532,7 +1532,7 @@ This method uses the collection's objects' and are sorted in the same order as the keys of the . - This method is similar to the property, but returns an object instead of an object. + This method is similar to the property, but returns an object instead of an object. This method is an `O(1)` operation. @@ -1601,7 +1601,7 @@ This method uses the collection's objects' and are sorted in the same order as the values of the . - This method is similar to the property, but returns an object instead of an object. + This method is similar to the property, but returns an object instead of an object. This method is an `O(1)` operation. @@ -1938,7 +1938,7 @@ This method uses the collection's objects' and property during the entire enumeration. + The following code example shows how to lock a collection using the property during the entire enumeration. :::code language="csharp" source="~/snippets/csharp/System.Collections/SortedList/IsSynchronized/source2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/SortedList/IsSynchronized/source2.vb" id="Snippet2"::: @@ -2015,15 +2015,15 @@ This method uses the collection's objects' and property to access a specific element in a collection by specifying the following syntax: `myCollection[key]`. + You can use the property to access a specific element in a collection by specifying the following syntax: `myCollection[key]`. - You can also use this property to add new elements by setting the value of a key that does not exist in the object (for example, `myCollection["myNonexistentKey"] = myValue)`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use this property to add new elements by setting the value of a key that does not exist in the object (for example, `myCollection["myNonexistentKey"] = myValue)`. However, if the specified key already exists in the , setting the property overwrites the old value. In contrast, the method does not modify existing elements. A key cannot be `null`, but a value can be. To distinguish between `null` that is returned because the specified key is not found and `null` that is returned because the value of the specified key is `null`, use the method or the method to determine if the key exists in the list. The elements of a are sorted by the keys either according to a specific implementation specified when the is created or according to the implementation provided by the keys themselves. - 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. + 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. Retrieving the value of this property is an `O(log n)` operation, where `n` is . Setting the property is an `O(log n)` operation if the key is already in the . If the key is not in the list, setting the property is an `O(n)` operation for unsorted data, or `O(log n)` if the new element is added at the end of the list. If insertion causes a resize, the operation is `O(n)`. @@ -2387,7 +2387,7 @@ This method uses the collection's objects' and property during the entire enumeration. + The following code example shows how to lock the collection using the property during the entire enumeration. :::code language="csharp" source="~/snippets/csharp/System.Collections/SortedList/IsSynchronized/source2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/SortedList/IsSynchronized/source2.vb" id="Snippet2"::: @@ -2455,14 +2455,14 @@ This method uses the collection's objects' and object, use the method. However, derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + To create a synchronized version of the object, use the method. However, derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. ## Examples - The following code example shows how to lock the collection using the property during the entire enumeration. + The following code example shows how to lock the collection using the property during the entire enumeration. :::code language="csharp" source="~/snippets/csharp/System.Collections/SortedList/IsSynchronized/source2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/SortedList/IsSynchronized/source2.vb" id="Snippet2"::: diff --git a/xml/System.Collections/Stack.xml b/xml/System.Collections/Stack.xml index ab3bf4ae9bc..f7de981b4b7 100644 --- a/xml/System.Collections/Stack.xml +++ b/xml/System.Collections/Stack.xml @@ -809,7 +809,7 @@ This method tests for equality by passing the `obj` argument to the method, but does not modify the . - `null` can be pushed onto the as a placeholder, if needed. To distinguish between a null value and the end of the stack, check the property or catch the , which is thrown when the is empty. + `null` can be pushed onto the as a placeholder, if needed. To distinguish between a null value and the end of the stack, check the property or catch the , which is thrown when the is empty. This method is an `O(1)` operation. @@ -877,7 +877,7 @@ This method tests for equality by passing the `obj` argument to the method, but does not modify the . - `null` can be pushed onto the as a placeholder, if needed. To distinguish between a null value and the end of the stack, check the property or catch the , which is thrown when the is empty. + `null` can be pushed onto the as a placeholder, if needed. To distinguish between a null value and the end of the stack, check the property or catch the , which is thrown when the is empty. This method is an `O(1)` operation. @@ -1087,7 +1087,7 @@ This method tests for equality by passing the `obj` argument to the , use the method. However, derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + To create a synchronized version of the , use the method. However, derived classes can provide their own synchronized version of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.ComponentModel.Composition.Hosting/CompositionContainer.xml b/xml/System.ComponentModel.Composition.Hosting/CompositionContainer.xml index 2b6553806ee..a84e85a93e1 100644 --- a/xml/System.ComponentModel.Composition.Hosting/CompositionContainer.xml +++ b/xml/System.ComponentModel.Composition.Hosting/CompositionContainer.xml @@ -38,35 +38,35 @@ Manages the composition of parts. - object serves two major purposes in an application. First, it keeps track of which parts are available for composition and what their dependencies are, and performs composition whenever the set of available parts changes. Second, it provides the methods by which the application gets instances of composed parts or fills the dependencies of a composable part. - + object serves two major purposes in an application. First, it keeps track of which parts are available for composition and what their dependencies are, and performs composition whenever the set of available parts changes. Second, it provides the methods by which the application gets instances of composed parts or fills the dependencies of a composable part. + > [!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. - - Parts can be made available to the container either directly or through the property. All the parts discoverable in this are available to the container to fulfill imports, along with any parts added directly. - - The method allows instantiated parts to be added to an existing container. Assuming composition is successful, these parts will have their imports filled with parts retrieved from the container, and their exports will be available to other parts. Imports marked as recomposable will be registered for recomposition. - - The method allows a part to have its imports filled without being added to the container. If the composition is successful, the part's imports will be filled, but the part's exports will not be available to other parts and no imports will be registered for recomposition. - - objects should always be disposed. When the method is called, the object also disposes all the parts that it has created. - - A object that can be accessed from multiple threads must be constructed with the `isThreadSafe` parameter set to `true`, using the constructor. Performance will be slightly slower when `isThreadSafe` is `true`, so we recommend that you set this parameter to `false` in single-threaded scenarios. The default is `false`. - +> 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. + + Parts can be made available to the container either directly or through the property. All the parts discoverable in this are available to the container to fulfill imports, along with any parts added directly. + + The method allows instantiated parts to be added to an existing container. Assuming composition is successful, these parts will have their imports filled with parts retrieved from the container, and their exports will be available to other parts. Imports marked as recomposable will be registered for recomposition. + + The method allows a part to have its imports filled without being added to the container. If the composition is successful, the part's imports will be filled, but the part's exports will not be available to other parts and no imports will be registered for recomposition. + + objects should always be disposed. When the method is called, the object also disposes all the parts that it has created. + + A object that can be accessed from multiple threads must be constructed with the `isThreadSafe` parameter set to `true`, using the constructor. Performance will be slightly slower when `isThreadSafe` is `true`, so we recommend that you set this parameter to `false` in single-threaded scenarios. The default is `false`. + > [!WARNING] -> A should never import itself, or a part that has a reference to it. Such a reference could allow an untrusted part to gain access all the parts in the container. - - - -## Examples - In the following example, a object is initialized with a catalog and is used to fill the imports of a part. This example uses the Attributed Programming Model. - +> A should never import itself, or a part that has a reference to it. Such a reference could allow an untrusted part to gain access all the parts in the container. + + + +## Examples + In the following example, a object is initialized with a catalog and is used to fill the imports of a part. This example uses the Attributed Programming Model. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Composition.Hosting/CompositionContainer/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/composition.compositioncontainer/vb/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/composition.compositioncontainer/vb/module1.vb" id="Snippet1"::: + ]]> Attributed Programming Model Overview @@ -261,11 +261,11 @@ An array of objects that provide the access to objects, or to set the property to an empty . Initializes a new instance of the class with the specified catalog, thread-safe mode, and export providers. - object that can be accessed from multiple threads must set the `isThreadSafe` parameter to `true`. Performance will be slightly slower when `isThreadSafe` is `true`, so we recommend that you set this parameter to `false` in single-threaded scenarios. The default is `false`. - + object that can be accessed from multiple threads must set the `isThreadSafe` parameter to `true`. Performance will be slightly slower when `isThreadSafe` is `true`, so we recommend that you set this parameter to `false` in single-threaded scenarios. The default is `false`. + ]]> One or more elements of are . @@ -364,21 +364,21 @@ Changes to the to include during the composition. Adds or removes the parts in the specified from the container and executes composition. - will always maintain a stable, composed state. Therefore, calling with an empty is never necessary to start composition. Instead, call the method whenever you need to make changes to the parts available to the . - - The can contain both parts to be added and parts to be removed. Recomposition will take place only once for each call to . - - - -## Examples - In this simple example, three parts are created and added to the , and one part is retrieved to show that all imports have been filled. This example uses the Attributed Programming Model. - + will always maintain a stable, composed state. Therefore, calling with an empty is never necessary to start composition. Instead, call the method whenever you need to make changes to the parts available to the . + + The can contain both parts to be added and parts to be removed. Recomposition will take place only once for each call to . + + + +## Examples + In this simple example, three parts are created and added to the , and one part is retrieved to show that all imports have been filled. This example uses the Attributed Programming Model. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Composition.Hosting/CompositionContainer/Compose/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/composition.compositioncontainer.compose/vb/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/composition.compositioncontainer.compose/vb/module1.vb" id="Snippet1"::: + ]]> Attributed Programming Model Overview @@ -417,16 +417,16 @@ Releases all resources used by the current instance of the class. - . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - - For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + + For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + > [!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. - +> 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. + ]]> @@ -497,11 +497,11 @@ Returns a collection of all exports that match the conditions in the specified object. A collection of all the objects in this object that match the conditions specified by . - method should return an empty collection of objects. - + method should return an empty collection of objects. + ]]> @@ -552,13 +552,13 @@ The that needs to be released. Releases the specified object from the . - that produced the instance. As a rule, non-shared exports should be detached from the container. - - For example, the will only release an if it comes from a that was constructed under a context. Release in this context means walking the dependency chain of the objects, detaching references from the container and calling `Dispose` on the objects as needed. If the was constructed under a context the will do nothing, as the specified may being used by other requestors. Those will only be detached when the container is itself disposed. - + that produced the instance. As a rule, non-shared exports should be detached from the container. + + For example, the will only release an if it comes from a that was constructed under a context. Release in this context means walking the dependency chain of the objects, detaching references from the container and calling `Dispose` on the objects as needed. If the was constructed under a context the will do nothing, as the specified may being used by other requestors. Those will only be detached when the container is itself disposed. + ]]> @@ -626,11 +626,11 @@ A collection of objects to be released. Releases a set of objects from the . - was constructed. For more information, see the method. - + was constructed. For more information, see the method. + ]]> diff --git a/xml/System.ComponentModel.Composition.Hosting/ExportProvider.xml b/xml/System.ComponentModel.Composition.Hosting/ExportProvider.xml index 0a816a45e1f..a24a6d20a1e 100644 --- a/xml/System.ComponentModel.Composition.Hosting/ExportProvider.xml +++ b/xml/System.ComponentModel.Composition.Hosting/ExportProvider.xml @@ -163,19 +163,19 @@ Returns the export with the contract name derived from the specified type parameter. If there is not exactly one matching export, an exception is thrown. The export with the contract name derived from the specified type parameter. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> - There are zero objects with the contract name derived from in the object. - - -or- - + There are zero objects with the contract name derived from in the object. + + -or- + There is more than one object with the contract name derived from in the object. The object has been disposed of. @@ -221,19 +221,19 @@ Returns the export with the specified contract name. If there is not exactly one matching export, an exception is thrown. The export with the specified contract name. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> - There are zero objects with the contract name derived from in the object. - - -or- - + There are zero objects with the contract name derived from in the object. + + -or- + There is more than one object with the contract name derived from in the object. The object has been disposed of. @@ -278,19 +278,19 @@ Returns the export with the contract name derived from the specified type parameter. If there is not exactly one matching export, an exception is thrown. System.Lazy`2 - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> - There are zero objects with the contract name derived from in the object. - - -or- - + There are zero objects with the contract name derived from in the object. + + -or- + There is more than one object with the contract name derived from in the object. The object has been disposed of. @@ -340,19 +340,19 @@ Returns the export with the specified contract name. If there is not exactly one matching export, an exception is thrown. The export with the specified contract name. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> - There are zero objects with the contract name derived from in the object. - - -or- - + There are zero objects with the contract name derived from in the object. + + -or- + There is more than one object with the contract name derived from in the object. The object has been disposed of. @@ -401,19 +401,19 @@ Returns the exported object with the contract name derived from the specified type parameter. If there is not exactly one matching exported object, an exception is thrown. The exported object with the contract name derived from the specified type parameter. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> - There are zero exported objects with the contract name derived from in the . - - -or- - + There are zero exported objects with the contract name derived from in the . + + -or- + There is more than one exported object with the contract name derived from in the . The object has been disposed of. The underlying exported object cannot be cast to . @@ -455,19 +455,19 @@ Returns the exported object with the specified contract name. If there is not exactly one matching exported object, an exception is thrown. The exported object with the specified contract name. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> - There are zero exported objects with the contract name derived from in the . - - -or- - + There are zero exported objects with the contract name derived from in the . + + -or- + There is more than one exported object with the contract name derived from in the . The object has been disposed of. The underlying exported object cannot be cast to . @@ -516,15 +516,15 @@ Gets the exported object with the contract name derived from the specified type parameter or the default value for the specified type, or throws an exception if there is more than one matching exported object. The exported object with the contract name derived from , if found; otherwise, the default value for . - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> There is more than one exported object with the contract name derived from in the . @@ -568,15 +568,15 @@ Gets the exported object with the specified contract name or the default value for the specified type, or throws an exception if there is more than one matching exported object. The exported object with the specified contract name, if found; otherwise, the default value for . - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> There is more than one exported object with the specified contract name in the . @@ -633,13 +633,13 @@ Gets all the exported objects with the contract name derived from the specified type parameter. The exported objects with the contract name derived from the specified type parameter, if found; otherwise, an empty object. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> The object has been disposed of. @@ -688,13 +688,13 @@ Gets all the exported objects with the specified contract name. The exported objects with the specified contract name, if found; otherwise, an empty object. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> The object has been disposed of. @@ -743,10 +743,10 @@ A collection of all the objects matching the condition specified by . To be added. - is and there are zero objects that match the conditions of the specified . - - -or- - + is and there are zero objects that match the conditions of the specified . + + -or- + is or and there is more than one object that matches the conditions of the specified . is . @@ -787,16 +787,16 @@ A collection of all the objects matching the condition specified by and . To be added. - is and there are zero objects that match the conditions of the specified . - - -or- - + is and there are zero objects that match the conditions of the specified . + + -or- + is or and there is more than one object that matches the conditions of the specified . - is . - - -or- - + is . + + -or- + is . @@ -843,13 +843,13 @@ Gets all the exports with the specified contract name. A collection of all the objects for the contract matching . - method on `type`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `type`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> The object has been disposed of. @@ -897,13 +897,13 @@ Gets all the exports with the contract name derived from the specified type parameter. The objects with the contract name derived from , if found; otherwise, an empty object. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> The object has been disposed of. @@ -950,13 +950,13 @@ Gets all the exports with the specified contract name. The objects with the specified contract name, if found; otherwise, an empty object. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> The object has been disposed of. @@ -1001,13 +1001,13 @@ Gets all the exports with the contract name derived from the specified type parameter. The objects with the contract name derived from , if found; otherwise, an empty object. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> The object has been disposed of. @@ -1058,13 +1058,13 @@ Gets all the exports with the specified contract name. The objects with the specified contract name if found; otherwise, an empty object. - method on `T`. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `T`. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> The object has been disposed of. @@ -1112,11 +1112,11 @@ Gets all the exports that match the constraint defined by the specified definition. A collection that contains all the exports that match the specified condition. - is and there are zero objects that match the conditions of the specified , an empty collection should be returned. - + is and there are zero objects that match the conditions of the specified , an empty collection should be returned. + ]]> diff --git a/xml/System.ComponentModel.Composition.Primitives/Export.xml b/xml/System.ComponentModel.Composition.Primitives/Export.xml index e3f31fd8504..c58731bfbf3 100644 --- a/xml/System.ComponentModel.Composition.Primitives/Export.xml +++ b/xml/System.ComponentModel.Composition.Primitives/Export.xml @@ -62,7 +62,7 @@ property and the method. + Derived types that call this constructor must override the property and the method. ]]> @@ -289,7 +289,7 @@ Overrides of this method should never return `null`. of the property. + This property returns the value of of the property. ]]> diff --git a/xml/System.ComponentModel.Composition.Primitives/ExportDefinition.xml b/xml/System.ComponentModel.Composition.Primitives/ExportDefinition.xml index 35ea58c4053..43f5ce810e8 100644 --- a/xml/System.ComponentModel.Composition.Primitives/ExportDefinition.xml +++ b/xml/System.ComponentModel.Composition.Primitives/ExportDefinition.xml @@ -59,11 +59,11 @@ Initializes a new instance of the class. - property and optionally, the property. By default, returns an empty, read-only dictionary. - + property and optionally, the property. By default, returns an empty, read-only dictionary. + ]]> @@ -124,11 +124,11 @@ Gets the contract name. The contract name of the object. - The property was not overridden by a derived class. @@ -165,13 +165,13 @@ Gets the contract metadata. The metadata of the . The default is an empty, read-only object. - object with a case-sensitive, non-linguistic comparer, such as , and should never return `null`. - - If the does not contain metadata, return an empty instead. - + object with a case-sensitive, non-linguistic comparer, such as , and should never return `null`. + + If the does not contain metadata, return an empty instead. + ]]> diff --git a/xml/System.ComponentModel.Composition.Primitives/ImportDefinition.xml b/xml/System.ComponentModel.Composition.Primitives/ImportDefinition.xml index 051f04a5084..d192679fb4c 100644 --- a/xml/System.ComponentModel.Composition.Primitives/ImportDefinition.xml +++ b/xml/System.ComponentModel.Composition.Primitives/ImportDefinition.xml @@ -62,7 +62,7 @@ property, and optionally, the , and properties. + Derived types that call this constructor must override the property, and optionally, the , and properties. ]]> diff --git a/xml/System.ComponentModel.Composition/ChangeRejectedException.xml b/xml/System.ComponentModel.Composition/ChangeRejectedException.xml index a3471f4c536..46ce844f4fa 100644 --- a/xml/System.ComponentModel.Composition/ChangeRejectedException.xml +++ b/xml/System.ComponentModel.Composition/ChangeRejectedException.xml @@ -70,18 +70,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -144,16 +144,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -182,18 +182,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 to 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| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + property. The property returns the same value that is passed to 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| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions diff --git a/xml/System.ComponentModel.Composition/CompositionContractMismatchException.xml b/xml/System.ComponentModel.Composition/CompositionContractMismatchException.xml index 167c1edc7a4..ac53416cd5d 100644 --- a/xml/System.ComponentModel.Composition/CompositionContractMismatchException.xml +++ b/xml/System.ComponentModel.Composition/CompositionContractMismatchException.xml @@ -70,18 +70,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply". This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply". This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -114,16 +114,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -169,11 +169,11 @@ The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and Soap Serialization @@ -214,18 +214,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 the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + 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| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions diff --git a/xml/System.ComponentModel.Composition/CreationPolicy.xml b/xml/System.ComponentModel.Composition/CreationPolicy.xml index dd30f5deb07..5a7c25dd54b 100644 --- a/xml/System.ComponentModel.Composition/CreationPolicy.xml +++ b/xml/System.ComponentModel.Composition/CreationPolicy.xml @@ -24,19 +24,19 @@ Specifies when and how a part will be instantiated. - needs instances of the objects described by exports in order to fill imports. If a one export is used to fill multiple imports, there are two possible behaviors. Either a single instance of the exported object is created, and a reference to the same object is given to every importer, or a separate instance of the exported object is created for each importer. - - Which behavior occurs depends on the property of the attached to the export and the of the . Both of which will contain a value from the enumeration. If the policies are incompatible, that export will not be considered a match for the given import. The following table summarizes the interaction of these two properties. - -||Export's specifies Any or none specified.|Export's specifies Shared|Export's specifies NonShared| -|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -|Any|A single, shared instance of the exported object will be created.|A single, shared instance of the exported object will be created.|A new instance of the exported object will be created for each importer.| -|Shared|A single, shared instance of the exported object will be created.|A single, shared instance of the exported object will be created.|The export will not be considered a match for the import.| -|NonShared|A new instance of the exported object will be created for each importer.|The export will not be considered a match for the import.|A new instance of the exported object will be created for each importer.| - + needs instances of the objects described by exports in order to fill imports. If a one export is used to fill multiple imports, there are two possible behaviors. Either a single instance of the exported object is created, and a reference to the same object is given to every importer, or a separate instance of the exported object is created for each importer. + + Which behavior occurs depends on the property of the attached to the export and the of the . Both of which will contain a value from the enumeration. If the policies are incompatible, that export will not be considered a match for the given import. The following table summarizes the interaction of these two properties. + +||Export's specifies Any or none specified.|Export's specifies Shared|Export's specifies NonShared| +|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +|Any|A single, shared instance of the exported object will be created.|A single, shared instance of the exported object will be created.|A new instance of the exported object will be created for each importer.| +|Shared|A single, shared instance of the exported object will be created.|A single, shared instance of the exported object will be created.|The export will not be considered a match for the import.| +|NonShared|A new instance of the exported object will be created for each importer.|The export will not be considered a match for the import.|A new instance of the exported object will be created for each importer.| + ]]> diff --git a/xml/System.ComponentModel.Composition/ExportAttribute.xml b/xml/System.ComponentModel.Composition/ExportAttribute.xml index a57cc19b940..a8043b108f7 100644 --- a/xml/System.ComponentModel.Composition/ExportAttribute.xml +++ b/xml/System.ComponentModel.Composition/ExportAttribute.xml @@ -35,23 +35,23 @@ Specifies that a type, property, field, or method provides a particular export. - declares that a part exports, or provides to the composition container, an object that fulfills a particular contract. During composition, parts with imports that have matching contracts will have those dependencies filled by the exported object. - - The can decorate either an entire class, or a property, field, or method of a class. If the entire class is decorated, an instance of the class is the exported object. If a member of a class is decorated, the exported object will be the value of the decorated member. - - Whether or not a contract matches is determined primarily by the contract name and the contract type. For more information, see . - - - -## Examples - The following example shows three classes decorated with the , and three imports that match them. - + declares that a part exports, or provides to the composition container, an object that fulfills a particular contract. During composition, parts with imports that have matching contracts will have those dependencies filled by the exported object. + + The can decorate either an entire class, or a property, field, or method of a class. If the entire class is decorated, an instance of the class is the exported object. If a member of a class is decorated, the exported object will be the value of the decorated member. + + Whether or not a contract matches is determined primarily by the contract name and the contract type. For more information, see . + + + +## Examples + The following example shows three classes decorated with the , and three imports that match them. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Composition/ExportAttribute/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/importandexport/vb/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/importandexport/vb/module1.vb" id="Snippet1"::: + ]]> @@ -90,15 +90,15 @@ Initializes a new instance of the class, exporting the type or member marked with this attribute under the default contract name. - method on the property or field type, or on the type that is marked with this attribute. - - Methods marked with this attribute must specify a contract name or a type by using either or . - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on the property or field type, or on the type that is marked with this attribute. + + Methods marked with this attribute must specify a contract name or a type by using either or . + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> @@ -130,15 +130,15 @@ The contract name that is used to export the type or member marked with this attribute, or or an empty string ("") to use the default contract name. Initializes a new instance of the class, exporting the type or member marked with this attribute under the specified contract name. - method on the property or field type, or on the type that this is marked with this attribute. - - Methods marked with this attribute must specify a contract name or a type by using either or . - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on the property or field type, or on the type that this is marked with this attribute. + + Methods marked with this attribute must specify a contract name or a type by using either or . + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> @@ -170,17 +170,17 @@ A type from which to derive the contract name that is used to export the type or member marked with this attribute, or to use the default contract name. Initializes a new instance of the class, exporting the type or member marked with this attribute under a contract name derived from the specified type. - method on `contractType`. - - The default contract name is the result of calling the method on the property or field type, or on the type that is marked with this attribute. - - Methods marked with this attribute must specify a contract name or a type by using either or . - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `contractType`. + + The default contract name is the result of calling the method on the property or field type, or on the type that is marked with this attribute. + + Methods marked with this attribute must specify a contract name or a type by using either or . + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> @@ -210,10 +210,10 @@ on the property or field type, or on the type itself that this is marked with this attribute. - +The default contract name is the result of calling on the property or field type, or on the type itself that this is marked with this attribute. + The contract name is compared using a case-sensitive, non-linguistic comparison using . - + ]]> diff --git a/xml/System.ComponentModel.Composition/ExportFactory`1.xml b/xml/System.ComponentModel.Composition/ExportFactory`1.xml index a3c2bfa85b1..ec03baf3218 100644 --- a/xml/System.ComponentModel.Composition/ExportFactory`1.xml +++ b/xml/System.ComponentModel.Composition/ExportFactory`1.xml @@ -42,31 +42,31 @@ The type of the export. A factory that creates new instances of a part that provides the specified export. - object, the property always returns a reference to the same object. In some circumstances, you might want each reference to result in the creation of a new object. is designed for those scenarios. - - can be used in a similar fashion to when creating attributed parts. That is, an import contract that is defined on with a generic parameter of `T` will match an export that is defined on `T`. For example, the follow export and import match: - -```csharp -[Export] -public String myData = "Example Data."; - -[Import] -public ExportFactory theData { get; set; } -``` - -```vb - -Public myData As String = "Example Data." - - -Public Property theData As ExportFactory(Of String) -``` - - The method returns an object, which has two pieces. The property provides access to the created part. Calling the method of the object cleans up the created part and all of its dependencies, thereby allowing the part's lifetime to be managed without reference to the container that created it. - + object, the property always returns a reference to the same object. In some circumstances, you might want each reference to result in the creation of a new object. is designed for those scenarios. + + can be used in a similar fashion to when creating attributed parts. That is, an import contract that is defined on with a generic parameter of `T` will match an export that is defined on `T`. For example, the follow export and import match: + +```csharp +[Export] +public String myData = "Example Data."; + +[Import] +public ExportFactory theData { get; set; } +``` + +```vb + +Public myData As String = "Example Data." + + +Public Property theData As ExportFactory(Of String) +``` + + The method returns an object, which has two pieces. The property provides access to the created part. Calling the method of the object cleans up the created part and all of its dependencies, thereby allowing the part's lifetime to be managed without reference to the container that created it. + ]]> diff --git a/xml/System.ComponentModel.Composition/ImportAttribute.xml b/xml/System.ComponentModel.Composition/ImportAttribute.xml index 9044c7a0496..5e09c5ee75f 100644 --- a/xml/System.ComponentModel.Composition/ImportAttribute.xml +++ b/xml/System.ComponentModel.Composition/ImportAttribute.xml @@ -35,21 +35,21 @@ Specifies that a property, field, or parameter value should be provided by the .object. - is used to declare the imports, or dependencies, of a given part. It can decorate a property, a field, or a method. During composition, a part's imports will be filled by the object to which that part belongs, by using the exports provided to that object. - - Whether an import matches a given export is determined primarily by comparing the contract name and the contract type. Ordinarily, you do not have to specify either of these when using the import attribute in code, and they will be automatically inferred from the type of the decorated member. If the import must match an export of a different type (for example, a subclass of the type of the decorated member, or an interface implemented by that member), then the contract type must be explicitly specified. The contract name can also be explicitly specified, for example to distinguish between multiple contracts with the same type, but it is usually better to do this through metadata. For more information about metadata, see . - - - -## Examples - The following example shows three classes with members decorated with the , and three exports that match them. - + is used to declare the imports, or dependencies, of a given part. It can decorate a property, a field, or a method. During composition, a part's imports will be filled by the object to which that part belongs, by using the exports provided to that object. + + Whether an import matches a given export is determined primarily by comparing the contract name and the contract type. Ordinarily, you do not have to specify either of these when using the import attribute in code, and they will be automatically inferred from the type of the decorated member. If the import must match an export of a different type (for example, a subclass of the type of the decorated member, or an interface implemented by that member), then the contract type must be explicitly specified. The contract name can also be explicitly specified, for example to distinguish between multiple contracts with the same type, but it is usually better to do this through metadata. For more information about metadata, see . + + + +## Examples + The following example shows three classes with members decorated with the , and three exports that match them. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Composition/ExportAttribute/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/importandexport/vb/module1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/importandexport/vb/module1.vb" id="Snippet1"::: + ]]> @@ -88,13 +88,13 @@ Initializes a new instance of the class, importing the export with the default contract name. - method on the property, field, or parameter type that this is marked with this attribute. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on the property, field, or parameter type that this is marked with this attribute. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> @@ -126,13 +126,13 @@ The contract name of the export to import, or or an empty string ("") to use the default contract name. Initializes a new instance of the class, importing the export with the specified contract name. - method on the property, field, or parameter type that is marked with this attribute. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on the property, field, or parameter type that is marked with this attribute. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> @@ -164,15 +164,15 @@ The type to derive the contract name of the export from, or to use the default contract name. Initializes a new instance of the class, importing the export with the contract name derived from the specified type. - method on `contractType`. - - The default contract name is the result of calling the method on the property, field, or parameter type that is marked with this attribute. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `contractType`. + + The default contract name is the result of calling the method on the property, field, or parameter type that is marked with this attribute. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> @@ -233,11 +233,11 @@ if the property, field, or parameter will be set to its type's default value when there is no export with the in the ; otherwise, . The default is . - @@ -361,12 +361,12 @@ Gets or sets a value that indicates that the importer requires a specific for the exports used to satisfy this import. - One of the following values: - - , if the importer does not require a specific . This is the default. - - to require that all used exports be shared by all parts in the container. - + One of the following values: + + , if the importer does not require a specific . This is the default. + + to require that all used exports be shared by all parts in the container. + to require that all used exports be non-shared in a container. In this case, each part receives their own instance. To be added. diff --git a/xml/System.ComponentModel.Composition/ImportCardinalityMismatchException.xml b/xml/System.ComponentModel.Composition/ImportCardinalityMismatchException.xml index 97ea7dcded4..fb3893a1f4f 100644 --- a/xml/System.ComponentModel.Composition/ImportCardinalityMismatchException.xml +++ b/xml/System.ComponentModel.Composition/ImportCardinalityMismatchException.xml @@ -78,18 +78,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply". This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply". This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -122,16 +122,16 @@ A message that describes the , or to set the property to its default value. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -177,11 +177,11 @@ An object that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -222,18 +222,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 the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + 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| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions diff --git a/xml/System.ComponentModel.Composition/ImportManyAttribute.xml b/xml/System.ComponentModel.Composition/ImportManyAttribute.xml index 5ce5363998e..d3e864b9b8b 100644 --- a/xml/System.ComponentModel.Composition/ImportManyAttribute.xml +++ b/xml/System.ComponentModel.Composition/ImportManyAttribute.xml @@ -69,13 +69,13 @@ Initializes a new instance of the class, importing the set of exports with the default contract name. - method on the type of the property, field, or parameter that is marked with this attribute. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on the type of the property, field, or parameter that is marked with this attribute. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> @@ -107,13 +107,13 @@ The contract name of the exports to import, or or an empty string ("") to use the default contract name. Initializes a new instance of the class, importing the set of exports with the specified contract name. - method on the property, field, or parameter type that is marked with this attribute. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on the property, field, or parameter type that is marked with this attribute. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> @@ -145,15 +145,15 @@ The type to derive the contract name of the exports to import, or to use the default contract name. Initializes a new instance of the class, importing the set of exports with the contract name derived from the specified type. - method on `contractType`. - - The default contract name is the result of calling the method on the property, field, or parameter type that is marked with this attribute. - - The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. - + method on `contractType`. + + The default contract name is the result of calling the method on the property, field, or parameter type that is marked with this attribute. + + The contract name is compared by using the property to perform a case-sensitive, non-linguistic comparison. + ]]> @@ -212,8 +212,8 @@ Gets or sets a value indicating whether the decorated property or field will be recomposed when exports that provide the matching contract change. - if the property or field allows for recomposition when exports that provide the same are added or removed from the ; otherwise, . - + if the property or field allows for recomposition when exports that provide the same are added or removed from the ; otherwise, . + The default value is . To be added. @@ -304,12 +304,12 @@ Gets or sets a value that indicates that the importer requires a specific for the exports used to satisfy this import. - One of the following values: - - , if the importer does not require a specific . This is the default. - - to require that all used exports be shared by all parts in the container. - + One of the following values: + + , if the importer does not require a specific . This is the default. + + to require that all used exports be shared by all parts in the container. + to require that all used exports be non-shared in a container. In this case, each part receives their own instance. To be added. diff --git a/xml/System.ComponentModel.DataAnnotations/CustomValidationAttribute.xml b/xml/System.ComponentModel.DataAnnotations/CustomValidationAttribute.xml index b06b614102f..bbaef6c493e 100644 --- a/xml/System.ComponentModel.DataAnnotations/CustomValidationAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/CustomValidationAttribute.xml @@ -46,15 +46,15 @@ Specifies a custom validation method that is used to validate a property or class instance. - attribute is used to perform custom validation when the method is invoked to perform validation. The method then redirects the call to the method that is identified by the property, which in turn performs the actual validation. - - The attribute can be applied to types, properties, fields, methods, and method parameters. When it is applied to a property, the attribute is invoked whenever a value is assigned to that property. When it is applied to a method, the attribute is invoked whenever the program calls that method. When it is applied to a method parameter, the attribute is invoked before the method is called. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - + attribute is used to perform custom validation when the method is invoked to perform validation. The method then redirects the call to the method that is identified by the property, which in turn performs the actual validation. + + The attribute can be applied to types, properties, fields, methods, and method parameters. When it is applied to a property, the attribute is invoked whenever a value is assigned to that property. When it is applied to a method, the attribute is invoked whenever the program calls that method. When it is applied to a method parameter, the attribute is invoked before the method is called. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + ]]> @@ -103,11 +103,11 @@ The method that performs custom validation. Initializes a new instance of the class. - @@ -151,11 +151,11 @@ Formats a validation error message. An instance of the formatted error message. - The current attribute is malformed. @@ -254,17 +254,17 @@ Gets the validation method. The name of the validation method. - input value and a output value. The parameter provides additional context information that the method can use to determine the context that it is used in. The output parameter enables the method to return an error message. - - If the method returns `null` for the parameter or if it returns an empty value for the property, the default method will be called to compose the error message. - + input value and a output value. The parameter provides additional context information that the method can use to determine the context that it is used in. The output parameter enables the method to return an error message. + + If the method returns `null` for the parameter or if it returns an empty value for the property, the default method will be called to compose the error message. + ]]> @@ -339,11 +339,11 @@ Gets the type that performs custom validation. The type that performs custom validation. - constructor overload. - + constructor overload. + ]]> diff --git a/xml/System.ComponentModel.DataAnnotations/DisplayAttribute.xml b/xml/System.ComponentModel.DataAnnotations/DisplayAttribute.xml index d7fe66bfb77..5bb6ce26141 100644 --- a/xml/System.ComponentModel.DataAnnotations/DisplayAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/DisplayAttribute.xml @@ -50,11 +50,11 @@ Provides a general-purpose attribute that lets you specify localizable strings for types and members of entity partial classes. - instance. - + instance. + ]]> @@ -90,11 +90,11 @@ Initializes a new instance of the class. - , , , and properties to an empty string. - + , , , and properties to an empty string. + ]]> @@ -135,11 +135,11 @@ if UI should be generated automatically to display this field; otherwise, . - property. Use the method instead. - + property. Use the method instead. + ]]> An attempt was made to get the property value before it was set. @@ -181,50 +181,50 @@ if UI should be generated automatically to display filtering for this field; otherwise, . - property. Use the method instead. - - Setting this property overrides the default behavior for specifying which columns are included as filters. - - - -## Examples - The following example shows how to disable the filter for the Employee1 field. - -```csharp -[MetadataType(typeof(EmployeeMD))] -public partial class Employee { - public class EmployeeMD { - [Display(Name = "Last Name", Order = -9, - Prompt = "Enter Last Name", Description="Emp Last Name")] - public object LastName { get; set; } - - [Display(Name = "Manager", AutoGenerateFilter=false)] - public object Employee1 { get; set; } - } -} -``` - -```vb - _ -Public Class Employee - - Public Class EmployeeMD - - _ - Public Property LastName As Object - End Property - - _ - Public Property Employee1 As Object - End Property - End Class -End Class -``` - + property. Use the method instead. + + Setting this property overrides the default behavior for specifying which columns are included as filters. + + + +## Examples + The following example shows how to disable the filter for the Employee1 field. + +```csharp +[MetadataType(typeof(EmployeeMD))] +public partial class Employee { + public class EmployeeMD { + [Display(Name = "Last Name", Order = -9, + Prompt = "Enter Last Name", Description="Emp Last Name")] + public object LastName { get; set; } + + [Display(Name = "Manager", AutoGenerateFilter=false)] + public object Employee1 { get; set; } + } +} +``` + +```vb + _ +Public Class Employee + + Public Class EmployeeMD + + _ + Public Property LastName As Object + End Property + + _ + Public Property Employee1 As Object + End Property + End Class +End Class +``` + ]]> An attempt was made to get the property value before it was set. @@ -266,50 +266,50 @@ End Class Gets or sets a value that is used to display a description in the UI. The value that is used to display a description in the UI. - property. Use the method instead. - - The property is typically used as a tooltip or description UI element that is bound to the member using this attribute. The Dynamic Data Edit.ascx template will display the description as a tooltip in text-entry fields. A `null` value or empty string is valid. - - - -## Examples - The following example shows how to set the property. - -```csharp -[MetadataType(typeof(EmployeeMD))] -public partial class Employee { - public class EmployeeMD { - [Display(Name = "Last Name", Order = -9, - Prompt = "Enter Last Name", Description="Emp Last Name")] - public object LastName { get; set; } - - [Display(Name = "Manager", AutoGenerateFilter=false)] - public object Employee1 { get; set; } - } -} -``` - -```vb - _ -Public Class Employee - - Public Class EmployeeMD - - _ - Public Property LastName As Object - End Property - - _ - Public Property Employee1 As Object - End Property - End Class -End Class -``` - + property. Use the method instead. + + The property is typically used as a tooltip or description UI element that is bound to the member using this attribute. The Dynamic Data Edit.ascx template will display the description as a tooltip in text-entry fields. A `null` value or empty string is valid. + + + +## Examples + The following example shows how to set the property. + +```csharp +[MetadataType(typeof(EmployeeMD))] +public partial class Employee { + public class EmployeeMD { + [Display(Name = "Last Name", Order = -9, + Prompt = "Enter Last Name", Description="Emp Last Name")] + public object LastName { get; set; } + + [Display(Name = "Manager", AutoGenerateFilter=false)] + public object Employee1 { get; set; } + } +} +``` + +```vb + _ +Public Class Employee + + Public Class EmployeeMD + + _ + Public Property LastName As Object + End Property + + _ + Public Property Employee1 As Object + End Property + End Class +End Class +``` + ]]> @@ -427,11 +427,11 @@ End Class Returns the value of the property. The localized description, if the has been specified and the property represents a resource key; otherwise, the non-localized value of the property. - property is typically used as a tooltip for the property that is annotated with this attribute. - + property is typically used as a tooltip for the property that is annotated with this attribute. + ]]> The property and the property are initialized, but a public static property that has a name that matches the value could not be found for the property. @@ -514,11 +514,11 @@ End Class Returns a value that is used for field display in the UI. The localized string for the property, if the property has been specified and the property represents a resource key; otherwise, the non-localized value of the property. - property. A `null` value or empty string is valid. - + property. A `null` value or empty string is valid. + ]]> The property and the property are initialized, but a public static property that has a name that matches the value could not be found for the property. @@ -560,11 +560,11 @@ End Class Returns the value of the property. The value of the property, if it has been set; otherwise, . - property to 10000. This value lets explicitly-ordered fields be displayed before and after the fields that do not have a specified order. - + property to 10000. This value lets explicitly-ordered fields be displayed before and after the fields that do not have a specified order. + ]]> @@ -606,11 +606,11 @@ End Class Returns the value of the property. The localized string for the property if the property has been specified and if the property represents a resource key; otherwise, the non-localized value of the property. - property is typically used as a prompt or watermark for a UI element that is bound to the property that is annotated with the attribute. - + property is typically used as a prompt or watermark for a UI element that is bound to the property that is annotated with the attribute. + ]]> Both the property and properties were set, but a public static property with a name matching the value couldn't be found on the . @@ -653,14 +653,14 @@ End Class Returns the value of the property. The localized string for the property if the property has been specified and if the property represents a resource key; otherwise, the non-localized value of the value property. - is not `null`. - + is not `null`. + ]]> - Both the property and properties were set, + Both the property and properties were set, but a public static property with a name matching the value couldn't be found on the . @@ -700,11 +700,11 @@ but a public static property with a name matching the property. Use the method instead. A `null` value or empty string is valid. - + property. Use the method instead. A `null` value or empty string is valid. + ]]> @@ -745,50 +745,50 @@ but a public static property with a name matching the property. Use the method instead. - - The name is typically used as the field label for a UI element that is bound to the property that is annotated with this attribute. The Dynamic Data List.aspx, ListDetails.aspx, and Details.aspx page templates use the property for the field label. A `null` value or empty string is valid. - - - -## Examples - The following example shows how to set the name property. - -```csharp -[MetadataType(typeof(EmployeeMD))] -public partial class Employee { - public class EmployeeMD { - [Display(Name = "Last Name", Order = -9, - Prompt = "Enter Last Name", Description="Emp Last Name")] - public object LastName { get; set; } - - [Display(Name = "Manager", AutoGenerateFilter=false)] - public object Employee1 { get; set; } - } -} -``` - -```vb - _ -Public Class Employee - - Public Class EmployeeMD - - _ - Public Property LastName As Object - End Property - - _ - Public Property Employee1 As Object - End Property - End Class -End Class -``` - + property. Use the method instead. + + The name is typically used as the field label for a UI element that is bound to the property that is annotated with this attribute. The Dynamic Data List.aspx, ListDetails.aspx, and Details.aspx page templates use the property for the field label. A `null` value or empty string is valid. + + + +## Examples + The following example shows how to set the name property. + +```csharp +[MetadataType(typeof(EmployeeMD))] +public partial class Employee { + public class EmployeeMD { + [Display(Name = "Last Name", Order = -9, + Prompt = "Enter Last Name", Description="Emp Last Name")] + public object LastName { get; set; } + + [Display(Name = "Manager", AutoGenerateFilter=false)] + public object Employee1 { get; set; } + } +} +``` + +```vb + _ +Public Class Employee + + Public Class EmployeeMD + + _ + Public Property LastName As Object + End Property + + _ + Public Property Employee1 As Object + End Property + End Class +End Class +``` + ]]> @@ -828,48 +828,48 @@ End Class Gets or sets the order weight of the column. The order weight of the column. - _ -Public Class Employee - - Public Class EmployeeMD - - _ - Public Property LastName As Object - End Property - - _ - Public Property Employee1 As Object - End Property - End Class -End Class -``` - + _ +Public Class Employee + + Public Class EmployeeMD + + _ + Public Property LastName As Object + End Property + + _ + Public Property Employee1 As Object + End Property + End Class +End Class +``` + ]]> The getter of this property has been invoked but its value has not been explicitly set using the setter. @@ -911,48 +911,48 @@ End Class Gets or sets a value that will be used to set the watermark for prompts in the UI. A value that will be used to display a watermark in the UI. - method instead. - - - -## Examples - The following example shows how to set the property to "Enter Last Name". - -```csharp -[MetadataType(typeof(EmployeeMD))] -public partial class Employee { - public class EmployeeMD { - [Display(Name = "Last Name", Order = -9, - Prompt = "Enter Last Name", Description="Emp Last Name")] - public object LastName { get; set; } - - [Display(Name = "Manager", AutoGenerateFilter=false)] - public object Employee1 { get; set; } - } -} -``` - -```vb - _ -Public Class Employee - - Public Class EmployeeMD - - _ - Public Property LastName As Object - End Property - - _ - Public Property Employee1 As Object - End Property - End Class -End Class -``` - + method instead. + + + +## Examples + The following example shows how to set the property to "Enter Last Name". + +```csharp +[MetadataType(typeof(EmployeeMD))] +public partial class Employee { + public class EmployeeMD { + [Display(Name = "Last Name", Order = -9, + Prompt = "Enter Last Name", Description="Emp Last Name")] + public object LastName { get; set; } + + [Display(Name = "Manager", AutoGenerateFilter=false)] + public object Employee1 { get; set; } + } +} +``` + +```vb + _ +Public Class Employee + + Public Class EmployeeMD + + _ + Public Property LastName As Object + End Property + + _ + Public Property Employee1 As Object + End Property + End Class +End Class +``` + ]]> @@ -1003,11 +1003,11 @@ End Class Gets or sets the type that contains the resources for the , , , and properties. The type of the resource that contains the , , , and properties. - , , , and properties are assumed to be literal, non-localized strings. If this value is not `null`, the string properties are assumed to be the names of public static properties that return the actual string value. - + , , , and properties are assumed to be literal, non-localized strings. If this value is not `null`, the string properties are assumed to be the names of public static properties that return the actual string value. + ]]> @@ -1048,11 +1048,11 @@ End Class Gets or sets a value that is used for the grid column label. A value that is for the grid column label. - for the field label. This property returns the localized string for if the property has been specified and if the property represents a resource key. If the property has not been specified or if the property is not a resource key, this property returns a non-localized string. - + for the field label. This property returns the localized string for if the property has been specified and if the property represents a resource key. If the property has not been specified or if the property is not a resource key, this property returns a non-localized string. + ]]> diff --git a/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml b/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml index 60f0fa1ac91..0d70842b4f2 100644 --- a/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/DisplayFormatAttribute.xml @@ -162,12 +162,12 @@ The following example shows how to use the property is applied to field values only when the data-bound control is in read-only mode. + By default, the formatting string that is specified by the property is applied to field values only when the data-bound control is in read-only mode. ## Examples - The following example shows how to use the property to set the display format for date information when the data field is in edit mode. The data field format to use for the data field is specified by setting the property. + The following example shows how to use the property to set the display format for date information when the data field is in edit mode. The data field format to use for the data field is specified by setting the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataAnnotations.DisplayFormatAttribute/CS/product.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataAnnotations.DisplayFormatAttribute/VB/product.vb" id="Snippet4"::: @@ -226,10 +226,10 @@ The following example shows how to use the property to specify whether an empty string value is automatically converted to `null` when the data field is updated in the database. + Users might enter an empty string for a field value. Use the property to specify whether an empty string value is automatically converted to `null` when the data field is updated in the database. > [!NOTE] -> By default, a object displays `null` values as empty strings. To display a different value, set the property. +> By default, a object displays `null` values as empty strings. To display a different value, set the property. @@ -293,12 +293,12 @@ The following example shows how to use the property to specify a custom display format for the values that are displayed in the object. If the property is not set, the field's value is displayed without any special formatting. For more information, see [Formatting Types](/dotnet/standard/base-types/formatting-types). + Use the property to specify a custom display format for the values that are displayed in the object. If the property is not set, the field's value is displayed without any special formatting. For more information, see [Formatting Types](/dotnet/standard/base-types/formatting-types). > [!NOTE] -> When the property is `true`, the value of the field is HTML encoded to its string representation before the formatting string is applied. For some objects, such as dates, you might want to control how the object is displayed with a formatting string. In those cases, you must set the property to `false`. +> When the property is `true`, the value of the field is HTML encoded to its string representation before the formatting string is applied. For some objects, such as dates, you might want to control how the object is displayed with a formatting string. In those cases, you must set the property to `false`. - By default, the formatting string is applied to the field value only when the data-bound control that contains the object is in read-only mode. To apply the formatting string to field values when they are in edit mode, set the property to `true`. + By default, the formatting string is applied to the field value only when the data-bound control that contains the object is in read-only mode. To apply the formatting string to field values when they are in edit mode, set the property to `true`. The formatting string can be any literal string and usually includes a placeholder for the field's value. For example, in the formatting string "Item Value: {0}", the field's value is substituted for the {0} placeholder when the string is displayed in the object. The remainder of the formatting string is displayed as literal text. @@ -308,7 +308,7 @@ The following example shows how to use the property to set the display format of data fields. The first example sets the display format for a currency type data field. The second example sets the display format for a date type data field. + The following examples show how to use the property to set the display format of data fields. The first example sets the display format for a currency type data field. The second example sets the display format for a date type data field. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataAnnotations.DisplayFormatAttribute/CS/product.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataAnnotations.DisplayFormatAttribute/VB/product.vb" id="Snippet3"::: @@ -461,10 +461,10 @@ The following example shows how to use the property. If this property is not set, null field values are displayed as empty strings (""). + Sometimes a data field's value is stored as null values in the source. You can specify custom text to display for data fields that have a null value by setting the property. If this property is not set, null field values are displayed as empty strings (""). > [!NOTE] -> To convert an empty string field value to a null value, you must set the property to `true`. +> To convert an empty string field value to a null value, you must set the property to `true`. diff --git a/xml/System.ComponentModel.DataAnnotations/ScaffoldColumnAttribute.xml b/xml/System.ComponentModel.DataAnnotations/ScaffoldColumnAttribute.xml index 248b1aeda52..d545bb1e40a 100644 --- a/xml/System.ComponentModel.DataAnnotations/ScaffoldColumnAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/ScaffoldColumnAttribute.xml @@ -46,7 +46,7 @@ property to enable scaffolding in a Dynamic Data Web Site. + Scaffolding is the mechanism for generating web page templates based on database schemas. ASP.NET Dynamic Data uses scaffolding to generate Web-based UI that lets a user to view and update a database. This class uses the property to enable scaffolding in a Dynamic Data Web Site. Scaffolding enhances ASP.NET page framework by dynamically displaying pages based on the data model with no physical pages required. diff --git a/xml/System.ComponentModel.DataAnnotations/ScaffoldTableAttribute.xml b/xml/System.ComponentModel.DataAnnotations/ScaffoldTableAttribute.xml index 8898e454437..6500a0b038f 100644 --- a/xml/System.ComponentModel.DataAnnotations/ScaffoldTableAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/ScaffoldTableAttribute.xml @@ -27,7 +27,7 @@ property to enable scaffolding of individual tables in a Dynamic Data Web Site. Scaffolding enhances the ASP.NET page framework by dynamically displaying pages based on the data model with no physical pages required. + Scaffolding is the mechanism for generating web page templates based on database schemas. ASP.NET Dynamic Data uses scaffolding to generate Web-based UI that lets a user to view and update a database. This class uses the property to enable scaffolding of individual tables in a Dynamic Data Web Site. Scaffolding enhances the ASP.NET page framework by dynamically displaying pages based on the data model with no physical pages required. Scaffolding provides the following: diff --git a/xml/System.ComponentModel.DataAnnotations/UIHintAttribute.xml b/xml/System.ComponentModel.DataAnnotations/UIHintAttribute.xml index 5a09e0040fa..a2a921a9119 100644 --- a/xml/System.ComponentModel.DataAnnotations/UIHintAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/UIHintAttribute.xml @@ -47,23 +47,23 @@ Specifies the template or user control that Dynamic Data uses to display a data field. - class to associate a model with a data field. Dynamic Data uses the class to associate a user control with a data field. Dynamic Data uses the property to determine which user control to use in order to display a data field. - - For more information about how to use attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following example shows how to use the attribute to specify the name of a custom field template that will handle the display and editing of a data field. - - For a complete example, see [How to: Customize Data Field Display in the Data Model](/previous-versions/aspnet/cc488522(v=vs.100)). - + MVC uses the class to associate a model with a data field. Dynamic Data uses the class to associate a user control with a data field. Dynamic Data uses the property to determine which user control to use in order to display a data field. + + For more information about how to use attributes, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following example shows how to use the attribute to specify the name of a custom field template that will handle the display and editing of a data field. + + For a complete example, see [How to: Customize Data Field Display in the Data Model](/previous-versions/aspnet/cc488522(v=vs.100)). + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/DynamicData.CustomFieldTemplate/CS/Product.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/DynamicData.CustomFieldTemplate/VB/Products.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/DynamicData.CustomFieldTemplate/VB/Products.vb" id="Snippet5"::: + ]]> How to: Customize Data Field Display in the Data Model @@ -115,13 +115,13 @@ The user control to use to display the data field. Initializes a new instance of the class by using a specified user control. - object that is created with this constructor is initialized using the specified `uiHint`, which specifies the user control (field template) to use in order to display the data field. - - ASP.NET Dynamic Data provides field templates, page templates, and data controls to render data fields in a data model. You can modify these templates and controls to customize them, or you can create a custom user control. If you create a custom user control, you use the property to specify the user control to use to display a data field. - + object that is created with this constructor is initialized using the specified `uiHint`, which specifies the user control (field template) to use in order to display the data field. + + ASP.NET Dynamic Data provides field templates, page templates, and data controls to render data fields in a data model. You can modify these templates and controls to customize them, or you can create a custom user control. If you create a custom user control, you use the property to specify the user control to use to display a data field. + ]]> @@ -230,10 +230,10 @@ Initializes a new instance of the class by using the specified user control, presentation layer, and control parameters. To be added. - is or it is a constraint key. - - -or- - + is or it is a constraint key. + + -or- + The value of is not a string. @@ -280,11 +280,11 @@ Gets or sets the object to use to retrieve values from any data source. A collection of key/value pairs. - property lets you retrieve data from a data model, tracks updates to the data model, and notifies the model of any changes. - + property lets you retrieve data from a data model, tracks updates to the data model, and notifies the model of any changes. + ]]> The current attribute is ill-formed. @@ -421,11 +421,11 @@ Gets or sets the presentation layer that uses the class. The presentation layer that is used by this class. - class. This property can be set to "HTML", "Silverlight", "WPF", or "WinForms". - + class. This property can be set to "HTML", "Silverlight", "WPF", or "WinForms". + ]]> @@ -490,16 +490,16 @@ Gets or sets the name of the field template to use to display the data field. The name of the field template that displays the data field. - property on a property so that the property is rendered using the custom user control. The property specifies which field template to use when a specific column is rendered. The property can point to one of the templates provided in Dynamic Data or to a custom template. For example, you can create a custom field template named RedText_Edit.ascx, and then use the property to specify that the RedText_Edit.ascx control should be used to render a specified data field instead of the default Text_Edit.ascx template that is provided in Dynamic Data. - - The following example shows how to specify that the UnitsInStock column in a database will be rendered by using the specified custom field template. - + property on a property so that the property is rendered using the custom user control. The property specifies which field template to use when a specific column is rendered. The property can point to one of the templates provided in Dynamic Data or to a custom template. For example, you can create a custom field template named RedText_Edit.ascx, and then use the property to specify that the RedText_Edit.ascx control should be used to render a specified data field instead of the default Text_Edit.ascx template that is provided in Dynamic Data. + + The following example shows how to specify that the UnitsInStock column in a database will be rendered by using the specified custom field template. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/DynamicData.CustomFieldTemplate/CS/Product.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/DynamicData.CustomFieldTemplate/VB/Products.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/DynamicData.CustomFieldTemplate/VB/Products.vb" id="Snippet5"::: + ]]> ASP.NET Dynamic Data Overview diff --git a/xml/System.ComponentModel.DataAnnotations/ValidationAttribute.xml b/xml/System.ComponentModel.DataAnnotations/ValidationAttribute.xml index ac4c0491100..927d478be3a 100644 --- a/xml/System.ComponentModel.DataAnnotations/ValidationAttribute.xml +++ b/xml/System.ComponentModel.DataAnnotations/ValidationAttribute.xml @@ -140,7 +140,7 @@ This constructor chooses a generic validation error message. If you subclass `Va property to retrieve an error message. +This constructor provides a resource accessor function that is used by the property to retrieve an error message. ]]> @@ -283,7 +283,7 @@ This property is the error message that you associate with the validation contro property together with the property in order to provide a localized error message. + You use the property together with the property in order to provide a localized error message. ]]> @@ -339,7 +339,7 @@ This property is the error message that you associate with the validation contro property together with the property in order to provide a localized error message. + You use the property together with the property in order to provide a localized error message. ]]> @@ -390,7 +390,7 @@ This property is the error message that you associate with the validation contro property or by evaluating the and properties. The two cases are mutually exclusive. The second case is used if you want to display a localized error message. + The error message string is obtained by evaluating the property or by evaluating the and properties. The two cases are mutually exclusive. The second case is used if you want to display a localized error message. ]]> @@ -439,7 +439,7 @@ This property is the error message that you associate with the validation contro property. This method appends the name of the data field that triggered the error to the formatted error message. You can customize how the error message is formatted by creating a derived class that overrides this method. + This method formats an error message by using the property. This method appends the name of the data field that triggered the error to the formatted error message. You can customize how the error message is formatted by creating a derived class that overrides this method. ]]> diff --git a/xml/System.ComponentModel.DataAnnotations/ValidationContext.xml b/xml/System.ComponentModel.DataAnnotations/ValidationContext.xml index d4bd99216eb..0473206ebd7 100644 --- a/xml/System.ComponentModel.DataAnnotations/ValidationContext.xml +++ b/xml/System.ComponentModel.DataAnnotations/ValidationContext.xml @@ -46,11 +46,11 @@ Describes the context in which a validation check is performed. - interface. - + interface. + ]]> @@ -177,11 +177,11 @@ An optional set of key/value pairs to make available to consumers. Initializes a new instance of the class using the specified object and an optional property bag. - @@ -256,13 +256,13 @@ A dictionary of key/value pairs to make available to the service consumers. This parameter is optional. Initializes a new instance of the class using the service provider and dictionary of service consumers. - method in order to perform custom validation. - - If the `items` parameter is `null`, an empty dictionary is created. If the parameter is not `null`, the set of key/value pairs is copied into a new dictionary, which prevents the service consumers from modifying the original dictionary. - + method in order to perform custom validation. + + If the `items` parameter is `null`, an empty dictionary is created. If the parameter is not `null`, the set of key/value pairs is copied into a new dictionary, which prevents the service consumers from modifying the original dictionary. + ]]> @@ -360,11 +360,11 @@ Gets or sets the name of the member to validate. The name of the member to validate. - value is the name that is shown to the user. If a display name is not explicitly set, this property uses the value that is assigned by the associated object. If that attribute does not exist, the property returns the value of the property. - + value is the name that is shown to the user. If a display name is not explicitly set, this property uses the value that is assigned by the associated object. If that attribute does not exist, the property returns the value of the property. + ]]> @@ -412,13 +412,13 @@ Returns the service that provides custom validation. An instance of the service, or if the service is not available. - object is defined at the application level, the method accesses it to retrieve the requested service. - - If the object is not defined or it does not return the service, the method queries the object that is passed to the method in order to obtain the service. - + object is defined at the application level, the method accesses it to retrieve the requested service. + + If the object is not defined or it does not return the service, the method queries the object that is passed to the method in order to obtain the service. + ]]> @@ -518,11 +518,11 @@ Gets the dictionary of key/value pairs that is associated with this context. The dictionary of the key/value pairs for this context. - @@ -577,8 +577,8 @@ Gets or sets the name of the member to validate. The name of the member to validate. - Gets the object to validate. The object to validate. - @@ -710,13 +710,13 @@ In .NET Framework 4.8 version prior to the October 2019 update, this property re Gets the validation services container. The validation services container. - property is used for getting services during validation. - - If the provider that is specified in the constructor implements the interface, the provider is used to initialize the property. Otherwise the property is initialized to an empty container. - + property is used for getting services during validation. + + If the provider that is specified in the constructor implements the interface, the provider is used to initialize the property. Otherwise the property is initialized to an empty container. + ]]> diff --git a/xml/System.ComponentModel.DataAnnotations/ValidationException.xml b/xml/System.ComponentModel.DataAnnotations/ValidationException.xml index 34f4e928ceb..d5a62a463bd 100644 --- a/xml/System.ComponentModel.DataAnnotations/ValidationException.xml +++ b/xml/System.ComponentModel.DataAnnotations/ValidationException.xml @@ -275,7 +275,7 @@ property, not `innerException`. + You typically will not use this constructor because validation exceptions are stored in the property, not `innerException`. ]]> diff --git a/xml/System.ComponentModel.DataAnnotations/ValidationResult.xml b/xml/System.ComponentModel.DataAnnotations/ValidationResult.xml index 03f4fc204cc..ee7fbbe1f78 100644 --- a/xml/System.ComponentModel.DataAnnotations/ValidationResult.xml +++ b/xml/System.ComponentModel.DataAnnotations/ValidationResult.xml @@ -90,11 +90,11 @@ The validation result object. Initializes a new instance of the class by using a object. - object. - + object. + ]]> @@ -238,11 +238,11 @@ Gets the error message for the validation. The error message for the validation. - property to `null`. - + property to `null`. + ]]> @@ -292,11 +292,11 @@ Gets the collection of member names that indicate which fields have validation errors. The collection of member names that indicate which fields have validation errors. - diff --git a/xml/System.ComponentModel.Design.Data/DesignerDataConnection.xml b/xml/System.ComponentModel.Design.Data/DesignerDataConnection.xml index 3b150a1921c..635d63e8ac0 100644 --- a/xml/System.ComponentModel.Design.Data/DesignerDataConnection.xml +++ b/xml/System.ComponentModel.Design.Data/DesignerDataConnection.xml @@ -17,11 +17,11 @@ Represents a connection to a data store in a design tool. This class cannot be inherited. - object represents a connection to a data store in the design tool. Typically a object is returned as part of the property, and is created either by reading the application's configuration file or by calling the method. - + object represents a connection to a data store in the design tool. Typically a object is returned as part of the property, and is created either by reading the application's configuration file or by calling the method. + ]]> @@ -65,11 +65,11 @@ The string that specifies how to connect to the data store. Initializes a new instance of the class with the specified name, data provider, and connection string. - objects that are not created from the application's configuration file. When you use this constructor, the property is set to `false`. - + objects that are not created from the application's configuration file. When you use this constructor, the property is set to `false`. + ]]> @@ -107,11 +107,11 @@ to indicate the connection was created from information stored in the application's configuration file; otherwise, . Initializes a new instance of the class with the specified name, data provider, and connection string, and indicates whether the connection was loaded from a configuration file. - property, such as when you are creating a object from information stored in the application's configuration file. The property is set to the value of the `isConfigured` parameter. - + property, such as when you are creating a object from information stored in the application's configuration file. The property is set to the value of the `isConfigured` parameter. + ]]> @@ -142,11 +142,11 @@ Gets the application connection string defined for the connection. The application connection string defined for the connection. - property contains the connection string used by the application for connecting to the data store. You must use the method to return a connection string suitable for use in the design environment. - + property contains the connection string used by the application for connecting to the data store. You must use the method to return a connection string suitable for use in the design environment. + ]]> @@ -178,13 +178,13 @@ if the connection is defined in the application's configuration file; otherwise, . - property will be `true` if the object was read from the application's configuration file, or if the object was written to the application's configuration file by the method. - - When the is `true`, the property is set to the name of the connection as defined in the [connectionStrings Element (ASP.NET Settings Schema)](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bf7sd233(v=vs.100)) of the configuration file. - + property will be `true` if the object was read from the application's configuration file, or if the object was written to the application's configuration file by the method. + + When the is `true`, the property is set to the name of the connection as defined in the [connectionStrings Element (ASP.NET Settings Schema)](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bf7sd233(v=vs.100)) of the configuration file. + ]]> @@ -215,11 +215,11 @@ Gets the name of the data connection. The name of the data connection. - property contains the name that identifies a specific connection in an application configuration file or a list of data connections. When the property is `true`, property is used as the `name` attribute in the [connectionStrings Element (ASP.NET Settings Schema)](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bf7sd233(v=vs.100)) configuration element, or is returned from the method. - + property contains the name that identifies a specific connection in an application configuration file or a list of data connections. When the property is `true`, property is used as the `name` attribute in the [connectionStrings Element (ASP.NET Settings Schema)](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bf7sd233(v=vs.100)) configuration element, or is returned from the method. + ]]> diff --git a/xml/System.ComponentModel.Design.Data/DesignerDataParameter.xml b/xml/System.ComponentModel.Design.Data/DesignerDataParameter.xml index a34e094ae9c..b9c3b651e55 100644 --- a/xml/System.ComponentModel.Design.Data/DesignerDataParameter.xml +++ b/xml/System.ComponentModel.Design.Data/DesignerDataParameter.xml @@ -17,13 +17,13 @@ Represents a parameter for a stored procedure. This class cannot be inherited. - class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. - - The class represents the parameters required to call a stored procedure in the data store. The property contains a collection of objects. - + class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. + + The class represents the parameters required to call a stored procedure in the data store. The property contains a collection of objects. + ]]> @@ -86,11 +86,11 @@ Gets the database type of the parameter. One of the values. - property contains the type of data required by the underlying data store. - + property contains the type of data required by the underlying data store. + ]]> @@ -121,11 +121,11 @@ Gets a value indicating whether the parameter is input-only, output-only, bidirectional, or a stored procedure return-value parameter. One of the values. - property to indicate whether a parameter is passed into a stored procedure, returned from a stored procedure, or both. - + property to indicate whether a parameter is passed into a stored procedure, returned from a stored procedure, or both. + ]]> diff --git a/xml/System.ComponentModel.Design.Data/DesignerDataStoredProcedure.xml b/xml/System.ComponentModel.Design.Data/DesignerDataStoredProcedure.xml index 4c68f3eb2be..b48ef3360a9 100644 --- a/xml/System.ComponentModel.Design.Data/DesignerDataStoredProcedure.xml +++ b/xml/System.ComponentModel.Design.Data/DesignerDataStoredProcedure.xml @@ -17,13 +17,13 @@ Represents a stored procedure in the data store. - class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. - - The class represents a single table in the data store. A collection of objects is returned when you call the method with the `schemaClass` parameter set to . - + class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. + + The class represents a single table in the data store. A collection of objects is returned when you call the method with the `schemaClass` parameter set to . + ]]> @@ -116,11 +116,11 @@ When overridden in a derived class, returns a collection of parameters for the stored procedure. A collection of objects. - method is called the first time the property is accessed to populate the collection of stored-procedure parameters. - + method is called the first time the property is accessed to populate the collection of stored-procedure parameters. + ]]> @@ -201,11 +201,11 @@ Gets a collection of parameters required for a stored procedure. A collection of parameters for the stored procedure. - property is populated by the method the first time the property is accessed. - + property is populated by the method the first time the property is accessed. + ]]> diff --git a/xml/System.ComponentModel.Design.Data/DesignerDataTable.xml b/xml/System.ComponentModel.Design.Data/DesignerDataTable.xml index bfde2bf52ab..b15a0cb76f7 100644 --- a/xml/System.ComponentModel.Design.Data/DesignerDataTable.xml +++ b/xml/System.ComponentModel.Design.Data/DesignerDataTable.xml @@ -17,13 +17,13 @@ Represents a table in the data store. - class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. - - The class represents a single table in the data store. A collection of objects is returned when you call the method with the `schemaClass` parameter set to . - + class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. + + The class represents a single table in the data store. A collection of objects is returned when you call the method with the `schemaClass` parameter set to . + ]]> @@ -116,11 +116,11 @@ When overridden in a derived class, returns a collection of relationship objects. A collection of objects. - method is called the first time the property is accessed, to populate the collection of data table relationships. - + method is called the first time the property is accessed, to populate the collection of data table relationships. + ]]> @@ -145,11 +145,11 @@ Gets a collection of relationships defined for a table. A collection of objects. - property returns a collection that represents all the relationships between this table and other tables in the data store. - + property returns a collection that represents all the relationships between this table and other tables in the data store. + ]]> diff --git a/xml/System.ComponentModel.Design.Data/DesignerDataTableBase.xml b/xml/System.ComponentModel.Design.Data/DesignerDataTableBase.xml index 03764149c4c..a24cc2c3de0 100644 --- a/xml/System.ComponentModel.Design.Data/DesignerDataTableBase.xml +++ b/xml/System.ComponentModel.Design.Data/DesignerDataTableBase.xml @@ -17,15 +17,15 @@ Defines the properties and methods shared between data-store tables and data-store views. - class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. - - The class provides the properties and methods shared between data tables in a data store and views defined on those data tables. - - When you inherit from the class, you must override the method. - + class is one of several types that represent the schema of a data store at design-time. These schema items are made available to controls by designers implementing the interface. Controls access schema objects by calling the method of the interface. + + The class provides the properties and methods shared between data tables in a data store and views defined on those data tables. + + When you inherit from the class, you must override the method. + ]]> @@ -65,11 +65,11 @@ The name of the table or view. Initializes a new instance of the class. - @@ -102,11 +102,11 @@ The data-store owner of the table or view. Initializes a new instance of the class. - @@ -131,11 +131,11 @@ Gets a collection of columns defined for a table or view. A collection of columns defined for a table or view. - property is populated by the method the first time the property is accessed. - + property is populated by the method the first time the property is accessed. + ]]> @@ -161,11 +161,11 @@ When overridden in a derived class, returns a collection of data-store column objects. A collection of objects. - method is called the first time the property is accessed, to populate the collection of data-store columns. - + method is called the first time the property is accessed, to populate the collection of data-store columns. + ]]> diff --git a/xml/System.ComponentModel.Design.Data/IDataEnvironment.xml b/xml/System.ComponentModel.Design.Data/IDataEnvironment.xml index 9ac50dfd9fc..df5debec78d 100644 --- a/xml/System.ComponentModel.Design.Data/IDataEnvironment.xml +++ b/xml/System.ComponentModel.Design.Data/IDataEnvironment.xml @@ -14,13 +14,13 @@ Defines an interface to data services that enables control designers to integrate data store or database-related functionality into their design environment. - interface can access the data connections available to an application at design time. The interface provides methods to list available data connections, create new data connections, retrieve schema information from a connection, and save data-connection configuration information to the application's configuration file. - - The interface enables you to interact with data connections in the design environment, but it is not intended as a data-management API. - + interface can access the data connections available to an application at design time. The interface provides methods to list available data connections, create new data connections, retrieve schema information from a connection, and save data-connection configuration information to the application's configuration file. + + The interface enables you to interact with data connections in the design environment, but it is not intended as a data-management API. + ]]> @@ -51,17 +51,17 @@ Creates a new data connection or edits an existing connection using the design tool's new connection user interface. A new or edited object, or if the user canceled. - method to activate the design environment's user interface for creating or editing data connections. If the `initialConnection` parameter is `null`, it indicates the user wants to create a new connection. If the `initialConnection` parameter is a object, it indicates the user wants to edit an existing connection. - - Your design environment is responsible for creating the data connection, adding the connection either to a global list of connections or to the Web application's configuration file, and adding the new connection to the property. - - The new connection should include the information that the application needs to create a data connection at run time. If you need to use the data connection in the design environment, use the method to return a object that will connect to the data store from the design environment. - - If the user chooses to cancel the new connection creation process, the method should return `null`. - + method to activate the design environment's user interface for creating or editing data connections. If the `initialConnection` parameter is `null`, it indicates the user wants to create a new connection. If the `initialConnection` parameter is a object, it indicates the user wants to edit an existing connection. + + Your design environment is responsible for creating the data connection, adding the connection either to a global list of connections or to the Web application's configuration file, and adding the new connection to the property. + + The new connection should include the information that the application needs to create a data connection at run time. If you need to use the data connection in the design environment, use the method to return a object that will connect to the data store from the design environment. + + If the user chooses to cancel the new connection creation process, the method should return `null`. + ]]> @@ -96,13 +96,13 @@ Launches a dialog to build a SQL query string. A string containing the SQL query, or if the user canceled. - method launches the design environment's UI for editing or creating SQL query strings. If the `initialQueryText` parameter is , it indicates the user wants to create a new query. If the `initialQueryText` parameter contains a string, it indicates the user wants to edit the existing query. - - The `mode` parameter indicates the type of query the user wants to build; either select, update, insert, or delete. Your user interface can use the `mode` parameter to configure itself for the type of query desired, limit the user to using SQL statements valid only for the type of query desired, and/or validate the query against the desired type. - + method launches the design environment's UI for editing or creating SQL query strings. If the `initialQueryText` parameter is , it indicates the user wants to create a new query. If the `initialQueryText` parameter contains a string, it indicates the user wants to edit the existing query. + + The `mode` parameter indicates the type of query the user wants to build; either select, update, insert, or delete. Your user interface can use the `mode` parameter to configure itself for the type of query desired, limit the user to using SQL statements valid only for the type of query desired, and/or validate the query against the desired type. + ]]> @@ -135,21 +135,21 @@ Writes a connection string to the application's configuration file. A object containing the saved connection data with the property set to , and the property set to . - method writes a connection to the application's configuration file. The connection string and provider name are written to the [connectionStrings Element (ASP.NET Settings Schema)](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bf7sd233(v=vs.100)) configuration element named according to the `name` parameter. The property of the `connection` parameter is ignored. - - Implementations of the method should throw the following exceptions. - -|Exception|Reason| -|---------------|------------| -||A duplicate name exists in the application's configuration file.| -|, , or other appropriate file IO exception.|The application's configuration file cannot be updated. Your method implementation should throw an appropriate exception.| -||The application's configuration file cannot be checked out from the source control system.| - - Consider using the configuration-management APIs in the namespace to read and write the application's configuration file. The class will read and write the [connectionStrings Element (ASP.NET Settings Schema)](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bf7sd233(v=vs.100)) configuration element. - + method writes a connection to the application's configuration file. The connection string and provider name are written to the [connectionStrings Element (ASP.NET Settings Schema)](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bf7sd233(v=vs.100)) configuration element named according to the `name` parameter. The property of the `connection` parameter is ignored. + + Implementations of the method should throw the following exceptions. + +|Exception|Reason| +|---------------|------------| +||A duplicate name exists in the application's configuration file.| +|, , or other appropriate file IO exception.|The application's configuration file cannot be updated. Your method implementation should throw an appropriate exception.| +||The application's configuration file cannot be checked out from the source control system.| + + Consider using the configuration-management APIs in the namespace to read and write the application's configuration file. The class will read and write the [connectionStrings Element (ASP.NET Settings Schema)](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bf7sd233(v=vs.100)) configuration element. + ]]> @@ -174,13 +174,13 @@ Gets a collection of data connections defined in the current design session. A collection of objects representing the data connections available in the current design session. - property returns the set of connections available at design time. Your implementation of the property can return either the list of connections defined in the current Web application, or a list of connections defined at a global level, such as a list of data connections maintained by the design environment. - - Each connection in the collection should have a unique connection string. If your collection includes both connections from the application's configuration file and global connections, your implementation must handle the case where connections from the global list and the configuration file have the same connection string. In this case, it is recommended that you eliminate duplicates and use the configuration-file connection only. - + property returns the set of connections available at design time. Your implementation of the property can return either the list of connections defined in the current Web application, or a list of connections defined at a global level, such as a list of data connections maintained by the design environment. + + Each connection in the collection should have a unique connection string. If your collection includes both connections from the application's configuration file and global connections, your implementation must handle the case where connections from the global list and the configuration file have the same connection string. In this case, it is recommended that you eliminate duplicates and use the configuration-file connection only. + ]]> @@ -235,11 +235,11 @@ Gets the schema for the specified data connection. An object containing the schema information for the specified data connection, or if no schema information is available. - method returns the database schema for the specified data connection. If the schema is unavailable, or if the provider for the connection is unavailable, the should return `null`. - + method returns the database schema for the specified data connection. If the schema is unavailable, or if the provider for the connection is unavailable, the should return `null`. + ]]> @@ -268,13 +268,13 @@ Gets a database connection that can be used at design time. A object that can be used at design time. - method returns a valid, open connection to the data store that can be used by the control designer. - - Control designers should use the to obtain a data connection and should not attempt to open a connection using the property. - + method returns a valid, open connection to the data store that can be used by the control designer. + + Control designers should use the to obtain a data connection and should not attempt to open a connection using the property. + ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/BasicDesignerLoader.xml b/xml/System.ComponentModel.Design.Serialization/BasicDesignerLoader.xml index 96c11c86310..be3f1eda9fd 100644 --- a/xml/System.ComponentModel.Design.Serialization/BasicDesignerLoader.xml +++ b/xml/System.ComponentModel.Design.Serialization/BasicDesignerLoader.xml @@ -62,7 +62,7 @@ - Deferred idle-time reloading. - A adds two kinds of services to the designer host's service container: replaceable services and irreplaceable services. You can replace a replaceable service by changing the value of the protected property. You cannot replace irreplaceable services because their implementations depend on each other. + A adds two kinds of services to the designer host's service container: replaceable services and irreplaceable services. You can replace a replaceable service by changing the value of the protected property. You cannot replace irreplaceable services because their implementations depend on each other. The following table describes the services that are provided by default. @@ -716,7 +716,7 @@ method is called in response to a component changing, adding, or removing event which indicates that the designer is about to be modified. You can implement source code control by overriding this method. A call to does not mean that the property will later be set to `true`; it merely indicates an intention to do so. + The method is called in response to a component changing, adding, or removing event which indicates that the designer is about to be modified. You can implement source code control by overriding this method. A call to does not mean that the property will later be set to `true`; it merely indicates an intention to do so. ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/CodeDomDesignerLoader.xml b/xml/System.ComponentModel.Design.Serialization/CodeDomDesignerLoader.xml index 1e540da26b4..5a22d2c49f5 100644 --- a/xml/System.ComponentModel.Design.Serialization/CodeDomDesignerLoader.xml +++ b/xml/System.ComponentModel.Design.Serialization/CodeDomDesignerLoader.xml @@ -54,11 +54,11 @@ Provides the base class for implementing a CodeDOM-based designer loader. - is an abstract class that provides a full designer loader based on the Code Document Object Model (CodeDOM). You provide the CodeDOM parser and generator, and a type resolution service. - + is an abstract class that provides a full designer loader based on the Code Document Object Model (CodeDOM). You provide the CodeDOM parser and generator, and a type resolution service. + ]]> @@ -136,11 +136,11 @@ Gets the this designer loader will use. The this designer loader will use. - , but it does use the provider to obtain an that it can use to validate identifiers in the name-creation service. The designer loader will also check the to see if it implements the interface. For more information on parsing or generating code, see the and methods. - + , but it does use the provider to obtain an that it can use to validate identifiers in the name-creation service. The designer loader will also check the to see if it implements the interface. For more information on parsing or generating code, see the and methods. + ]]> @@ -176,16 +176,16 @@ Releases the resources used by the class. - method removes services added by the method. - - Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + method removes services added by the method. + + Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + > [!NOTE] -> Always call 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. - +> Always call 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. + ]]> @@ -221,19 +221,19 @@ Initializes services. - adds to the service container. - -|Term|Definition| -|----------|----------------| -||Provides semantics for creating names of objects. The service uses the CodeDOM provider's interface to create names that are valid identifiers for the language. In addition, the name creation service supports empty names. Empty names should be interpreted as temporary local variables during serialization.| -||Allows other objects to serialize a group of components into a binary object. This service is most often used by features such as copy and paste or undo and redo. The class provides a designer serialization service that is based on creating CodeDOM trees for objects.| -||This service replaces as a means to serialize components to a binary object.| - - For details on replaceable and non-replaceable services, see . - + adds to the service container. + +|Term|Definition| +|----------|----------------| +||Provides semantics for creating names of objects. The service uses the CodeDOM provider's interface to create names that are valid identifiers for the language. In addition, the name creation service supports empty names. Empty names should be interpreted as temporary local variables during serialization.| +||Allows other objects to serialize a group of components into a binary object. This service is most often used by features such as copy and paste or undo and redo. The class provides a designer serialization service that is based on creating CodeDOM trees for objects.| +||This service replaces as a means to serialize components to a binary object.| + + For details on replaceable and non-replaceable services, see . + ]]> The has not been initialized, or the designer loader did not supply a type resolution service, which is required for CodeDom serialization. @@ -278,11 +278,11 @@ if the decides a reload is required; otherwise, . - method checks for the presence of the interface on the . The provider will reparse the CodeDOM tree and pass the resulting parse tree to the method. If this method returns `false`, the designer will not be reloaded. - + method checks for the presence of the interface on the . The provider will reparse the CodeDOM tree and pass the resulting parse tree to the method. If this method returns `false`, the designer will not be reloaded. + ]]> The language did not provide a code parser for this file; this file type may not support a designer. @@ -320,11 +320,11 @@ Notifies the designer loader that loading is about to begin. - method, see . - + method, see . + ]]> @@ -360,11 +360,11 @@ Notifies the designer loader that unloading is about to begin. - method, see . - + method, see . + ]]> @@ -456,11 +456,11 @@ An of objects (usually exceptions) that were reported as errors. Notifies the designer loader that loading is complete. - method, see . - + method, see . + ]]> @@ -497,11 +497,11 @@ Parses the text or other persistent storage and returns a . A resulting from a parse operation. - method is called when the needs to parse the source code. The source code location and format must be specified by deriving classes. - + method is called when the needs to parse the source code. The source code location and format must be specified by deriving classes. + ]]> @@ -542,16 +542,16 @@ The from which to request the serializer. Requests serialization of the root component of the designer. - method obtains the root for the root component of the designer and invokes the serializer to serialize the component. If the result of this operation is a , then integrates the with the existing CodeDOM tree. The result is the original CodeDOM tree with matching members and statements replaced. Finally, calls the abstract method to save this CodeDOM tree. - - If the serialization of the root designer component does not result in a , then does nothing further. - + method obtains the root for the root component of the designer and invokes the serializer to serialize the component. If the result of this operation is a , then integrates the with the existing CodeDOM tree. The result is the original CodeDOM tree with matching members and statements replaced. Finally, calls the abstract method to save this CodeDOM tree. + + If the serialization of the root designer component does not result in a , then does nothing further. + > [!IMPORTANT] -> It is the responsibility of the caller to ensure that a CodeDOM originates from a trusted source. Accepting a CodeDOM object from an untrusted party could allow that party to run malicious code. When flushing a CodeDOM into a file, the framework will run code represented by the CodeDOM object and the serialized content of the object as provided. - +> It is the responsibility of the caller to ensure that a CodeDOM originates from a trusted source. Accepting a CodeDOM object from an untrusted party could allow that party to run malicious code. When flushing a CodeDOM into a file, the framework will run code represented by the CodeDOM object and the serialized content of the object as provided. + ]]> The language did not provide a code parser for this file; this file type may not support a designer. @@ -592,14 +592,14 @@ The from which to request the serializer. Parses code from a CodeDOM provider. - method obtains an from the CodeDOM provider and parses the code. locates the first class in the file, obtains a root for the data type, and then invokes the serializer to deserialize the data type. assumes that this process will create all necessary components in the of the property. Finally, calls the method with the fully qualified name of the type it passed to the CodeDOM serializer. - + method obtains an from the CodeDOM provider and parses the code. locates the first class in the file, obtains a root for the data type, and then invokes the serializer to deserialize the data type. assumes that this process will create all necessary components in the of the property. Finally, calls the method with the fully qualified name of the type it passed to the CodeDOM serializer. + > [!IMPORTANT] -> It is the responsibility of the caller to ensure that a CodeDOM originates from a trusted source. Accepting a CodeDOM object from an untrusted party could allow that party to run malicious code. When loading a CodeDOM into the design surface, the framework will run code represented by the CodeDOM object and the serialized content of the object as provided. - +> It is the responsibility of the caller to ensure that a CodeDOM originates from a trusted source. Accepting a CodeDOM object from an untrusted party could allow that party to run malicious code. When loading a CodeDOM into the design surface, the framework will run code represented by the CodeDOM object and the serialized content of the object as provided. + ]]> The language did not provide a code parser for this file; this file type may not support a designer. @@ -875,11 +875,11 @@ Gets the type resolution service to be used with this designer loader. An that the CodeDOM serializers will use when resolving types. - automatically adds this to the service container when the method is invoked. While the type resolution service is optional in many scenarios, it is required for code interpretation because source code contains type names, but no assembly references. - + automatically adds this to the service container when the method is invoked. While the type resolution service is optional in many scenarios, it is required for code interpretation because source code contains type names, but no assembly references. + ]]> @@ -920,11 +920,11 @@ The to be persisted. Writes compile-unit changes to persistent storage. - method saves a to persistent storage. The deriving class is responsible for invoking the on the appropriate text writer to save the code. The ensures that the CodeDOM objects that are passed to are the same instances of objects that were retrieved from , except in cases where the serialization process had to make changes to the code. This allows an optimized designer loader to store additional data in the property of code elements. This data will be available during the method for any elements that were not replaced by the serialization process. - + method saves a to persistent storage. The deriving class is responsible for invoking the on the appropriate text writer to save the code. The ensures that the CodeDOM objects that are passed to are the same instances of objects that were retrieved from , except in cases where the serialization process had to make changes to the code. This allows an optimized designer loader to store additional data in the property of code elements. This data will be available during the method for any elements that were not replaced by the serialization process. + ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/CodeDomSerializerBase.xml b/xml/System.ComponentModel.Design.Serialization/CodeDomSerializerBase.xml index 7c2f0803414..c5e083cc0df 100644 --- a/xml/System.ComponentModel.Design.Serialization/CodeDomSerializerBase.xml +++ b/xml/System.ComponentModel.Design.Serialization/CodeDomSerializerBase.xml @@ -1539,7 +1539,7 @@ If no expression could be created and no suitable serializer could be found, an error will be reported through the serialization manager. No error will be reported if a serializer was found but it failed to produce an expression. In this case, it is assumed that the serializer either already reported the error or it did not attempt to serialize the object. - If the serializer returned a statement or a collection of statements, those statements will not be discarded. The method will first look for a on the context stack and add statements to the statement context object's property. If there is no statement context, the method will look in the context for a and add the statements there. If no place can be found to add the statements, an error will be generated. + If the serializer returned a statement or a collection of statements, those statements will not be discarded. The method will first look for a on the context stack and add statements to the statement context object's property. If there is no statement context, the method will look in the context for a and add the statements there. If no place can be found to add the statements, an error will be generated. > [!NOTE] > You should not call the method within when serializing your own object. Instead, you should call . If it returns `null`, create your own expression and call . Then proceed with the rest of your serialization. diff --git a/xml/System.ComponentModel.Design.Serialization/ContextStack.xml b/xml/System.ComponentModel.Design.Serialization/ContextStack.xml index 82ed24e8833..4cd3010fd04 100644 --- a/xml/System.ComponentModel.Design.Serialization/ContextStack.xml +++ b/xml/System.ComponentModel.Design.Serialization/ContextStack.xml @@ -52,26 +52,26 @@ Provides a stack object that can be used by a serializer to make information available to nested serializers. - class enables a serializer to set data about the context of an object that is being serialized to a stack where another serializer can access it. The value of the property is provided by an to share information of use to some serializers. - - A context stack is useful because the process of serializing a design document can be deeply nested, and objects at each level of nesting may require context information to correctly persist the state of the object. A serializer can set a context object to the stack before invoking a nested serializer. Each object set to the stack should be removed by the serializer that set it after a call to a nested serializer returns. - - Typically, the objects on the stack contain information about the context of the current object that is being serialized. A parent serializer adds context information to the stack about the next object to be serialized, calls an appropriate serializer and, when the serializer finishes executing on the object, removes the context information from the stack. It is up to the implementation of each serializer to determine what objects get pushed on this stack. - - As an example, an object with a property named `Enabled` has a data type of . If a serializer writes this value to a data stream, it might need to include the context or type of property it is writing. The serializer does not have this information, however, because it is only instructed to write the value. To provide this information to the serializer, the parent serializer can push a that points to the `Enabled` property on the context stack. - - - -## Examples - The following code example demonstrates using a to push and then remove 10 values. - + class enables a serializer to set data about the context of an object that is being serialized to a stack where another serializer can access it. The value of the property is provided by an to share information of use to some serializers. + + A context stack is useful because the process of serializing a design document can be deeply nested, and objects at each level of nesting may require context information to correctly persist the state of the object. A serializer can set a context object to the stack before invoking a nested serializer. Each object set to the stack should be removed by the serializer that set it after a call to a nested serializer returns. + + Typically, the objects on the stack contain information about the context of the current object that is being serialized. A parent serializer adds context information to the stack about the next object to be serialized, calls an appropriate serializer and, when the serializer finishes executing on the object, removes the context information from the stack. It is up to the implementation of each serializer to determine what objects get pushed on this stack. + + As an example, an object with a property named `Enabled` has a data type of . If a serializer writes this value to a data stream, it might need to include the context or type of property it is writing. The serializer does not have this information, however, because it is only instructed to write the value. To provide this information to the serializer, the parent serializer can push a that points to the `Enabled` property on the context stack. + + + +## Examples + The following code example demonstrates using a to push and then remove 10 values. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ContextStackExample/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.vb" id="Snippet1"::: + ]]> @@ -119,15 +119,15 @@ Initializes a new instance of the class. - instance. - + instance. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ContextStackExample/CPP/class1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.vb" id="Snippet2"::: + ]]> @@ -174,11 +174,11 @@ A context object to append to the stack. Appends an object to the end of the stack, rather than pushing it onto the top of the stack. - @@ -226,11 +226,11 @@ Gets the current object on the stack. The current object on the stack, or if no objects were pushed. - @@ -338,11 +338,11 @@ Gets the first object on the stack that inherits from or implements the specified type. The first object on the stack that inherits from or implements the specified type, or if no object on the stack implements the type. - @@ -391,15 +391,15 @@ Removes the current object off of the stack, returning its value. The object removed from the stack; if no objects are on the stack. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ContextStackExample/CPP/class1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.vb" id="Snippet4"::: + ]]> @@ -447,15 +447,15 @@ The context object to push onto the stack. Pushes, or places, the specified object onto the stack. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ContextStackExample/CPP/class1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design.Serialization/ContextStack/Overview/class1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/DesignerSerializationManager.xml b/xml/System.ComponentModel.Design.Serialization/DesignerSerializationManager.xml index ea1e6aa668e..8776c4cf87b 100644 --- a/xml/System.ComponentModel.Design.Serialization/DesignerSerializationManager.xml +++ b/xml/System.ComponentModel.Design.Serialization/DesignerSerializationManager.xml @@ -113,8 +113,8 @@ | event|The event is raised just before a session is disposed. Then, all handlers are detached from this event.| |Name table|The serialization manager maintains a table that maps between objects and their names. Serializers may give objects names for easy identification. This name table is cleared when the session terminates.| |Serializer cache|The serialization manager maintains a cache of serializers it has been asked to supply. This cache is cleared when the session terminates. The public method can safely be called at any time, but its value is cached only if it is called from within a session.| -|Context stack|The serialization manager maintains an object called the context stack, which you can access with the property. Serializers can use this stack to store additional information that is available to other serializers. For example, a serializer that is serializing a property value can push the property name on the serialization stack before asking the value to serialize. This stack is cleared when the session is terminated.| -|Error list|The serialization manager maintains a list of errors that occurred during serialization. This list, which is accessed through the property, is cleared when the session is terminated. Accessing the property between sessions will result in an exception.| +|Context stack|The serialization manager maintains an object called the context stack, which you can access with the property. Serializers can use this stack to store additional information that is available to other serializers. For example, a serializer that is serializing a property value can push the property name on the serialization stack before asking the value to serialize. This stack is cleared when the session is terminated.| +|Error list|The serialization manager maintains a list of errors that occurred during serialization. This list, which is accessed through the property, is cleared when the session is terminated. Accessing the property between sessions will result in an exception.| ]]> @@ -801,7 +801,7 @@ property determines the behavior of the method. If `true`, will pass the given component name. If `false`, will check for the presence of the given name in the container. If the name does not exist in the container, will use the given name. If the name does exist in the container, will pass a null value as the name of a component when adding it to the container, thereby giving it a new name. This second variation is useful for implementing a serializer that always duplicates objects, rather than assuming those objects do not exist. Paste commands often use this type of serializer. + The property determines the behavior of the method. If `true`, will pass the given component name. If `false`, will check for the presence of the given name in the container. If the name does not exist in the container, will use the given name. If the name does exist in the container, will pass a null value as the name of a component when adding it to the container, thereby giving it a new name. This second variation is useful for implementing a serializer that always duplicates objects, rather than assuming those objects do not exist. Paste commands often use this type of serializer. You can only change this property when you are not in a serialization session. @@ -857,7 +857,7 @@ property provides a way to give the serialization manager a set of serialization properties that serializers can use to guide their behavior. + The property provides a way to give the serialization manager a set of serialization properties that serializers can use to guide their behavior. This object's public properties will be inspected and wrapped in new property descriptors that have a target object of the serialization manager. @@ -906,9 +906,9 @@ property is `false`, the method will always create a new instance of a type. If is `true`, will first search the name table and container for an object of the same name. If such an object exists and is of the same type, will return the existing instance. This second variation is useful for implementing a serializer that applies serialization state to an existing set of objects, rather than always creating a new tree. The **Undo** command often uses this type of serializer. + If the property is `false`, the method will always create a new instance of a type. If is `true`, will first search the name table and container for an object of the same name. If such an object exists and is of the same type, will return the existing instance. This second variation is useful for implementing a serializer that applies serialization state to an existing set of objects, rather than always creating a new tree. The **Undo** command often uses this type of serializer. - In the case where the property is `true`, the property will further modify the behavior of depending on the types of the two objects. + In the case where the property is `true`, the property will further modify the behavior of depending on the types of the two objects. ]]> @@ -1739,7 +1739,7 @@ In a related use, this event can be used to remove a temporary service installed property modifies the behavior of the method when the property is `true`, as detailed in the following table. + The property modifies the behavior of the method when the property is `true`, as detailed in the following table. |`RecycleInstances`|`ValidateRecycledTypes`|Behavior of `CreateInstance`| |------------------------|-----------------------------|----------------------------------| diff --git a/xml/System.ComponentModel.Design.Serialization/ExpressionContext.xml b/xml/System.ComponentModel.Design.Serialization/ExpressionContext.xml index 65391220134..5995ec217ec 100644 --- a/xml/System.ComponentModel.Design.Serialization/ExpressionContext.xml +++ b/xml/System.ComponentModel.Design.Serialization/ExpressionContext.xml @@ -44,23 +44,23 @@ Provides a means of passing context state among serializers. This class cannot be inherited. - is placed on the context stack and contains the most relevant expression during serialization. The following C# code demonstrates an assignment. - -```csharp -button1.Text = "Hello"; -``` - - During serialization, several serializers are responsible for creating this single statement. One of those serializers is responsible for creating "Hello". There are times when that serializer may need to know the context in which it is creating its expression. In the previous example, this context is not needed. The following C# code shows a situation in which knowledge of the context is necessary. - -```csharp -button1.Text = rm.GetString("button1_Text"); -``` - - In this case, the serializer responsible for creating the resource expression needs to be informed of the names of the target objects. The class can be used for this. As each serializer creates an expression and invokes a serializer to handle a smaller part of the statement as a whole, the serializer pushes an expression context on the context stack. Each expression context has a parent property that locates the next expression context on the stack. This provides a convenient traversal capability. - + is placed on the context stack and contains the most relevant expression during serialization. The following C# code demonstrates an assignment. + +```csharp +button1.Text = "Hello"; +``` + + During serialization, several serializers are responsible for creating this single statement. One of those serializers is responsible for creating "Hello". There are times when that serializer may need to know the context in which it is creating its expression. In the previous example, this context is not needed. The following C# code shows a situation in which knowledge of the context is necessary. + +```csharp +button1.Text = rm.GetString("button1_Text"); +``` + + In this case, the serializer responsible for creating the resource expression needs to be informed of the names of the target objects. The class can be used for this. As each serializer creates an expression and invokes a serializer to handle a smaller part of the statement as a whole, the serializer pushes an expression context on the context stack. Each expression context has a parent property that locates the next expression context on the stack. This provides a convenient traversal capability. + ]]> @@ -252,11 +252,11 @@ button1.Text = rm.GetString("button1_Text"); Gets the of the expression. The of the expression. - to determine if a cast is needed when assigning to the expression. - + to determine if a cast is needed when assigning to the expression. + ]]> @@ -300,11 +300,11 @@ button1.Text = rm.GetString("button1_Text"); Gets the object owning this expression. The object owning this expression. - property of an instance of called `button1`, returns `button1`. - + property of an instance of called `button1`, returns `button1`. + ]]> @@ -353,23 +353,23 @@ button1.Text = rm.GetString("button1_Text"); Gets the preset value of an expression. The preset value of this expression, or if not assigned. - property of a , the property contains the instance of the property. This is because the property is read-only and preset by the object to contain a value. On the other hand, a property such as or does not have a preset value and therefore the property returns `null`. - - The following C# code shows how serializers can use this information to guide serialization. - -```csharp -Padding p = new Padding(); -p.Left = 5; -button1.Padding = p; - -button1.Padding.Left = 5; -``` - - The serializer of the structure needs to be informed if it should generate the first or second form. The first form is generated by default. The second form is only generated if there is an on the context stack that contains a equal to the value of the currently being serialized. - + property of a , the property contains the instance of the property. This is because the property is read-only and preset by the object to contain a value. On the other hand, a property such as or does not have a preset value and therefore the property returns `null`. + + The following C# code shows how serializers can use this information to guide serialization. + +```csharp +Padding p = new Padding(); +p.Left = 5; +button1.Padding = p; + +button1.Padding.Left = 5; +``` + + The serializer of the structure needs to be informed if it should generate the first or second form. The first form is generated by default. The second form is only generated if there is an on the context stack that contains a equal to the value of the currently being serialized. + ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/IDesignerLoaderHost2.xml b/xml/System.ComponentModel.Design.Serialization/IDesignerLoaderHost2.xml index fb10c7f0ba5..665c9c4b38f 100644 --- a/xml/System.ComponentModel.Design.Serialization/IDesignerLoaderHost2.xml +++ b/xml/System.ComponentModel.Design.Serialization/IDesignerLoaderHost2.xml @@ -60,11 +60,11 @@ Provides an interface that extends to specify whether errors are tolerated while loading a design document. - interface to specify whether the designer loader can continue loading when errors occur during deserialization. - + interface to specify whether the designer loader can continue loading when errors occur during deserialization. + ]]> @@ -113,11 +113,11 @@ if the designer loader can reload the design document when errors are detected; otherwise, . The default is . - @@ -166,11 +166,11 @@ if the designer loader will ignore errors when it reloads; otherwise, . The default is . - property can only be set to `true` if is `true`. If is `false`, the value of is ignored. - + property can only be set to `true` if is `true`. If is `false`, the value of is ignored. + ]]> diff --git a/xml/System.ComponentModel.Design.Serialization/InstanceDescriptor.xml b/xml/System.ComponentModel.Design.Serialization/InstanceDescriptor.xml index d750f0e73ee..48716cf63b0 100644 --- a/xml/System.ComponentModel.Design.Serialization/InstanceDescriptor.xml +++ b/xml/System.ComponentModel.Design.Serialization/InstanceDescriptor.xml @@ -61,11 +61,11 @@ An provides the following members: -- A property that describes this object. +- A property that describes this object. -- An property that consists of the constructor arguments that can be used to instantiate this object. +- An property that consists of the constructor arguments that can be used to instantiate this object. -- A Boolean property that indicates whether the object is completely represented by the current information. +- A Boolean property that indicates whether the object is completely represented by the current information. - An method that can be used to create an instance of the represented object. @@ -317,7 +317,7 @@ property, using the specified arguments to create that particular type of instance. + This method creates a new instance of the object indicated by the property, using the specified arguments to create that particular type of instance. ]]> diff --git a/xml/System.ComponentModel.Design/CollectionEditor.xml b/xml/System.ComponentModel.Design/CollectionEditor.xml index ed67aaafcba..650260f61f0 100644 --- a/xml/System.ComponentModel.Design/CollectionEditor.xml +++ b/xml/System.ComponentModel.Design/CollectionEditor.xml @@ -473,7 +473,7 @@ property, which is faster than this method. + You can retrieve the data type of the items of the collection from the property, which is faster than this method. This method does not need to be called by users, except in derived classes where this method has been overridden and implemented. @@ -569,7 +569,7 @@ property, which is faster than this method. + You can retrieve the data type of the items of the collection from the property, which is faster than this method. This method does not need to be called by users, except in derived classes where this method has been overridden and implemented. diff --git a/xml/System.ComponentModel.Design/ComponentActionsType.xml b/xml/System.ComponentModel.Design/ComponentActionsType.xml index f0dd8e8312c..48517d4c51e 100644 --- a/xml/System.ComponentModel.Design/ComponentActionsType.xml +++ b/xml/System.ComponentModel.Design/ComponentActionsType.xml @@ -16,18 +16,18 @@ Specifies the type of object-bound smart tag with respect to how it was associated with the component. - that is associated with the component overrides the property to return the collection of smart tags for that component.| -|Push|A call to the method explicitly associates the specified smart tags with the specified component.| - - For more information about these smart-tag models, see the and classes. - + that is associated with the component overrides the property to return the collection of smart tags for that component.| +|Push|A call to the method explicitly associates the specified smart tags with the specified component.| + + For more information about these smart-tag models, see the and classes. + ]]> diff --git a/xml/System.ComponentModel.Design/ComponentChangedEventArgs.xml b/xml/System.ComponentModel.Design/ComponentChangedEventArgs.xml index 45418986428..c7adae6d2a8 100644 --- a/xml/System.ComponentModel.Design/ComponentChangedEventArgs.xml +++ b/xml/System.ComponentModel.Design/ComponentChangedEventArgs.xml @@ -63,13 +63,13 @@ A provides the following information: -- A property that indicates the component that was modified. +- A property that indicates the component that was modified. -- A property that indicates the member that was changed. +- A property that indicates the member that was changed. -- A property that indicates the new value of the member. +- A property that indicates the new value of the member. -- An property that indicates the old value of the member. +- An property that indicates the old value of the member. Component designers typically raise the event automatically when components are added, removed, or modified. A event is not raised during form load and unload because changes at this time are expected. A component designer might raise the event after it changes a property of the component; this ensures that the Properties window will display the updated property. diff --git a/xml/System.ComponentModel.Design/ComponentDesigner.xml b/xml/System.ComponentModel.Design/ComponentDesigner.xml index 27fd5622c19..a1cae788656 100644 --- a/xml/System.ComponentModel.Design/ComponentDesigner.xml +++ b/xml/System.ComponentModel.Design/ComponentDesigner.xml @@ -77,7 +77,7 @@ The class implements a special behavior for the property descriptors of inherited components. An internal type named `InheritedPropertyDescriptor` is used by the default implementation to stand in for properties that are inherited from a base class. There are two cases in which these property descriptors are added. -1. To the root object itself, which is returned by the property, because you are inheriting from its base class. +1. To the root object itself, which is returned by the property, because you are inheriting from its base class. 2. To fields found in the base class of the root object. Public and protected fields from the base class are added to the designer so that they can be manipulated by the user. @@ -86,7 +86,7 @@ ## Examples - The following code example provides an example implementation and an example component associated with the designer. The designer implements an override of the method that calls the base `Initialize` method, an override of the method that displays a when the component is double-clicked, and an override of the property accessor that supplies a custom menu command to the shortcut menu for the component. + The following code example provides an example implementation and an example component associated with the designer. The designer implements an override of the method that calls the base `Initialize` method, an override of the method that displays a when the component is double-clicked, and an override of the property accessor that supplies a custom menu command to the shortcut menu for the component. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ComponentDesignerExample/CPP/examplecomponent.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/ComponentDesigner/Overview/examplecomponent.cs" id="Snippet1"::: @@ -998,7 +998,7 @@ ## Remarks This method provides a way to change or remove the items within the dictionary of attributes that are exposed through a . - The keys in the dictionary of attributes are the type identifiers of the attributes, as specified by the value of their property. The objects are of type . This method is called immediately after the method. + The keys in the dictionary of attributes are the type identifiers of the attributes, as specified by the value of their property. The objects are of type . This method is called immediately after the method. ]]> @@ -1152,7 +1152,7 @@ ## Remarks This method provides a way to add items to the dictionary of attributes that a designer exposes through a . - The keys in the dictionary of attributes are the type identifiers of the attributes, as specified by the value of their property. The objects are of type . This method is called immediately before the method. + The keys in the dictionary of attributes are the type identifiers of the attributes, as specified by the value of their property. The objects are of type . This method is called immediately before the method. ]]> diff --git a/xml/System.ComponentModel.Design/ComponentRenameEventArgs.xml b/xml/System.ComponentModel.Design/ComponentRenameEventArgs.xml index 81b90b4ed33..82d0f422edf 100644 --- a/xml/System.ComponentModel.Design/ComponentRenameEventArgs.xml +++ b/xml/System.ComponentModel.Design/ComponentRenameEventArgs.xml @@ -63,11 +63,11 @@ A object provides the following information: -- A property that references the component being renamed. +- A property that references the component being renamed. -- An property that indicates the old name of the component. +- An property that indicates the old name of the component. -- A property that indicates the new name of the component. +- A property that indicates the new name of the component. diff --git a/xml/System.ComponentModel.Design/DesignSurface.xml b/xml/System.ComponentModel.Design/DesignSurface.xml index 4ead4920fda..f779b5fc2d7 100644 --- a/xml/System.ComponentModel.Design/DesignSurface.xml +++ b/xml/System.ComponentModel.Design/DesignSurface.xml @@ -64,7 +64,7 @@ The class can be used by itself, or the user can derive a new class from it and augment the behavior. - The class provides several design-time services automatically. The class adds all of its services in its constructor. Most of these services can be overridden by replacing them in the protected property. To replace a service, override the constructor, call base, and make any changes through the protected property. All services that are added to the service container and that implement are disposed when the design surface is disposed. The default set of replaceable services that the class provides is shown in the following table. + The class provides several design-time services automatically. The class adds all of its services in its constructor. Most of these services can be overridden by replacing them in the protected property. To replace a service, override the constructor, call base, and make any changes through the protected property. All services that are added to the service container and that implement are disposed when the design surface is disposed. The default set of replaceable services that the class provides is shown in the following table. |Service|Description| |-------------|-----------------| @@ -447,7 +447,7 @@ property holds all objects that are currently in design mode. When components are added to , their designer, if any, is loaded. The component is sited with a site that provides full access to the design surface. + The property holds all objects that are currently in design mode. When components are added to , their designer, if any, is loaded. The component is sited with a site that provides full access to the design surface. ]]> @@ -1590,7 +1590,7 @@ ## Remarks The method must be called beforehand to start the loading process. It is possible to return a view before the designer loader finishes loading because the root designer, which supplies the view, is the first object created by the designer loader. If a view is unavailable, raises an exception. - The notion of a view technology is obsolete. But, it remains in the interfaces for root designers for backward compatibility. Its use is hidden from anyone using objects. The property hides view technologies by passing the supported technologies back into the root designer. + The notion of a view technology is obsolete. But, it remains in the interfaces for root designers for backward compatibility. Its use is hidden from anyone using objects. The property hides view technologies by passing the supported technologies back into the root designer. diff --git a/xml/System.ComponentModel.Design/DesignSurfaceManager.xml b/xml/System.ComponentModel.Design/DesignSurfaceManager.xml index 86d4c2d0703..7ce5c8b64ba 100644 --- a/xml/System.ComponentModel.Design/DesignSurfaceManager.xml +++ b/xml/System.ComponentModel.Design/DesignSurfaceManager.xml @@ -59,7 +59,7 @@ ## Remarks The class is designed to be a container of objects. It provides common services that handle event routing between designers, property windows, and other global objects. Using is optional, but it is recommended if you intend to have several designer windows. - The class provides several design-time services automatically. You can override each of these services by replacing them in the protected property. To replace a service, override the constructor, call base, and make any changes through the protected property. All services added to the service container that implement the interface are disposed when the design surface manager is disposed. The class provides the interface as the default service. provides a global eventing mechanism for designer events. With this mechanism, an application is informed when a designer becomes active. The service provides a collection of designers and a single place where global objects, such as the Properties window, can monitor selection change events. + The class provides several design-time services automatically. You can override each of these services by replacing them in the protected property. To replace a service, override the constructor, call base, and make any changes through the protected property. All services added to the service container that implement the interface are disposed when the design surface manager is disposed. The class provides the interface as the default service. provides a global eventing mechanism for designer events. With this mechanism, an application is informed when a designer becomes active. The service provides a collection of designers and a single place where global objects, such as the Properties window, can monitor selection change events. ]]> @@ -186,7 +186,7 @@ property should be set by the designer's user interface whenever a designer becomes the active window. The default implementation of this property works with the default implementation of the interface to notify interested parties that a new designer is now active. If you provide your own implementation of , you should override this property to notify your service appropriately. This property can be set to `null`, indicating that no designer is active. + The property should be set by the designer's user interface whenever a designer becomes the active window. The default implementation of this property works with the default implementation of the interface to notify interested parties that a new designer is now active. If you provide your own implementation of , you should override this property to notify your service appropriately. This property can be set to `null`, indicating that no designer is active. ]]> @@ -475,7 +475,7 @@ property is implemented directly on top of , so if you provide your own implementation of that service, this property uses your implementation. + The property is implemented directly on top of , so if you provide your own implementation of that service, this property uses your implementation. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionHeaderItem.xml b/xml/System.ComponentModel.Design/DesignerActionHeaderItem.xml index a16ff37dbf5..7acef618df4 100644 --- a/xml/System.ComponentModel.Design/DesignerActionHeaderItem.xml +++ b/xml/System.ComponentModel.Design/DesignerActionHeaderItem.xml @@ -116,7 +116,7 @@ and the properties to the value of the `displayName` parameter and sets the property to `null`. + This constructor sets both the and the properties to the value of the `displayName` parameter and sets the property to `null`. @@ -179,7 +179,7 @@ property to `null`. The property is case-sensitive. + This constructor sets the property to `null`. The property is case-sensitive. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionItem.xml b/xml/System.ComponentModel.Design/DesignerActionItem.xml index 6e2f04a0669..6a7398202e8 100644 --- a/xml/System.ComponentModel.Design/DesignerActionItem.xml +++ b/xml/System.ComponentModel.Design/DesignerActionItem.xml @@ -168,9 +168,9 @@ objects may be combined to form a single smart tag panel, the property indicates whether the current item can be rearranged by category. + Because multiple objects may be combined to form a single smart tag panel, the property indicates whether the current item can be rearranged by category. - The property is used in conjunction with the property on the and types. + The property is used in conjunction with the property on the and types. For example, ASP.NET uses a data-bound control like to connect to a data source control like . Both have a with its own set of objects. The control has items like , `Edit Fields`, and `AutoFormat`. The class has `Configure` and `Refresh Items`, which have set to `true`. @@ -285,7 +285,7 @@ property is used whenever a plain text description of the item is required (for example, in ToolTips and the status bar). + The property is used whenever a plain text description of the item is required (for example, in ToolTips and the status bar). The value of this property is set in the constructor for this class. @@ -337,7 +337,7 @@ property is set in the constructor for this class. + The value of the property is set in the constructor for this class. ]]> @@ -386,7 +386,7 @@ property allows the programmer to store arbitrary data within an item. The standard properties for this class, such as and , are not stored in this collection. + The property allows the programmer to store arbitrary data within an item. The standard properties for this class, such as and , are not stored in this collection. The type of this property is actually . diff --git a/xml/System.ComponentModel.Design/DesignerActionList.xml b/xml/System.ComponentModel.Design/DesignerActionList.xml index 83de08b853a..3f398c72ece 100644 --- a/xml/System.ComponentModel.Design/DesignerActionList.xml +++ b/xml/System.ComponentModel.Design/DesignerActionList.xml @@ -120,7 +120,7 @@ constructor sets the property to `false`. + The constructor sets the property to `false`. @@ -179,7 +179,7 @@ ## Remarks If the property value is set to `true`, the component with which this is associated will automatically expand and display the smart tag panel when the component is created. - You can opt out of this behavior by setting the property to `false`. + You can opt out of this behavior by setting the property to `false`. @@ -328,13 +328,13 @@ Property items have a special panel-item interface that enables display and manipulation of their corresponding property values. For more information, see the class. - The order of the items in the returned array reflects the order that they will appear in the panel. The items are grouped according to the property, using the following rules: + The order of the items in the returned array reflects the order that they will appear in the panel. The items are grouped according to the property, using the following rules: - The category of the first item encountered signifies the start of the first group. That group continues as long as each succeeding item is of the same category. When an item of a different, new category is encountered, a new group is created and the item is placed in it. - If an item has a type different than the current group, but that category has already been used, the item is placed in the matching existing category. -- If an item does not have a category, it is placed in a miscellaneous group at the end of the panel. This group also contains items whose property is set to `false`. +- If an item does not have a category, it is placed in a miscellaneous group at the end of the panel. This group also contains items whose property is set to `false`. The method is called when the panel is first created. You must call the method to update the list of items displayed in the panel. diff --git a/xml/System.ComponentModel.Design/DesignerActionListCollection.xml b/xml/System.ComponentModel.Design/DesignerActionListCollection.xml index daaeab84dc8..1227d3b6f5a 100644 --- a/xml/System.ComponentModel.Design/DesignerActionListCollection.xml +++ b/xml/System.ComponentModel.Design/DesignerActionListCollection.xml @@ -61,7 +61,7 @@ |Technique|Description| |---------------|-----------------| -|Pull model|The designer for the component class, which is derived from the class, supplies this collection through the property. The designer infrastructure reads this property when it must display the panel.| +|Pull model|The designer for the component class, which is derived from the class, supplies this collection through the property. The designer infrastructure reads this property when it must display the panel.| |Push model|A or is supplied as a parameter in a call to the method of the associated with the component.| The designer infrastructure constructs a panel by creating a smart tag panel, whose constructor takes two parameters of type . The collections of lists, which contain the pulled and pushed items, are merged into one panel. @@ -574,7 +574,7 @@ property, the new element is added to the end of the collection. + If the `index` parameter is equal to the value of the property, the new element is added to the end of the collection. Internally, the class uses a to contain its collection of objects. Because lists maintain contiguous elements, the elements that follow the insertion point move down to accommodate the new element. This rearrangement changes the index of the elements after the insertion point. diff --git a/xml/System.ComponentModel.Design/DesignerActionListsChangedEventArgs.xml b/xml/System.ComponentModel.Design/DesignerActionListsChangedEventArgs.xml index e78cd67ffb3..72fb0459a6a 100644 --- a/xml/System.ComponentModel.Design/DesignerActionListsChangedEventArgs.xml +++ b/xml/System.ComponentModel.Design/DesignerActionListsChangedEventArgs.xml @@ -255,9 +255,9 @@ property enables the programmer to associate an object to an instance of the class. + The property enables the programmer to associate an object to an instance of the class. - For the event, the property should always reference the that the is associated with. + For the event, the property should always reference the that the is associated with. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionMethodItem.xml b/xml/System.ComponentModel.Design/DesignerActionMethodItem.xml index e6589645c76..3e12f494d48 100644 --- a/xml/System.ComponentModel.Design/DesignerActionMethodItem.xml +++ b/xml/System.ComponentModel.Design/DesignerActionMethodItem.xml @@ -47,7 +47,7 @@ class represents individual items in a smart tag panel. An item of this type is displayed as an active user interface element, such as a hyperlink, that invokes a programmer-supplied method in a class derived from . The association between the item and the method is maintained through the value of the property. The method that this item invokes must neither take parameters nor return a value. + The class represents individual items in a smart tag panel. An item of this type is displayed as an active user interface element, such as a hyperlink, that invokes a programmer-supplied method in a class derived from . The association between the item and the method is maintained through the value of the property. The method that this item invokes must neither take parameters nor return a value. Individual panel items are associated together to form a panel by a call to the method of the class. @@ -123,7 +123,7 @@ constructor sets the and properties to `null`, and the property to `false`. + The constructor sets the and properties to `null`, and the property to `false`. ]]> @@ -239,7 +239,7 @@ constructor sets the property to `null` and the property to `false`. + The constructor sets the property to `null` and the property to `false`. For more information about how the `category` parameter is used to group items on a panel, see the method. @@ -302,7 +302,7 @@ ## Remarks If the `includeAsDesignerVerb` parameter is set to `true`, then the item is also considered a ; therefore, it will be added to the component's design-time shortcut menu. A list of designer verbs can be accessed through the designer's collection property. - The constructor sets the property to `null`. + The constructor sets the property to `null`. For more information on how the `category` parameter is used to group items on a panel, see the method. @@ -363,7 +363,7 @@ constructor sets the property to `false`. + The constructor sets the property to `false`. For more information on how the `category` parameter is used to group items on a panel, see the method. @@ -489,9 +489,9 @@ property is set to `true`, then the item is also considered a ; therefore, it will be added to the component's design-time shortcut menu. A list of designer verbs can be accessed through the designer's collection property. + If the property is set to `true`, then the item is also considered a ; therefore, it will be added to the component's design-time shortcut menu. A list of designer verbs can be accessed through the designer's collection property. - The value of the property is set in the constructor for this class. + The value of the property is set in the constructor for this class. ]]> @@ -535,7 +535,7 @@ property is initialized to `true`, the associated method can also be invoked through the corresponding designer verb event. + If the property is initialized to `true`, the associated method can also be invoked through the corresponding designer verb event. ]]> @@ -585,7 +585,7 @@ property specifies which property, in the class derived from the class, that the item should be bound to. When the programmer interacts with the panel item through the user interface (UI), this associated property will be set. + The property specifies which property, in the class derived from the class, that the item should be bound to. When the programmer interacts with the panel item through the user interface (UI), this associated property will be set. The bound method should neither take parameters nor return a value. @@ -643,9 +643,9 @@ property allows another component to lend its smart tag panel items to the current list. For example, a user control might aggregate the items from one of its constituent standard controls. + The property allows another component to lend its smart tag panel items to the current list. For example, a user control might aggregate the items from one of its constituent standard controls. - This property works in conjunction with the property. + This property works in conjunction with the property. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionPropertyItem.xml b/xml/System.ComponentModel.Design/DesignerActionPropertyItem.xml index a1e2ff0bea4..bec41086097 100644 --- a/xml/System.ComponentModel.Design/DesignerActionPropertyItem.xml +++ b/xml/System.ComponentModel.Design/DesignerActionPropertyItem.xml @@ -47,7 +47,7 @@ class represents individual items in a smart tag panel. Each item is typically associated with a property in a class that is derived from the class and supplied by the component author. The association is maintained through the name of the property, as stored in the property. + The class represents individual items in a smart tag panel. Each item is typically associated with a property in a class that is derived from the class and supplied by the component author. The association is maintained through the name of the property, as stored in the property. Individual panel items are associated together to form a panel by a call to the method of the class. @@ -199,7 +199,7 @@ constructor sets the property to `null`. + The constructor sets the property to `null`. For more information about how the `category` parameter is used to group items on a panel, see the method. @@ -329,7 +329,7 @@ property specifies which property - in the class derived from the class - the item should be bound to. When the programmer interacts with the panel item through the user interface (UI), this associated property will be set. + The property specifies which property - in the class derived from the class - the item should be bound to. When the programmer interacts with the panel item through the user interface (UI), this associated property will be set. is set in the constructor. Its value is case-sensitive. @@ -385,9 +385,9 @@ property, another component can lend its pull-model panel items to the current list. For example, a user control might aggregate the objects from one or more of its constituent controls. + With the property, another component can lend its pull-model panel items to the current list. For example, a user control might aggregate the objects from one or more of its constituent controls. - This property works in conjunction with the property. + This property works in conjunction with the property. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionService.xml b/xml/System.ComponentModel.Design/DesignerActionService.xml index 86858c950d1..a532c5f6932 100644 --- a/xml/System.ComponentModel.Design/DesignerActionService.xml +++ b/xml/System.ComponentModel.Design/DesignerActionService.xml @@ -69,7 +69,7 @@ - The method allows adding a or to the set of existing items for a component instance. In contrast, the method removes one or all of the item lists associated with a component. > [!NOTE] - > The method represents the direct push model of associating panel items with a component. In contrast, the pull model relies on overriding the property of the designer class for that component. The design environment is responsible for adding these items into the current when a component is created on the design surface. + > The method represents the direct push model of associating panel items with a component. In contrast, the pull model relies on overriding the property of the designer class for that component. The design environment is responsible for adding these items into the current when a component is created on the design surface. > [!IMPORTANT] > The , , , and methods only consider or affect push-model items. @@ -78,7 +78,7 @@ Because it is often desirable to use some of the same panel items in both the component's design-time shortcut menu and its panel, a large degree of interoperability exists between objects and designer verbs. - If a component designer does not explicitly specify a (that is, it does not contain an overridden property), then a list will be created from existing designer verbs. These verbs are specified by the property. In this case, an internal verb list class is used to contain the collection of verb item panel entries. + If a component designer does not explicitly specify a (that is, it does not contain an overridden property), then a list will be created from existing designer verbs. These verbs are specified by the property. In this case, an internal verb list class is used to contain the collection of verb item panel entries. If you want a to be used both as a panel entry and a design-time shortcut menu entry, then you can set the `includeAsDesignerVerb` parameter in the item's constructor. @@ -189,9 +189,9 @@ method represents the push model of adding smart tag items. The alternate pull model relies on overriding the property in the designer for the corresponding component. + The method represents the push model of adding smart tag items. The alternate pull model relies on overriding the property in the designer for the corresponding component. - When this method is called, the lists to be added are scanned for any with the property set to `true`. These items are added to the list of designer verbs for this component, through a call to the method. + When this method is called, the lists to be added are scanned for any with the property set to `true`. These items are added to the list of designer verbs for this component, through a call to the method. Smart tags are managed on a component instance basis. The managed collection may contain duplicate entries. @@ -246,9 +246,9 @@ method represents the push model of adding smart tag items. The alternate pull model relies on overriding the property in the designer for the corresponding component. + The method represents the push model of adding smart tag items. The alternate pull model relies on overriding the property in the designer for the corresponding component. - When this method is called, the lists to be added are scanned for any with the property set to `true`. These items are added to the list of designer verbs for this component, through a call to the method. + When this method is called, the lists to be added are scanned for any with the property set to `true`. These items are added to the list of designer verbs for this component, through a call to the method. Smart tags are managed on a component instance basis. The managed collection may contain duplicate entries. @@ -663,7 +663,7 @@ ||Pull-model smart tags only.| ||Push-model smart tags only.| - If the associated designer for a component does not supply a pull-model smart tag list, then the method will instead use the designer's design-time shortcut menu items from the property. + If the associated designer for a component does not supply a pull-model smart tag list, then the method will instead use the designer's design-time shortcut menu items from the property. ]]> @@ -723,7 +723,7 @@ ||Pull-model designer actions only.| ||Push-model designer actions only.| - If the associated designer for a component does not supply a pull-model designer action list, then the method will instead use the designer's design-time shortcut menu items from the property. + If the associated designer for a component does not supply a pull-model designer action list, then the method will instead use the designer's design-time shortcut menu items from the property. ]]> @@ -772,7 +772,7 @@ ## Remarks The method is a helper method for the methods. searches for pull-model smart tags of type , and then adds these to the supplied `actionLists` collection. - If the component's developer does not explicitly supply a collection of smart tags through the property of its designer, this method will reuse the design-time shortcut menu entries, which are obtained through the property of the designer. + If the component's developer does not explicitly supply a collection of smart tags through the property of its designer, this method will reuse the design-time shortcut menu entries, which are obtained through the property of the designer. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerActionTextItem.xml b/xml/System.ComponentModel.Design/DesignerActionTextItem.xml index e542df73358..fc7d30273cd 100644 --- a/xml/System.ComponentModel.Design/DesignerActionTextItem.xml +++ b/xml/System.ComponentModel.Design/DesignerActionTextItem.xml @@ -99,7 +99,7 @@ constructor sets the property to `null`. + The constructor sets the property to `null`. For more information about how the `category` parameter is used to group items on a panel, see the method. diff --git a/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventArgs.xml b/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventArgs.xml index b8729708af1..f101d141ff7 100644 --- a/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventArgs.xml +++ b/xml/System.ComponentModel.Design/DesignerActionUIStateChangeEventArgs.xml @@ -203,7 +203,7 @@ property enables the programmer to associate an object to an instance of the class. This object then is available to methods that handle the event. + The property enables the programmer to associate an object to an instance of the class. This object then is available to methods that handle the event. ]]> diff --git a/xml/System.ComponentModel.Design/DesignerCommandSet.xml b/xml/System.ComponentModel.Design/DesignerCommandSet.xml index ef39236bd41..31767e26c81 100644 --- a/xml/System.ComponentModel.Design/DesignerCommandSet.xml +++ b/xml/System.ComponentModel.Design/DesignerCommandSet.xml @@ -44,21 +44,21 @@ Represents a base class for design-time tools, not derived from , that provide smart tag or designer verb capabilities. - class provides the and properties to query for the and collections, respectively. However, if a design-time tool author decides not to derive from this class, the class represents an alternative base class to provide this functionality. - - The class contains only three members, described in the following table. - -|Public member|Description| -|-------------------|-----------------| -||Returns the collection of either the smart tags or designer verbs associated with the designed component. The base implementation returns `null`.| -||Gets the collection of all the smart tags associated with the designed component. The base implementation simply calls .| -||Gets the collection of all the designer verbs associated with the designed component. The base implementation simply calls .| - - A should be added as a site-specific service. Externally, a service of this type should first be queried to discover smart tag and designer verb functionality. If this service is not found, then the property should be used instead. This procedure provides a path for backwards compatibility. - + class provides the and properties to query for the and collections, respectively. However, if a design-time tool author decides not to derive from this class, the class represents an alternative base class to provide this functionality. + + The class contains only three members, described in the following table. + +|Public member|Description| +|-------------------|-----------------| +||Returns the collection of either the smart tags or designer verbs associated with the designed component. The base implementation returns `null`.| +||Gets the collection of all the smart tags associated with the designed component. The base implementation simply calls .| +||Gets the collection of all the designer verbs associated with the designed component. The base implementation simply calls .| + + A should be added as a site-specific service. Externally, a service of this type should first be queried to discover smart tag and designer verb functionality. If this service is not found, then the property should be used instead. This procedure provides a path for backwards compatibility. + ]]> @@ -99,11 +99,11 @@ Initializes an instance of the class. - @@ -140,11 +140,11 @@ Gets the collection of all the smart tags associated with the designed component. A that contains the smart tags for the associated designed component. - with the string parameter "ActionLists". - + with the string parameter "ActionLists". + ]]> @@ -188,16 +188,16 @@ Returns a collection of command objects. A collection that contains the specified type - either or - of command objects. The base implementation always returns . - and properties specify the following values and meanings for this parameter. - -|String|Meaning| -|------------|-------------| -|"ActionLists"|Return a collection of all the smart tags associated with the component.| -|"Verbs"|Return a collection of all the designer verbs associated with the component.| - + and properties specify the following values and meanings for this parameter. + +|String|Meaning| +|------------|-------------| +|"ActionLists"|Return a collection of all the smart tags associated with the component.| +|"Verbs"|Return a collection of all the designer verbs associated with the component.| + ]]> @@ -238,11 +238,11 @@ Gets the collection of all the designer verbs associated with the designed component. A that contains the designer verbs for the associated designed component. - with the string parameter "Verbs". - + with the string parameter "Verbs". + ]]> diff --git a/xml/System.ComponentModel.Design/DesignerOptionService.xml b/xml/System.ComponentModel.Design/DesignerOptionService.xml index 70747a06179..21b665527e5 100644 --- a/xml/System.ComponentModel.Design/DesignerOptionService.xml +++ b/xml/System.ComponentModel.Design/DesignerOptionService.xml @@ -55,37 +55,37 @@ Provides a base class for getting and setting option values for a designer. - class provides a collection of options. Each of these option collections has an indexer that enables it to be further filtered. Each option collection contains its own set of options, as well as a rollup of all of its child options. In the event of a naming conflict between properties, the outermost options object takes precedence. The following **Tools | Options** user interface (UI) structure shows how the outermost options object takes on greater importance: - - **WindowsFormsDesigner | General** - -- **SnapToGrid** - -- **ShowGrid** - -- **GridSize** - - Given a named `service`, to get to the value of the property, you would make the following call: - + class provides a collection of options. Each of these option collections has an indexer that enables it to be further filtered. Each option collection contains its own set of options, as well as a rollup of all of its child options. In the event of a naming conflict between properties, the outermost options object takes precedence. The following **Tools | Options** user interface (UI) structure shows how the outermost options object takes on greater importance: + + **WindowsFormsDesigner | General** + +- **SnapToGrid** + +- **ShowGrid** + +- **GridSize** + + Given a named `service`, to get to the value of the property, you would make the following call: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/IDesignerOptionServiceExample/CPP/idesigneroptionservicecontrol.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/DesignerOptionService/Overview/idesigneroptionservicecontrol.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/DesignerOptionService/Overview/idesigneroptionservicecontrol.vb" id="Snippet2"::: - - This works, until you want to move to another page. Also, provides no discovery mechanism. If you do not know what string to pass in, the service cannot find the property value. - - The class addresses these issues. You can query collections, and there is a type converter defined on the object that marks the collection as expandable. With this type converter, you can pass the entire designer option service to a property window and visually inspect the service. - - - -## Examples - The following code example demonstrates accessing the to display the current values of the standard options. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/DesignerOptionService/Overview/idesigneroptionservicecontrol.vb" id="Snippet2"::: + + This works, until you want to move to another page. Also, provides no discovery mechanism. If you do not know what string to pass in, the service cannot find the property value. + + The class addresses these issues. You can query collections, and there is a type converter defined on the object that marks the collection as expandable. With this type converter, you can pass the entire designer option service to a property window and visually inspect the service. + + + +## Examples + The following code example demonstrates accessing the to display the current values of the standard options. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/DesignerOptionService/Overview/designeroptionservicecontrol.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/DesignerOptionService/Overview/designeroptionservicecontrol.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/DesignerOptionService/Overview/designeroptionservicecontrol.vb" id="Snippet1"::: + ]]> @@ -182,11 +182,11 @@ Creates a new with the given name and adds it to the given parent. A new with the given name. - collection of the option collection. The `value` parameter can be `null` if this options collection does not offer any properties. Properties are wrapped in such a way that passing anything into the component parameter of the is ignored, and the `value` object is substituted. - + collection of the option collection. The `value` parameter can be `null` if this options collection does not offer any properties. Properties are wrapped in such a way that passing anything into the component parameter of the is ignored, and the `value` object is substituted. + ]]> @@ -236,19 +236,19 @@ Gets the options collection for this service. A populated with available designer options. - @@ -297,13 +297,13 @@ The collection to populate. Populates a . - method is called on demand the first time a user asks for child options or properties of an options collection. - - You can populate the `options` collection by calling the method and passing this collection as the parent. - + method is called on demand the first time a user asks for child options or properties of an options collection. + + You can populate the `options` collection by calling the method and passing this collection as the parent. + ]]> @@ -356,11 +356,11 @@ if the dialog box is shown; otherwise, . - method must be implemented for the `optionObject` parameter's options dialog box to be shown. - + method must be implemented for the `optionObject` parameter's options dialog box to be shown. + ]]> diff --git a/xml/System.ComponentModel.Design/DesignerTransactionCloseEventArgs.xml b/xml/System.ComponentModel.Design/DesignerTransactionCloseEventArgs.xml index ae7baba9139..45b3c5db95d 100644 --- a/xml/System.ComponentModel.Design/DesignerTransactionCloseEventArgs.xml +++ b/xml/System.ComponentModel.Design/DesignerTransactionCloseEventArgs.xml @@ -52,20 +52,20 @@ Provides data for the and events. - event occurs when a designer finalizes a transaction. - - - -## Examples - The following code example demonstrates creating a . - + event occurs when a designer finalizes a transaction. + + + +## Examples + The following code example demonstrates creating a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/DesignerTransactionCloseEventArgsExample/CPP/designertransactioncloseeventargsexample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/DesignerTransactionCloseEventArgs/Overview/designertransactioncloseeventargsexample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/DesignerTransactionCloseEventArgs/Overview/designertransactioncloseeventargsexample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/DesignerTransactionCloseEventArgs/Overview/designertransactioncloseeventargsexample.vb" id="Snippet1"::: + ]]> @@ -189,11 +189,11 @@ if this is the last transaction to close; otherwise, . Initializes a new instance of the class. - property defaults to `true`. - + property defaults to `true`. + ]]> diff --git a/xml/System.ComponentModel.Design/HelpKeywordAttribute.xml b/xml/System.ComponentModel.Design/HelpKeywordAttribute.xml index 06ee517b6f1..95de1468323 100644 --- a/xml/System.ComponentModel.Design/HelpKeywordAttribute.xml +++ b/xml/System.ComponentModel.Design/HelpKeywordAttribute.xml @@ -63,11 +63,11 @@ property value. For members, the Help keyword is given by the full name of the type that declared the property, plus the property name itself. + By default, the Help keyword for a class is given by the property value. For members, the Help keyword is given by the full name of the type that declared the property, plus the property name itself. - For example, consider the property on the control. The class keyword is "System.Windows.Forms.Button", but the property keyword is "System.Windows.Forms.Control.Text", because the property is declared on the class, rather than the class itself; the class inherits the property. + For example, consider the property on the control. The class keyword is "System.Windows.Forms.Button", but the property keyword is "System.Windows.Forms.Control.Text", because the property is declared on the class, rather than the class itself; the class inherits the property. - By contrast, the property is declared on the class, so its keyword is "System.Windows.Forms.Button.DialogResult". + By contrast, the property is declared on the class, so its keyword is "System.Windows.Forms.Button.DialogResult". When the Help system gets the keywords, it will first look at . At the class level, it will return the string specified by the . This will not be used for members of the type in question, which will still reflect the declaring type's actual full name, plus the member name. This attribute supports strongly typed classes that have associated common documentation but distinct Help IDs. @@ -252,7 +252,7 @@ public class DemoComponent : Component property of `t`. + The Help keyword will be set to the property of `t`. ]]> diff --git a/xml/System.ComponentModel.Design/IComponentChangeService.xml b/xml/System.ComponentModel.Design/IComponentChangeService.xml index 50ca5b3bbea..f5e7b230848 100644 --- a/xml/System.ComponentModel.Design/IComponentChangeService.xml +++ b/xml/System.ComponentModel.Design/IComponentChangeService.xml @@ -237,7 +237,7 @@ This event occurs when any component on the form changes. This event will not occur during form load and unload, because changes are expected at this time. > [!NOTE] -> A can raise multiple events. Some event handlers can interfere with expected sequences of events, such as if your code alters the values of properties while a transaction is occurring. A event handler can also impair performance if it draws after each change while a is in progress. To allow a in process to complete without interruption or interference by your event handler, you can test the state of the property and defer handling the change events until the completion of the transaction. Do so by adding a that will raise your event handler and remove itself upon completion of the transaction. +> A can raise multiple events. Some event handlers can interfere with expected sequences of events, such as if your code alters the values of properties while a transaction is occurring. A event handler can also impair performance if it draws after each change while a is in progress. To allow a in process to complete without interruption or interference by your event handler, you can test the state of the property and defer handling the change events until the completion of the transaction. Do so by adding a that will raise your event handler and remove itself upon completion of the transaction. ]]> diff --git a/xml/System.ComponentModel.Design/IComponentDesignerDebugService.xml b/xml/System.ComponentModel.Design/IComponentDesignerDebugService.xml index 293a1401cfd..e25d75e927f 100644 --- a/xml/System.ComponentModel.Design/IComponentDesignerDebugService.xml +++ b/xml/System.ComponentModel.Design/IComponentDesignerDebugService.xml @@ -44,11 +44,11 @@ The message to display. Asserts on a condition inside a design-time environment. - method enables a designer to assert on a condition inside a design-time environment. - + method enables a designer to assert on a condition inside a design-time environment. + ]]> @@ -78,11 +78,11 @@ The message to log. Logs a failure message inside a design-time environment. - method enables a designer to log failure messages inside a design-time environment. - + method enables a designer to log failure messages inside a design-time environment. + ]]> @@ -109,11 +109,11 @@ Gets or sets the indent level for debug output. The indent level for debug output. - property enables a designer to change the indent level for debug output. - + property enables a designer to change the indent level for debug output. + ]]> @@ -140,11 +140,11 @@ Gets a collection of trace listeners for monitoring design-time debugging output. A collection of trace listeners. - property enables objects to monitor design-time debugging output. - + property enables objects to monitor design-time debugging output. + ]]> @@ -176,11 +176,11 @@ The category of . Logs a debug message inside a design-time environment. - method enables a designer to log debug messages inside a design-time environment. - + method enables a designer to log debug messages inside a design-time environment. + ]]> diff --git a/xml/System.ComponentModel.Design/IDesigner.xml b/xml/System.ComponentModel.Design/IDesigner.xml index 0cf4e4042c3..ab4293b2628 100644 --- a/xml/System.ComponentModel.Design/IDesigner.xml +++ b/xml/System.ComponentModel.Design/IDesigner.xml @@ -63,7 +63,7 @@ Implement the method of a designer to perform actions when a component is created. This can be useful if a component should have a special configuration at design-time, or if its configuration should change depending on conditions that the designer can determine. - A designer can provide menu commands on the shortcut menu that is displayed when a user right-clicks a component or control in the design-time environment. You can implement the property to define a get accessor that returns a containing the objects for generating menu commands. + A designer can provide menu commands on the shortcut menu that is displayed when a user right-clicks a component or control in the design-time environment. You can implement the property to define a get accessor that returns a containing the objects for generating menu commands. A designer for a component that appears in the component tray can perform a default action when the component is double-clicked. Implement the method to specify the behavior to perform when the component is double-clicked. diff --git a/xml/System.ComponentModel.Design/IDesignerFilter.xml b/xml/System.ComponentModel.Design/IDesignerFilter.xml index 10e2051780d..1a9b5d24fa0 100644 --- a/xml/System.ComponentModel.Design/IDesignerFilter.xml +++ b/xml/System.ComponentModel.Design/IDesignerFilter.xml @@ -44,24 +44,24 @@ Provides an interface that enables a designer to access and filter the dictionaries of a that stores the property, attribute, and event descriptors that a component designer can expose to the design-time environment. - enables a designer to filter the set of property, attribute, and event descriptors that its associated component exposes through a . The methods of this interface whose names begin with `Pre` are called immediately before the methods whose names begin with `Post`. - - If you want to add attribute, event, or property descriptors, use a , , or method. - - If you want to change or remove attribute, event, or property descriptors, use a , , or method. - - - -## Examples - The following example demonstrates an override of that adds a property of the designer to the Properties window when the designer's control is selected at design time. See the example for the class for a complete designer example that uses the interface. - + enables a designer to filter the set of property, attribute, and event descriptors that its associated component exposes through a . The methods of this interface whose names begin with `Pre` are called immediately before the methods whose names begin with `Post`. + + If you want to add attribute, event, or property descriptors, use a , , or method. + + If you want to change or remove attribute, event, or property descriptors, use a , , or method. + + + +## Examples + The following example demonstrates an override of that adds a property of the designer to the Properties window when the designer's control is selected at design time. See the example for the class for a complete designer example that uses the interface. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/ControlDesignerExample/CPP/controldesignerexample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/IDesignerFilter/Overview/controldesignerexample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/IDesignerFilter/Overview/controldesignerexample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/IDesignerFilter/Overview/controldesignerexample.vb" id="Snippet2"::: + ]]> @@ -111,17 +111,17 @@ The objects for the class of the component. The keys in the dictionary of attributes are the values of the attributes. When overridden in a derived class, allows a designer to change or remove items from the set of attributes that it exposes through a . - . - - The keys in the dictionary of attributes are the type IDs of the attributes. The objects are of type . This method is called immediately after . - - The type ID of an attribute can be any object. By default, returns its as the value of its property. You can check the of an attribute in the dictionary for equivalence with a known for an attribute to identify it, or use to identify the attribute object itself. - - When an attribute that has the same as an existing or inherited attribute is added to a component, the new attribute replaces the old attribute. For many attributes, a new attribute of the same type will replace any previous attribute of the type. However, some types of attributes return a that distinguishes the attribute selectively. For example, in order to provide different types of simultaneously active designers for a type, such as an and an , the class returns a that uniquely identifies both the attribute and the base designer type. The constructor allows you to specify the base designer type of the designer in addition to its specific type, and returns a that reflects this. Therefore when you add a new with a base designer type of the same type as the base designer type of an existing , the old attribute is replaced with the new attribute. - + . + + The keys in the dictionary of attributes are the type IDs of the attributes. The objects are of type . This method is called immediately after . + + The type ID of an attribute can be any object. By default, returns its as the value of its property. You can check the of an attribute in the dictionary for equivalence with a known for an attribute to identify it, or use to identify the attribute object itself. + + When an attribute that has the same as an existing or inherited attribute is added to a component, the new attribute replaces the old attribute. For many attributes, a new attribute of the same type will replace any previous attribute of the type. However, some types of attributes return a that distinguishes the attribute selectively. For example, in order to provide different types of simultaneously active designers for a type, such as an and an , the class returns a that uniquely identifies both the attribute and the base designer type. The constructor allows you to specify the base designer type of the designer in addition to its specific type, and returns a that reflects this. Therefore when you add a new with a base designer type of the same type as the base designer type of an existing , the old attribute is replaced with the new attribute. + ]]> @@ -173,13 +173,13 @@ The objects that represent the events of the class of the component. The keys in the dictionary of events are event names. When overridden in a derived class, allows a designer to change or remove items from the set of events that it exposes through a . - . - - The keys in the dictionary of events are the names of the events. The objects are of type . This method is called immediately after . - + . + + The keys in the dictionary of events are the names of the events. The objects are of type . This method is called immediately after . + ]]> @@ -231,13 +231,13 @@ The objects that represent the properties of the class of the component. The keys in the dictionary of properties are property names. When overridden in a derived class, allows a designer to change or remove items from the set of properties that it exposes through a . - . - - The keys in the dictionary of properties are the names of the properties. The objects are of type . This method is called immediately after . - + . + + The keys in the dictionary of properties are the names of the properties. The objects are of type . This method is called immediately after . + ]]> @@ -289,17 +289,17 @@ The objects for the class of the component. The keys in the dictionary of attributes are the values of the attributes. When overridden in a derived class, allows a designer to add items to the set of attributes that it exposes through a . - . - - The keys in the dictionary of attributes are the type IDs of the attributes. The objects are of type . This method is called immediately before . - - The type ID of an attribute can be any object. By default, returns its as the value of its property. You can check the of an attribute in the dictionary for equivalence with a known for an attribute to identify it, or use to identify the attribute object itself. - - When an attribute that has the same as an existing or inherited attribute is added to a component, the new attribute replaces the old attribute. For many attributes, a new attribute of the same type will replace any previous attribute of the type. However, some types of attributes return a that distinguishes the attribute selectively. For example, in order to provide different types of simultaneously active designers for a type, such as an and an , the class returns a that uniquely identifies both the attribute and the base designer type. The constructor allows you to specify the base designer type of the designer in addition to its specific type, and returns a that reflects this. Therefore when you add a new with a base designer type of the same type as the base designer type of an existing , the old attribute is replaced with the new attribute. - + . + + The keys in the dictionary of attributes are the type IDs of the attributes. The objects are of type . This method is called immediately before . + + The type ID of an attribute can be any object. By default, returns its as the value of its property. You can check the of an attribute in the dictionary for equivalence with a known for an attribute to identify it, or use to identify the attribute object itself. + + When an attribute that has the same as an existing or inherited attribute is added to a component, the new attribute replaces the old attribute. For many attributes, a new attribute of the same type will replace any previous attribute of the type. However, some types of attributes return a that distinguishes the attribute selectively. For example, in order to provide different types of simultaneously active designers for a type, such as an and an , the class returns a that uniquely identifies both the attribute and the base designer type. The constructor allows you to specify the base designer type of the designer in addition to its specific type, and returns a that reflects this. Therefore when you add a new with a base designer type of the same type as the base designer type of an existing , the old attribute is replaced with the new attribute. + ]]> @@ -351,13 +351,13 @@ The objects that represent the events of the class of the component. The keys in the dictionary of events are event names. When overridden in a derived class, allows a designer to add items to the set of events that it exposes through a . - . - - The keys in the dictionary of events are the names of the events. The objects are of type . This method is called immediately before . - + . + + The keys in the dictionary of events are the names of the events. The objects are of type . This method is called immediately before . + ]]> @@ -409,13 +409,13 @@ The objects that represent the properties of the class of the component. The keys in the dictionary of properties are property names. When overridden in a derived class, allows a designer to add items to the set of properties that it exposes through a . - . - - The keys in the dictionary of properties are the names of the properties. The objects are of type . This method is called immediately before . - + . + + The keys in the dictionary of properties are the names of the properties. The objects are of type . This method is called immediately before . + ]]> diff --git a/xml/System.ComponentModel.Design/IMenuCommandService.xml b/xml/System.ComponentModel.Design/IMenuCommandService.xml index c13b1132ec4..8f8eb5e138a 100644 --- a/xml/System.ComponentModel.Design/IMenuCommandService.xml +++ b/xml/System.ComponentModel.Design/IMenuCommandService.xml @@ -63,9 +63,9 @@ - Display a shortcut menu of standard commands that is associated with a menu . - Designer verbs represent custom-defined commands that are listed on the shortcut menu in design mode. A designer verb can provide a specified text label. Each designer verb is automatically assigned a unique . A designer can provide designer verbs through its property, but these are only available when the designer's component is currently selected. Global designer verbs are designer verb commands that can be accessed from a design-mode shortcut menu regardless of the selected component. This interface allows you to manage the set of global designer verbs that are available in design mode. + Designer verbs represent custom-defined commands that are listed on the shortcut menu in design mode. A designer verb can provide a specified text label. Each designer verb is automatically assigned a unique . A designer can provide designer verbs through its property, but these are only available when the designer's component is currently selected. Global designer verbs are designer verb commands that can be accessed from a design-mode shortcut menu regardless of the selected component. This interface allows you to manage the set of global designer verbs that are available in design mode. - You can add a global designer verb using the method, and you can remove a global designer verb using the method. You can invoke a designer verb using the method if you know the of the verb. The property of this interface contains the current set of designer verb commands to display in a shortcut menu. This set of designer verb commands consists of all global designer verbs and any designer verbs offered by the designer of any currently selected component. This set of verbs is updated each time a component with a designer offering designer verb commands is selected or deselected. + You can add a global designer verb using the method, and you can remove a global designer verb using the method. You can invoke a designer verb using the method if you know the of the verb. The property of this interface contains the current set of designer verb commands to display in a shortcut menu. This set of designer verb commands consists of all global designer verbs and any designer verbs offered by the designer of any currently selected component. This set of verbs is updated each time a component with a designer offering designer verb commands is selected or deselected. Menu commands are limited to the set of predefined standard commands. Most of the predefined standard commands are defined in the and enumerations. You can add, remove, and invoke menu commands, and search for menu commands that have been added to a menu using methods of this interface. @@ -213,7 +213,7 @@ property of their designer rather than calling this method. This method adds a global designer verb that can be accessed from the right-click shortcut menu in design mode regardless of the currently selected component. + Designers of components that provide designer verbs should use the property of their designer rather than calling this method. This method adds a global designer verb that can be accessed from the right-click shortcut menu in design mode regardless of the currently selected component. ]]> @@ -544,7 +544,7 @@ method on this interface, and individual designer verbs, which are offered by the property of individual designers. If the name of a global verb conflicts with the name of a designer verb, the designer-provided designer verb takes precedence. + The set of currently available designer verbs consists of all global designer verbs, which are added by the method on this interface, and individual designer verbs, which are offered by the property of individual designers. If the name of a global verb conflicts with the name of a designer verb, the designer-provided designer verb takes precedence. ]]> diff --git a/xml/System.ComponentModel.Design/IReferenceService.xml b/xml/System.ComponentModel.Design/IReferenceService.xml index ae474e3b37e..bdc0f887f2b 100644 --- a/xml/System.ComponentModel.Design/IReferenceService.xml +++ b/xml/System.ComponentModel.Design/IReferenceService.xml @@ -177,7 +177,7 @@ property of the where the component is sited. + The name of each component sited in a design time project is set in the property of the where the component is sited. ]]> diff --git a/xml/System.ComponentModel.Design/ITreeDesigner.xml b/xml/System.ComponentModel.Design/ITreeDesigner.xml index b36b50fbcf3..bf6e1c868dc 100644 --- a/xml/System.ComponentModel.Design/ITreeDesigner.xml +++ b/xml/System.ComponentModel.Design/ITreeDesigner.xml @@ -119,7 +119,7 @@ property will return an empty collection if the has no child objects. + The property will return an empty collection if the has no child objects. ]]> diff --git a/xml/System.ComponentModel.Design/MenuCommand.xml b/xml/System.ComponentModel.Design/MenuCommand.xml index 7a3ef644d01..0a3e36d22d4 100644 --- a/xml/System.ComponentModel.Design/MenuCommand.xml +++ b/xml/System.ComponentModel.Design/MenuCommand.xml @@ -73,7 +73,7 @@ - Boolean flag states that indicate whether the command is , , , or . -- An property that indicates the OLE command status code for the command. +- An property that indicates the OLE command status code for the command. - An override for the method. diff --git a/xml/System.ComponentModel.Design/MenuCommandService.xml b/xml/System.ComponentModel.Design/MenuCommandService.xml index a48ee56716a..7eea3de8afc 100644 --- a/xml/System.ComponentModel.Design/MenuCommandService.xml +++ b/xml/System.ComponentModel.Design/MenuCommandService.xml @@ -950,7 +950,7 @@ property provides a collection of verbs. These verbs come from two places: + The property provides a collection of verbs. These verbs come from two places: - Verbs added through the method of . diff --git a/xml/System.ComponentModel.Design/ServiceContainer.xml b/xml/System.ComponentModel.Design/ServiceContainer.xml index 48ff790b40c..4cc3d728cce 100644 --- a/xml/System.ComponentModel.Design/ServiceContainer.xml +++ b/xml/System.ComponentModel.Design/ServiceContainer.xml @@ -78,7 +78,7 @@ The object can be created using a constructor that adds a parent through which services can be optionally added to or removed from all parent objects, including the immediate parent . To add or remove a service from all implementations that are linked to this through parenting, call the or method overload that accepts a Boolean value indicating whether to promote the service request. > [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). diff --git a/xml/System.ComponentModel.Design/StandardCommands.xml b/xml/System.ComponentModel.Design/StandardCommands.xml index 4b6ad9fa9f1..39b67172a28 100644 --- a/xml/System.ComponentModel.Design/StandardCommands.xml +++ b/xml/System.ComponentModel.Design/StandardCommands.xml @@ -52,22 +52,22 @@ Defines identifiers for the standard set of commands that are available to most applications. - identifiers for standard commands that are available to designers. - - To add a command from the class to a designer menu, you must call the method of an and add a that contains a from . - - - -## Examples - The following code example illustrates how to add a member of the class to a and how to add the to an . - + identifiers for standard commands that are available to designers. + + To add a command from the class to a designer menu, you must call the method of an and add a that contains a from . + + + +## Examples + The following code example illustrates how to add a member of the class to a and how to add the to an . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/MenuCommand Example/CPP/component1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel.Design/IMenuCommandService/Overview/component1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/IMenuCommandService/Overview/component1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel.Design/IMenuCommandService/Overview/component1.vb" id="Snippet1"::: + ]]> @@ -2084,15 +2084,15 @@ Gets the first of a set of verbs. This field is read-only. - that identifies the first of a set of designer verbs. - - The Visual Studio Windows Forms Designer automatically maps designer verbs to the property on , so generally you do not need to access this command. - - All designer verbs for an object become commands with a within a sequential range of IDs that begins with and ends with . - + that identifies the first of a set of designer verbs. + + The Visual Studio Windows Forms Designer automatically maps designer verbs to the property on , so generally you do not need to access this command. + + All designer verbs for an object become commands with a within a sequential range of IDs that begins with and ends with . + ]]> @@ -2136,15 +2136,15 @@ Gets the last of a set of verbs. This field is read-only. - that identifies the last of a set of designer verbs. - - The Visual Studio Windows Forms Designer automatically maps designer verbs to the property on , so generally you do not need to access this command. - - All designer verbs for an object become commands with a within a sequential range of IDs that begins with and ends with . - + that identifies the last of a set of designer verbs. + + The Visual Studio Windows Forms Designer automatically maps designer verbs to the property on , so generally you do not need to access this command. + + All designer verbs for an object become commands with a within a sequential range of IDs that begins with and ends with . + ]]> diff --git a/xml/System.ComponentModel/AddingNewEventArgs.xml b/xml/System.ComponentModel/AddingNewEventArgs.xml index 90aff2bcdf1..79075161f10 100644 --- a/xml/System.ComponentModel/AddingNewEventArgs.xml +++ b/xml/System.ComponentModel/AddingNewEventArgs.xml @@ -51,26 +51,26 @@ Provides data for the event. - class provides data for the event, which signals that an item is about to be added to a collection. The event gives the programmer, within the event handler , the option of supplying the new object by setting the property to this new item. If this property is not set, the collection will typically use the parameterless constructor of the appropriate type to construct a new item. In either case, the new item will be added to the collection. - - If the collection also implements the interface, the item will be provisionally added, waiting a subsequent commit or rollback. - - This event is commonly used in data-binding scenarios, within classes such as and . - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates how to use the class to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](/dotnet/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource). - + class provides data for the event, which signals that an item is about to be added to a collection. The event gives the programmer, within the event handler , the option of supplying the new object by setting the property to this new item. If this property is not set, the collection will typically use the parameterless constructor of the appropriate type to construct a new item. In either case, the new item will be added to the collection. + + If the collection also implements the interface, the item will be provisionally added, waiting a subsequent commit or rollback. + + This event is commonly used in data-binding scenarios, within classes such as and . + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following code example demonstrates how to use the class to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](/dotnet/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CPP/form1.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AddingNewEventArgs/Overview/form1.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AddingNewEventArgs/Overview/form1.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AddingNewEventArgs/Overview/form1.vb" id="Snippet8"::: + ]]> @@ -129,11 +129,11 @@ Initializes a new instance of the class using no parameters. - property to `null`. A value that is `null` indicates that, if the does not explicitly set this property, the collection will take standard steps to provide a new item to add to itself. - + property to `null`. A value that is `null` indicates that, if the does not explicitly set this property, the collection will take standard steps to provide a new item to add to itself. + ]]> @@ -186,11 +186,11 @@ An to use as the new item value. Initializes a new instance of the class using the specified object as the new item. - constructor sets the property to the `newObject` parameter. This object will be used as the new item to be added to the associated collection, unless this property is updated by the event handler. - + constructor sets the property to the `newObject` parameter. This object will be used as the new item to be added to the associated collection, unless this property is updated by the event handler. + ]]> @@ -247,20 +247,20 @@ Gets or sets the object to be added to the binding list. The to be added as a new item to the associated collection. - property is set to `null`, it indicates that the collection is to take the standard action, which typically entails creating an object of the appropriate type using its parameterless constructor, and then adding it to the collection. - - - -## Examples - The following code example demonstrates how to use the class to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](/dotnet/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource). - + property is set to `null`, it indicates that the collection is to take the standard action, which typically entails creating an object of the appropriate type using its parameterless constructor, and then adding it to the collection. + + + +## Examples + The following code example demonstrates how to use the class to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](/dotnet/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CPP/form1.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AddingNewEventArgs/Overview/form1.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AddingNewEventArgs/Overview/form1.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AddingNewEventArgs/Overview/form1.vb" id="Snippet8"::: + ]]> diff --git a/xml/System.ComponentModel/AddingNewEventHandler.xml b/xml/System.ComponentModel/AddingNewEventHandler.xml index 9655232f3bf..cac168a06e1 100644 --- a/xml/System.ComponentModel/AddingNewEventHandler.xml +++ b/xml/System.ComponentModel/AddingNewEventHandler.xml @@ -61,24 +61,24 @@ A that contains the event data. Represents the method that will handle the event. - event occurs prior to adding a new item to a collection, typically in data-binding scenarios. The handler of this event can supply the new item to be added, overriding the standard action of the collection class. This is accomplished by setting the property of the parameter `e` to this new item. Typically this item must be of a type expected by the recipient collection, or the collection will throw an exception of type . - - This event is commonly used in data-binding scenarios, within classes such as and . - - When you create an delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates how to use the delegate to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](/dotnet/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource). - + event occurs prior to adding a new item to a collection, typically in data-binding scenarios. The handler of this event can supply the new item to be added, overriding the standard action of the collection class. This is accomplished by setting the property of the parameter `e` to this new item. Typically this item must be of a type expected by the recipient collection, or the collection will throw an exception of type . + + This event is commonly used in data-binding scenarios, within classes such as and . + + When you create an delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following code example demonstrates how to use the delegate to handle the event. This code example is part of a larger example provided in [How to: Customize Item Addition with the Windows Forms BindingSource](/dotnet/framework/winforms/controls/how-to-customize-item-addition-with-the-windows-forms-bindingsource). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.DataConnector.AddingNew/CPP/form1.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AddingNewEventArgs/Overview/form1.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AddingNewEventArgs/Overview/form1.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AddingNewEventArgs/Overview/form1.vb" id="Snippet8"::: + ]]> diff --git a/xml/System.ComponentModel/AmbientValueAttribute.xml b/xml/System.ComponentModel/AmbientValueAttribute.xml index 40ba952ef3c..0597b86e9f0 100644 --- a/xml/System.ComponentModel/AmbientValueAttribute.xml +++ b/xml/System.ComponentModel/AmbientValueAttribute.xml @@ -56,21 +56,21 @@ Specifies the value to pass to a property to cause the property to get its value from another source. This is known as *ambience*. This class cannot be inherited. - property or a property. - - Typically, a visual designer uses the attribute to decide which value to persist for a property. This is usually a value that causes the property to get its value from another source. An example of an ambient value is as the ambient value for the property. If you have a control on a form and the property of the control is set to a different color than the property of the form, you can reset the property of the control to that of the form by setting the of the control to . - - - -## Examples - The following code example demonstrates using to enforce ambient behavior for a property called `AlertForeColor`. For a full code listing, see [How to: Apply Attributes in Windows Forms Controls](/dotnet/framework/winforms/controls/how-to-apply-attributes-in-windows-forms-controls). - + property or a property. + + Typically, a visual designer uses the attribute to decide which value to persist for a property. This is usually a value that causes the property to get its value from another source. An example of an ambient value is as the ambient value for the property. If you have a control on a form and the property of the control is set to a different color than the property of the form, you can reset the property of the control to that of the form by setting the of the control to . + + + +## Examples + The following code example demonstrates using to enforce ambient behavior for a property called `AlertForeColor`. For a full code listing, see [How to: Apply Attributes in Windows Forms Controls](/dotnet/framework/winforms/controls/how-to-apply-attributes-in-windows-forms-controls). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.cs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.vb" id="Snippet23"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.vb" id="Snippet23"::: + ]]> @@ -578,14 +578,14 @@ The value for this attribute. Initializes a new instance of the class, given the value and its type. - to enforce ambient behavior for a property called `AlertForeColor`. For a full code listing, see [How to: Apply Attributes in Windows Forms Controls](/dotnet/framework/winforms/controls/how-to-apply-attributes-in-windows-forms-controls). - + to enforce ambient behavior for a property called `AlertForeColor`. For a full code listing, see [How to: Apply Attributes in Windows Forms Controls](/dotnet/framework/winforms/controls/how-to-apply-attributes-in-windows-forms-controls). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.cs" id="Snippet23"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.vb" id="Snippet23"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.vb" id="Snippet23"::: + ]]> diff --git a/xml/System.ComponentModel/AsyncCompletedEventArgs.xml b/xml/System.ComponentModel/AsyncCompletedEventArgs.xml index 70a054e5a70..228e9b42bc1 100644 --- a/xml/System.ComponentModel/AsyncCompletedEventArgs.xml +++ b/xml/System.ComponentModel/AsyncCompletedEventArgs.xml @@ -53,32 +53,32 @@ Provides data for the *MethodName* event. - delegate to the event, you will receive information about the outcome of asynchronous operations in the parameter of the corresponding event-handler method. - - The client application's event-handler delegate can check the property to determine if the asynchronous task was cancelled. - - The client application's event-handler delegate can check the property to determine if an exception occurred during execution of the asynchronous task. - - If the class supports multiple asynchronous methods, or multiple calls to the same asynchronous method, you can determine which task raised the *MethodName*`Completed` event by checking the value of the property. Your code will need to track these tokens, known as task IDs, as their corresponding asynchronous tasks start and complete. - - - -## Examples - The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. - + delegate to the event, you will receive information about the outcome of asynchronous operations in the parameter of the corresponding event-handler method. + + The client application's event-handler delegate can check the property to determine if the asynchronous task was cancelled. + + The client application's event-handler delegate can check the property to determine if an exception occurred during execution of the asynchronous task. + + If the class supports multiple asynchronous methods, or multiple calls to the same asynchronous method, you can determine which task raised the *MethodName*`Completed` event by checking the value of the property. Your code will need to track these tokens, known as task IDs, as their corresponding asynchronous tasks start and complete. + + + +## Examples + The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet12"::: -:::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet12"::: - +:::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet12"::: + ]]> - Classes that follow the Event-based Asynchronous Pattern can raise events to alert clients about the status of pending asynchronous operations. If the class provides a *MethodName* event, you can use the to tell clients about the outcome of asynchronous operations. - + Classes that follow the Event-based Asynchronous Pattern can raise events to alert clients about the status of pending asynchronous operations. If the class provides a *MethodName* event, you can use the to tell clients about the outcome of asynchronous operations. + You may want to communicate to clients more information about the outcome of an asynchronous operation than an accommodates. In this case, you can derive your own class from the class and provide additional private instance variables and corresponding read-only public properties. Call the method before returning the property value, in case the operation was canceled or an error occurred. @@ -230,23 +230,23 @@ if the background operation has been canceled; otherwise . The default is . - property is `true`, the asynchronous operation was interrupted. - - The client application's event-handler delegate should check the property before accessing any properties in a class derived from ; otherwise, the property will raise an if the asynchronous operation was interrupted. - - - -## Examples - The following code example demonstrates the using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. - + property is `true`, the asynchronous operation was interrupted. + + The client application's event-handler delegate should check the property before accessing any properties in a class derived from ; otherwise, the property will raise an if the asynchronous operation was interrupted. + + + +## Examples + The following code example demonstrates the using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet12"::: -:::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet12"::: - +:::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet12"::: + ]]> @@ -305,23 +305,23 @@ Gets a value indicating which error occurred during an asynchronous operation. An instance, if an error occurred during an asynchronous operation; otherwise . - property. The client application's event-handler delegate should check the property before accessing any properties in a class derived from ; otherwise, the property will raise a with its property holding a reference to . - - The value of the property is `null` if the operation was canceled. - - - -## Examples - The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. - + property. The client application's event-handler delegate should check the property before accessing any properties in a class derived from ; otherwise, the property will raise a with its property holding a reference to . + + The value of the property is `null` if the operation was canceled. + + + +## Examples + The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet12"::: -:::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet12"::: - +:::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet12"::: + ]]> @@ -373,15 +373,15 @@ Raises a user-supplied exception if an asynchronous operation failed. - in derived class properties. - - + in derived class properties. + + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet6"::: -:::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet6"::: - +:::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet6"::: + ]]> The property is . @@ -441,23 +441,23 @@ Gets the unique identifier for the asynchronous task. An object reference that uniquely identifies the asynchronous task; otherwise, if no value has been set. - property. Your code will need track these tokens, known as task IDs, as their corresponding asynchronous tasks start and complete. - - The value of this property is set during the original call to the asynchronous method that started the task. - - - -## Examples - The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. - + property. Your code will need track these tokens, known as task IDs, as their corresponding asynchronous tasks start and complete. + + The value of this property is set during the original call to the asynchronous method that started the task. + + + +## Examples + The following code example demonstrates using an to track the lifetime of asynchronous operations. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet12"::: -:::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet12"::: - +:::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet12"::: + ]]> diff --git a/xml/System.ComponentModel/AsyncCompletedEventHandler.xml b/xml/System.ComponentModel/AsyncCompletedEventHandler.xml index 7dc4dc52372..0df29592ad0 100644 --- a/xml/System.ComponentModel/AsyncCompletedEventHandler.xml +++ b/xml/System.ComponentModel/AsyncCompletedEventHandler.xml @@ -63,20 +63,20 @@ An that contains the event data. Represents the method that will handle the *MethodName* event of an asynchronous operation. - delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event-handler method is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - - For an asynchronous method, called *MethodName*, in your component, you will have a corresponding *MethodName*`Completed` event, and an optional *MethodName*`CompletedEventArgs` class. - - For a component that supports multiple concurrent invocations of its asynchronous methods, the client can supply a unique token, or task ID, to distinguish which asynchronous task is raising particular events. The client's can read the property to determine which task is reporting completion. Your implementation should use the to create an that associates the client's task IDs with pending asynchronous tasks. - - - -## Examples - For a code example of the delegate, see the example in the class. - + delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event-handler method is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). + + For an asynchronous method, called *MethodName*, in your component, you will have a corresponding *MethodName*`Completed` event, and an optional *MethodName*`CompletedEventArgs` class. + + For a component that supports multiple concurrent invocations of its asynchronous methods, the client can supply a unique token, or task ID, to distinguish which asynchronous task is raising particular events. The client's can read the property to determine which task is reporting completion. Your implementation should use the to create an that associates the client's task IDs with pending asynchronous tasks. + + + +## Examples + For a code example of the delegate, see the example in the class. + ]]> diff --git a/xml/System.ComponentModel/AsyncOperation.xml b/xml/System.ComponentModel/AsyncOperation.xml index d924e0f8f90..1514bdef51c 100644 --- a/xml/System.ComponentModel/AsyncOperation.xml +++ b/xml/System.ComponentModel/AsyncOperation.xml @@ -63,7 +63,7 @@ - To indicate that an asynchronous task has completed, or to cancel a pending asynchronous task, call . - Your class should get an object for each asynchronous task by calling when each task starts. To allow the client to distinguish separate asynchronous tasks, takes a parameter for a unique client-provided token, which becomes the property. It can then be used by client code to identify the particular asynchronous task that is raising progress or completion events. + Your class should get an object for each asynchronous task by calling when each task starts. To allow the client to distinguish separate asynchronous tasks, takes a parameter for a unique client-provided token, which becomes the property. It can then be used by client code to identify the particular asynchronous task that is raising progress or completion events. @@ -455,10 +455,10 @@ Note: Console applications do not synchronize the execution of that will act as a task ID. You will use this task ID when you call the , method and this will associate the client's task ID with a particular invocation of your asynchronous operation. This task ID is made available to your implementation through the property. + If your class supports multiple asynchronous methods or multiple invocations of a single asynchronous method, clients will need a way to determine which asynchronous task is raising events. Your `MethodNameAsync` method should take a parameter of type that will act as a task ID. You will use this task ID when you call the , method and this will associate the client's task ID with a particular invocation of your asynchronous operation. This task ID is made available to your implementation through the property. > [!CAUTION] -> Client code must be careful to provide a unique value for the property. Non-unique task IDs may cause your implementation to report progress and other events incorrectly. Your code should check for a non-unique task ID and raise an if one is detected. +> Client code must be careful to provide a unique value for the property. Non-unique task IDs may cause your implementation to report progress and other events incorrectly. Your code should check for a non-unique task ID and raise an if one is detected. diff --git a/xml/System.ComponentModel/AsyncOperationManager.xml b/xml/System.ComponentModel/AsyncOperationManager.xml index 2ef4c922b4d..4f40e0a8aa0 100644 --- a/xml/System.ComponentModel/AsyncOperationManager.xml +++ b/xml/System.ComponentModel/AsyncOperationManager.xml @@ -52,25 +52,25 @@ Provides concurrency management for classes that support asynchronous method calls. This class cannot be inherited. - provides a convenient way to create a class that runs properly under all application models supported by the .NET Framework. - - The class has one method, , which returns an that can be used to track the duration of a particular asynchronous task. The for a task can be used to alert clients when a task completes. It can also be used to post progress updates and incremental results without terminating the operation. - - For more information about implementing asynchronous classes, see [Implementing the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern). - - - -## Examples - The following code example demonstrates using the class to create a class that supports asynchronous operations for any application model. It shows how to implement a class that tests a number to determine whether it is prime. This calculation can be time consuming, so it is done on a separate thread. Progress reports, incremental results, and completion notifications are handled by the class, which ensures that the client's event handlers are called on the proper thread or context. - - For a full code listing, see [How to: Implement a Component That Supports the Event-based Asynchronous Pattern](/previous-versions/dotnet/netframework-4.0/9hk12d4y(v=vs.100)). For a full code listing of a client form, see [How to: Implement a Client of the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/how-to-implement-a-client-of-the-event-based-asynchronous-pattern). - + provides a convenient way to create a class that runs properly under all application models supported by the .NET Framework. + + The class has one method, , which returns an that can be used to track the duration of a particular asynchronous task. The for a task can be used to alert clients when a task completes. It can also be used to post progress updates and incremental results without terminating the operation. + + For more information about implementing asynchronous classes, see [Implementing the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern). + + + +## Examples + The following code example demonstrates using the class to create a class that supports asynchronous operations for any application model. It shows how to implement a class that tests a number to determine whether it is prime. This calculation can be time consuming, so it is done on a separate thread. Progress reports, incremental results, and completion notifications are handled by the class, which ensures that the client's event handlers are called on the proper thread or context. + + For a full code listing, see [How to: Implement a Component That Supports the Event-based Asynchronous Pattern](/previous-versions/dotnet/netframework-4.0/9hk12d4y(v=vs.100)). For a full code listing of a client form, see [How to: Implement a Client of the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/how-to-implement-a-client-of-the-event-based-asynchronous-pattern). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet3"::: + ]]> @@ -130,28 +130,28 @@ Returns an for tracking the duration of a particular asynchronous operation. An that you can use to track the duration of an asynchronous method invocation. - method returns an that you can use to track the duration of a particular asynchronous operation and to alert the application model when the operation completes. You can also use it to post progress updates and incremental results without terminating the operation. The will correctly marshal these calls to the appropriate thread or context for the application model. - - If you implement a class that supports the Event-based Asynchronous Pattern, your class should call each time your *MethodName*`Async` method is called. The client application that makes calls to the method can use the `userSuppliedState` parameter to uniquely identify each invocation, so as to distinguish events raised during the execution of the asynchronous operation. - + method returns an that you can use to track the duration of a particular asynchronous operation and to alert the application model when the operation completes. You can also use it to post progress updates and incremental results without terminating the operation. The will correctly marshal these calls to the appropriate thread or context for the application model. + + If you implement a class that supports the Event-based Asynchronous Pattern, your class should call each time your *MethodName*`Async` method is called. The client application that makes calls to the method can use the `userSuppliedState` parameter to uniquely identify each invocation, so as to distinguish events raised during the execution of the asynchronous operation. + > [!CAUTION] -> Client code must provide a unique value for the `userSuppliedState` parameter. Non-unique task IDs may cause your implementation to report progress and other events incorrectly. Your code should check for a non-unique task ID and throw an if one is detected. - - Your code should track every returned by and use the object in the corresponding underlying asynchronous operation to post updates and terminate the operation. This tracking can be as simple as passing the as a parameter among delegates. In more sophisticated designs, your class can maintain a collection of objects, adding objects when tasks are started and removing them when tasks are completed or canceled. This approach allows you to check for unique `userSuppliedState` parameter values, and is the method you should use when working with classes that support multiple concurrent invocations. - - For more information about implementing asynchronous classes, see [Implementing the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern). - - - -## Examples - The following code example demonstrates using the method to create an for tracking the duration of asynchronous operations. This code example is part of a larger example provided for the class. - +> Client code must provide a unique value for the `userSuppliedState` parameter. Non-unique task IDs may cause your implementation to report progress and other events incorrectly. Your code should check for a non-unique task ID and throw an if one is detected. + + Your code should track every returned by and use the object in the corresponding underlying asynchronous operation to post updates and terminate the operation. This tracking can be as simple as passing the as a parameter among delegates. In more sophisticated designs, your class can maintain a collection of objects, adding objects when tasks are started and removing them when tasks are completed or canceled. This approach allows you to check for unique `userSuppliedState` parameter values, and is the method you should use when working with classes that support multiple concurrent invocations. + + For more information about implementing asynchronous classes, see [Implementing the Event-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/implementing-the-event-based-asynchronous-pattern). + + + +## Examples + The following code example demonstrates using the method to create an for tracking the duration of asynchronous operations. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet3"::: + ]]> @@ -205,13 +205,13 @@ Gets or sets the synchronization context for the asynchronous operation. The synchronization context for the asynchronous operation. - property to `null` to release the free-threaded factory when it is done, or else its factory will never be disposed. - + property to `null` to release the free-threaded factory when it is done, or else its factory will never be disposed. + ]]> diff --git a/xml/System.ComponentModel/AttributeCollection.xml b/xml/System.ComponentModel/AttributeCollection.xml index 6df9fc681a5..25598863f6f 100644 --- a/xml/System.ComponentModel/AttributeCollection.xml +++ b/xml/System.ComponentModel/AttributeCollection.xml @@ -65,30 +65,30 @@ Represents a collection of attributes. - class is read-only; it does not implement methods to add or remove attributes. You must inherit from this class to implement these methods. - - Use the property to find the number of attributes that exist in the collection. - - You can also use the methods of this class to query the collection about its contents. Call the method to verify that a specified attribute or attribute array exists in the collection. Call the method to verify that a specified attribute or array of attributes exists in the collection, and that the values of the specified attributes are the same as the values in the collection. - - While most attributes have default values, default values are not required. If an attribute has no default value, `null` is returned from the indexed property that takes a type. When defining your own attributes, you can declare a default value by either providing a constructor that takes no arguments, or defining a public static field of your attribute type named "Default". - - - -## Examples - The first code example checks to see whether the has been set in this collection. The second code example gets the actual value of the for a button. Both examples require that `button1` and `textBox1` have been created on a form. When using attributes, verify that an attribute has been set, or access its value. - + class is read-only; it does not implement methods to add or remove attributes. You must inherit from this class to implement these methods. + + Use the property to find the number of attributes that exist in the collection. + + You can also use the methods of this class to query the collection about its contents. Call the method to verify that a specified attribute or attribute array exists in the collection. Call the method to verify that a specified attribute or array of attributes exists in the collection, and that the values of the specified attributes are the same as the values in the collection. + + While most attributes have default values, default values are not required. If an attribute has no default value, `null` is returned from the indexed property that takes a type. When defining your own attributes, you can declare a default value by either providing a constructor that takes no arguments, or defining a public static field of your attribute type named "Default". + + + +## Examples + The first code example checks to see whether the has been set in this collection. The second code example gets the actual value of the for a button. Both examples require that `button1` and `textBox1` have been created on a form. When using attributes, verify that an attribute has been set, or access its value. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic AttributeCollection Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AttributeCollection/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Overview/source.vb" id="Snippet1"::: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic AttributeCollection Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AttributeCollection/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Overview/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Overview/source.vb" id="Snippet2"::: + ]]> @@ -206,15 +206,15 @@ An array of type that provides the attributes for this collection. Initializes a new instance of the class. - using the attributes on `button1`. It assumes that `button1` has been created on a form. - + using the attributes on `button1`. It assumes that `button1` has been created on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic AttributeCollection.AttributeCollection Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AttributeCollection/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/.ctor/source.vb" id="Snippet1"::: + ]]> @@ -333,24 +333,24 @@ if the collection contains the attribute or is the default attribute for the type of attribute; otherwise, . - and methods is that calls the method on an attribute, and calls the method. - - For most attributes, these methods do the same thing. For attributes that may have multiple flags, however, is typically implemented so that it returns `true` if any of the flags are satisfied. For example, consider a data binding attribute with the Boolean flags "SupportsSql", "SupportsOleDb", and "SupportsXml". This attribute may be present on a property that supports all three data-binding approaches. It will often be the case that a programmer needs to know only if a particular approach is available, not all three. Therefore, a programmer could use with an instance of the attribute containing only the flags the programmer needs. - - - -## Examples - The following code example checks to see whether the collection has a set to `true`. It assumes that `button1` and `textBox1` have been created on a form. - + and methods is that calls the method on an attribute, and calls the method. + + For most attributes, these methods do the same thing. For attributes that may have multiple flags, however, is typically implemented so that it returns `true` if any of the flags are satisfied. For example, consider a data binding attribute with the Boolean flags "SupportsSql", "SupportsOleDb", and "SupportsXml". This attribute may be present on a property that supports all three data-binding approaches. It will often be the case that a programmer needs to know only if a particular approach is available, not all three. Therefore, a programmer could use with an instance of the attribute containing only the flags the programmer needs. + + + +## Examples + The following code example checks to see whether the collection has a set to `true`. It assumes that `button1` and `textBox1` have been created on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic AttributeCollection.Contains Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AttributeCollection/Contains/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Contains/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Contains/source.vb" id="Snippet1"::: + ]]> @@ -416,20 +416,20 @@ if the collection contains all the attributes; otherwise, . - @@ -531,20 +531,20 @@ Gets the number of attributes. The number of attributes. - property to set the limits of a loop that iterates through a collection of objects. If the collection is zero-based, be sure to use `Count - 1` as the upper boundary of the loop. - - - -## Examples - The following code example uses the property to print the number of properties on `button1` in a text box. It assumes that `button1` and `textBox1` have been created on a form. - + property to set the limits of a loop that iterates through a collection of objects. If the collection is zero-based, be sure to use `Count - 1` as the upper boundary of the loop. + + + +## Examples + The following code example uses the property to print the number of properties on `button1` in a text box. It assumes that `button1` and `textBox1` have been created on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic AttributeCollection.Count Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AttributeCollection/Count/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Count/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Count/source.vb" id="Snippet1"::: + ]]> @@ -650,11 +650,11 @@ Creates a new from an existing . A new that is a copy of . - entries are merged with those of the `existing` parameter. - + entries are merged with those of the `existing` parameter. + ]]> @@ -770,15 +770,15 @@ Gets an enumerator for this collection. An enumerator of type . - @@ -840,20 +840,20 @@ Gets the attribute with the specified index number. The with the specified index number. - to access that . For example, to get the third , you need to specify `myColl[2]`. - - - -## Examples - The following code example uses the property to print the name of the specified by the index number in a text box. Because the index number is zero-based, this code example prints the name of the second in a text box. It assumes `button1` and `textBox1` have been created on a form. - + to access that . For example, to get the third , you need to specify `myColl[2]`. + + + +## Examples + The following code example uses the property to print the name of the specified by the index number in a text box. Because the index number is zero-based, this code example prints the name of the second in a text box. It assumes `button1` and `textBox1` have been created on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic AttributeCollection.this Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AttributeCollection/Item/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Item/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Item/source.vb" id="Snippet1"::: + ]]> @@ -918,22 +918,22 @@ Gets the attribute with the specified type. The with the specified type or, if the attribute does not exist, the default value for the attribute type. - from the collection and prints its value. It assumes that `button1` and `textBox1` have been created on a form. - - For this code example to run, you must provide the fully qualified assembly name. For information about how to obtain the fully qualified assembly name, see [Assembly Names](/dotnet/standard/assembly/names). - + from the collection and prints its value. It assumes that `button1` and `textBox1` have been created on a form. + + For this code example to run, you must provide the fully qualified assembly name. For information about how to obtain the fully qualified assembly name, see [Assembly Names](/dotnet/standard/assembly/names). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic AttributeCollection.this1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AttributeCollection/Item/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Item/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Item/source1.vb" id="Snippet1"::: + ]]> @@ -996,24 +996,24 @@ if the attribute is contained within the collection and has the same value as the attribute in the collection; otherwise, . - and methods is that calls the method on an attribute, and calls the method. - - For most attributes, these methods do the same thing. For attributes that may have multiple flags, however, is typically implemented so that it returns `true` if any of the flags are satisfied. For example, consider a data binding attribute with the Boolean flags "SupportsSql", "SupportsOleDb", and "SupportsXml". This attribute may be present on a property that supports all three data binding approaches. It will often be the case that a programmer needs to know only if a particular approach is available, not all three. Therefore, a programmer could use with an instance of the attribute containing only the flags the programmer needs. - - - -## Examples - The following code example verifies that the is a member of the collection and that it has been set to `true`. It assumes that `button1` and `textBox1` have been created on a form. - + and methods is that calls the method on an attribute, and calls the method. + + For most attributes, these methods do the same thing. For attributes that may have multiple flags, however, is typically implemented so that it returns `true` if any of the flags are satisfied. For example, consider a data binding attribute with the Boolean flags "SupportsSql", "SupportsOleDb", and "SupportsXml". This attribute may be present on a property that supports all three data binding approaches. It will often be the case that a programmer needs to know only if a particular approach is available, not all three. Therefore, a programmer could use with an instance of the attribute containing only the flags the programmer needs. + + + +## Examples + The following code example verifies that the is a member of the collection and that it has been set to `true`. It assumes that `button1` and `textBox1` have been created on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic AttributeCollection.Matches Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AttributeCollection/Matches/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Matches/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AttributeCollection/Matches/source.vb" id="Snippet1"::: + ]]> @@ -1074,20 +1074,20 @@ if all the attributes in the array are contained in the collection and have the same values as the attributes in the collection; otherwise, . - diff --git a/xml/System.ComponentModel/AttributeProviderAttribute.xml b/xml/System.ComponentModel/AttributeProviderAttribute.xml index 7d009ce33d6..54b3f6c58d6 100644 --- a/xml/System.ComponentModel/AttributeProviderAttribute.xml +++ b/xml/System.ComponentModel/AttributeProviderAttribute.xml @@ -60,7 +60,7 @@ property is typed as `object`. The reason for this is that this property can accept several types of input. Unfortunately, this provides no common place to add metadata to describe the characteristics of the property. Each `DataSource` property throughout the .NET Framework needs to have identical metadata for type converters, UI type editors, and other services that require metadata. The remedies this situation. + There are a few cases in the .NET Framework object model where a property is purposely typed to be vague. For example, the property is typed as `object`. The reason for this is that this property can accept several types of input. Unfortunately, this provides no common place to add metadata to describe the characteristics of the property. Each `DataSource` property throughout the .NET Framework needs to have identical metadata for type converters, UI type editors, and other services that require metadata. The remedies this situation. Once this attribute is placed on a property, the rules for obtaining attributes for the property descriptor's collection differ. Typically, the property descriptor gathers local attributes, and then merges these with attributes from the property type. In this case, the attributes are taken from the type returned from the , not from the actual property type. This attribute is used on to point the object's specific type to , and the appropriate metadata is placed on to enable data binding. In so doing, external parties can easily add metadata to all data sources. diff --git a/xml/System.ComponentModel/BackgroundWorker.xml b/xml/System.ComponentModel/BackgroundWorker.xml index 29e8357b8ef..bea78c0d204 100644 --- a/xml/System.ComponentModel/BackgroundWorker.xml +++ b/xml/System.ComponentModel/BackgroundWorker.xml @@ -66,46 +66,46 @@ Executes an operation on a separate thread. - class allows you to run an operation on a separate, dedicated thread. Time-consuming operations like downloads and database transactions can cause your user interface (UI) to seem as though it has stopped responding while they are running. When you want a responsive UI and you are faced with long delays associated with such operations, the class provides a convenient solution. - - To execute a time-consuming operation in the background, create a and listen for events that report the progress of your operation and signal when your operation is finished. You can create the programmatically or you can drag it onto your form from the **Components** tab of the **Toolbox**. If you create the in the Windows Forms Designer, it will appear in the Component Tray, and its properties will be displayed in the Properties window. - - To set up for a background operation, add an event handler for the event. Call your time-consuming operation in this event handler. To start the operation, call . To receive notifications of progress updates, handle the event. To receive a notification when the operation is completed, handle the event. - + class allows you to run an operation on a separate, dedicated thread. Time-consuming operations like downloads and database transactions can cause your user interface (UI) to seem as though it has stopped responding while they are running. When you want a responsive UI and you are faced with long delays associated with such operations, the class provides a convenient solution. + + To execute a time-consuming operation in the background, create a and listen for events that report the progress of your operation and signal when your operation is finished. You can create the programmatically or you can drag it onto your form from the **Components** tab of the **Toolbox**. If you create the in the Windows Forms Designer, it will appear in the Component Tray, and its properties will be displayed in the Properties window. + + To set up for a background operation, add an event handler for the event. Call your time-consuming operation in this event handler. To start the operation, call . To receive notifications of progress updates, handle the event. To receive a notification when the operation is completed, handle the event. + > [!NOTE] -> You must be careful not to manipulate any user-interface objects in your event handler. Instead, communicate to the user interface through the and events. -> -> events are not marshaled across boundaries. Do not use a component to perform multithreaded operations in more than one . - - If your background operation requires a parameter, call with your parameter. Inside the event handler, you can extract the parameter from the property. - - For more information about , see [How to: Run an Operation in the Background](/dotnet/framework/winforms/controls/how-to-run-an-operation-in-the-background). - - - -## Examples - The following code example demonstrates the basics of the class for executing a time-consuming operation asynchronously. The following illustration shows an example of the output. - - ![BackgroundWorker simple example](~/add/media/backgroundworker-simple.png "BackgroundWorker simple example") - - To try this code, create a Windows Forms application. Add a control named `resultLabel` and add two controls named `startAsyncButton` and `cancelAsyncButton`. Create event handlers for both buttons. From the **Components** tab of the Toolbox, add a component named `backgroundWorker1`. Create , , and event handlers for the . In the code for the form, replace the existing code with the following code. - +> You must be careful not to manipulate any user-interface objects in your event handler. Instead, communicate to the user interface through the and events. +> +> events are not marshaled across boundaries. Do not use a component to perform multithreaded operations in more than one . + + If your background operation requires a parameter, call with your parameter. Inside the event handler, you can extract the parameter from the property. + + For more information about , see [How to: Run an Operation in the Background](/dotnet/framework/winforms/controls/how-to-run-an-operation-in-the-background). + + + +## Examples + The following code example demonstrates the basics of the class for executing a time-consuming operation asynchronously. The following illustration shows an example of the output. + + ![BackgroundWorker simple example](~/add/media/backgroundworker-simple.png "BackgroundWorker simple example") + + To try this code, create a Windows Forms application. Add a control named `resultLabel` and add two controls named `startAsyncButton` and `cancelAsyncButton`. Create event handlers for both buttons. From the **Components** tab of the Toolbox, add a component named `backgroundWorker1`. Create , , and event handlers for the . In the code for the form, replace the existing code with the following code. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/form1.vb" id="Snippet1"::: - - The following code example demonstrates the use of the class for executing a time-consuming operation asynchronously. The following illustration shows an example of the output. - - ![BackgroundWorker Fibonacci example](~/add/media/backgroundworker-fibonacci.png "BackgroundWorker Fibonacci example") - - The operation computes the selected Fibonacci number, reports progress updates as the calculation proceeds, and permits a pending calculation to be canceled. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/form1.vb" id="Snippet1"::: + + The following code example demonstrates the use of the class for executing a time-consuming operation asynchronously. The following illustration shows an example of the output. + + ![BackgroundWorker Fibonacci example](~/add/media/backgroundworker-fibonacci.png "BackgroundWorker Fibonacci example") + + The operation computes the selected Fibonacci number, reports progress updates as the calculation proceeds, and permits a pending calculation to be canceled. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet1"::: + ]]> How to: Run an Operation in the Background @@ -149,11 +149,11 @@ Initializes a new instance of the class. - . - + . + ]]> How to: Run an Operation in the Background @@ -200,25 +200,25 @@ Requests cancellation of a pending background operation. - submits a request to terminate the pending background operation and sets the property to `true`. - - When you call , your worker method has an opportunity to stop its execution and exit. The worker code should periodically check the property to see if it has been set to `true`. - + submits a request to terminate the pending background operation and sets the property to `true`. + + When you call , your worker method has an opportunity to stop its execution and exit. The worker code should periodically check the property to see if it has been set to `true`. + > [!CAUTION] -> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](/dotnet/standard/threading/managed-threading-best-practices). - - - -## Examples - The following code example demonstrates the use of the method to cancel an asynchronous ("background") operation. This code example is part of a larger example provided for the class. - +> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](/dotnet/standard/threading/managed-threading-best-practices). + + + +## Examples + The following code example demonstrates the use of the method to cancel an asynchronous ("background") operation. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet4"::: + ]]> @@ -278,22 +278,22 @@ if the application has requested cancellation of a background operation; otherwise, . The default is . - is `true`, then the method has been called on the . - - This property is meant for use by the worker thread, which should periodically check and abort the background operation when it is set to `true`. - - - -## Examples - The following code example demonstrates the use of the property to query a about its cancellation state. This code example is part of a larger example provided for the class. - + is `true`, then the method has been called on the . + + This property is meant for use by the worker thread, which should periodically check and abort the background operation when it is set to `true`. + + + +## Examples + The following code example demonstrates the use of the property to query a about its cancellation state. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet8"::: + ]]> How to: Run an Operation in the Background @@ -409,33 +409,33 @@ Occurs when is called. - method. This is where you start the operation that performs the potentially time-consuming work. - - Your code in the event handler should periodically check the property value and abort the operation if it is `true`. When this occurs, you can set the flag of to `true`, and the flag of in your event handler will be set to `true`. - + method. This is where you start the operation that performs the potentially time-consuming work. + + Your code in the event handler should periodically check the property value and abort the operation if it is `true`. When this occurs, you can set the flag of to `true`, and the flag of in your event handler will be set to `true`. + > [!CAUTION] -> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](/dotnet/standard/threading/managed-threading-best-practices). - - If your operation produces a result, you can assign the result to the property. This will be available to the event handler in the property. - - If the operation raises an exception that your code does not handle, the catches the exception and passes it into the event handler, where it is exposed as the property of . If you are running under the Visual Studio debugger, the debugger will break at the point in the event handler where the unhandled exception was raised. If you have more than one , you should not reference any of them directly, as this would couple your event handler to a specific instance of . Instead, you should access your by casting the `sender` parameter in your event handler. - - You must be careful not to manipulate any user-interface objects in your event handler. Instead, communicate to the user interface through the events. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates the use of the event to start an asynchronous operation. This code example is part of a larger example provided for the class. - +> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](/dotnet/standard/threading/managed-threading-best-practices). + + If your operation produces a result, you can assign the result to the property. This will be available to the event handler in the property. + + If the operation raises an exception that your code does not handle, the catches the exception and passes it into the event handler, where it is exposed as the property of . If you are running under the Visual Studio debugger, the debugger will break at the point in the event handler where the unhandled exception was raised. If you have more than one , you should not reference any of them directly, as this would couple your event handler to a specific instance of . Instead, you should access your by casting the `sender` parameter in your event handler. + + You must be careful not to manipulate any user-interface objects in your event handler. Instead, communicate to the user interface through the events. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following code example demonstrates the use of the event to start an asynchronous operation. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet5"::: + ]]> How to: Run an Operation in the Background @@ -494,19 +494,19 @@ , if the is running an asynchronous operation; otherwise, . - starts an asynchronous operation when you call . - - - -## Examples - The following code example demonstrates how to use the property to wait for completion of a operation. This code example is part of a larger example described in [How to: Download a File in the Background](/dotnet/framework/winforms/controls/how-to-download-a-file-in-the-background). - + starts an asynchronous operation when you call . + + + +## Examples + The following code example demonstrates how to use the property to wait for completion of a operation. This code example is part of a larger example described in [How to: Download a File in the Background](/dotnet/framework/winforms/controls/how-to-download-a-file-in-the-background). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/IsBusy/Form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/IsBusy/Form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/IsBusy/Form1.vb" id="Snippet2"::: + ]]> @@ -604,21 +604,21 @@ An that contains the event data. Raises the event. - method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - - - -## Examples - The following code example demonstrates the use of the method to report the progress of an asynchronous operation. This code example is part of a larger example provided for the class. - + method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + + + +## Examples + The following code example demonstrates the use of the method to report the progress of an asynchronous operation. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.cs" id="Snippet24"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet24"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AsyncCompletedEventArgs/Overview/primenumbercalculatormain.vb" id="Snippet24"::: + ]]> @@ -672,13 +672,13 @@ An that contains the event data. Raises the event. - method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -729,22 +729,22 @@ Occurs when is called. - method. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - - - -## Examples - The following code example demonstrates the use of the event to report the progress of an asynchronous operation to the user. This code example is part of a larger example provided for the class. - + method. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + + + +## Examples + The following code example demonstrates the use of the event to report the progress of an asynchronous operation to the user. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet7"::: + ]]> How to: Run an Operation in the Background @@ -810,24 +810,24 @@ The percentage, from 0 to 100, of the background operation that is complete. Raises the event. - method to raise the event. The property value must be `true`, or will throw an . - - It is up to you to implement a meaningful way of measuring your background operation's progress as a percentage of the total task completed. - - The call to the method is asynchronous and returns immediately. The event handler executes on the thread that created the . - - - -## Examples - The following code example demonstrates the use of the method to report the progress of an asynchronous operation to the user. This code example is part of a larger example provided for the class. - + method to raise the event. The property value must be `true`, or will throw an . + + It is up to you to implement a meaningful way of measuring your background operation's progress as a percentage of the total task completed. + + The call to the method is asynchronous and returns immediately. The event handler executes on the thread that created the . + + + +## Examples + The following code example demonstrates the use of the method to report the progress of an asynchronous operation to the user. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet8"::: + ]]> The property is set to . @@ -881,21 +881,21 @@ A unique indicating the user state. Returned as the property of the . Raises the event. - method to raise the event. The property value must `true`, or will throw an . - - It is up to you to implement a meaningful way of measuring your background operation's progress as a percentage of the total task completed. - - - -## Examples - The following code example demonstrates the use of the method to report the progress of an asynchronous operation to the user. This code example is part of a larger example provided for the class. - + method to raise the event. The property value must `true`, or will throw an . + + It is up to you to implement a meaningful way of measuring your background operation's progress as a percentage of the total task completed. + + + +## Examples + The following code example demonstrates the use of the method to report the progress of an asynchronous operation to the user. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/ReportProgress/form1.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/ReportProgress/form1.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/ReportProgress/form1.vb" id="Snippet10"::: + ]]> The property is set to . @@ -959,21 +959,21 @@ Starts execution of a background operation. - method submits a request to start the operation running asynchronously. When the request is serviced, the event is raised, which in turn starts execution of your background operation. - - If the background operation is already running, calling again will raise an . - - - -## Examples - The following code example demonstrates the use of the method to start an asynchronous operation. It is part of a larger example described in [How to: Download a File in the Background](/dotnet/framework/winforms/controls/how-to-download-a-file-in-the-background). - + method submits a request to start the operation running asynchronously. When the request is serviced, the event is raised, which in turn starts execution of your background operation. + + If the background operation is already running, calling again will raise an . + + + +## Examples + The following code example demonstrates the use of the method to start an asynchronous operation. It is part of a larger example described in [How to: Download a File in the Background](/dotnet/framework/winforms/controls/how-to-download-a-file-in-the-background). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/IsBusy/Form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/IsBusy/Form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/IsBusy/Form1.vb" id="Snippet2"::: + ]]> @@ -1028,24 +1028,24 @@ A parameter for use by the background operation to be executed in the event handler. Starts execution of a background operation. - method submits a request to start the operation running asynchronously. When the request is serviced, the event is raised, which in turn starts execution of your background operation. - - If your operation requires a parameter, you can provide it as the `argument` parameter to . - - If the background operation is already running, calling again will raise an . - - - -## Examples - The following code example demonstrates the use of the method to start an asynchronous operation. This code example is part of a larger example provided for the class. - + method submits a request to start the operation running asynchronously. When the request is serviced, the event is raised, which in turn starts execution of your background operation. + + If your operation requires a parameter, you can provide it as the `argument` parameter to . + + If the background operation is already running, calling again will raise an . + + + +## Examples + The following code example demonstrates the use of the method to start an asynchronous operation. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet3"::: + ]]> @@ -1096,31 +1096,31 @@ Occurs when the background operation has completed, has been canceled, or has raised an exception. - event handler returns. - - If the operation completes successfully and its result is assigned in the event handler, you can access the result through the property. - - The property of indicates that an exception was thrown by the operation. - - The property of indicates whether a cancellation request was processed by the background operation. If your code in the event handler detects a cancellation request by checking the flag and setting the flag of to `true`, the flag of also will be set to `true`. - + event handler returns. + + If the operation completes successfully and its result is assigned in the event handler, you can access the result through the property. + + The property of indicates that an exception was thrown by the operation. + + The property of indicates whether a cancellation request was processed by the background operation. If your code in the event handler detects a cancellation request by checking the flag and setting the flag of to `true`, the flag of also will be set to `true`. + > [!CAUTION] -> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](/dotnet/standard/threading/managed-threading-best-practices). - - Your event handler should always check the and properties before accessing the property. If an exception was raised or if the operation was canceled, accessing the property raises an exception. - - - -## Examples - The following code example demonstrates the use of the event to handle the result of an asynchronous operation. This code example is part of a larger example provided for the class. - +> Be aware that your code in the event handler may finish its work as a cancellation request is being made, and your polling loop may miss being set to `true`. In this case, the flag of in your event handler will not be set to `true`, even though a cancellation request was made. This situation is called a *race condition* and is a common concern in multithreaded programming. For more information about multithreading design issues, see [Managed Threading Best Practices](/dotnet/standard/threading/managed-threading-best-practices). + + Your event handler should always check the and properties before accessing the property. If an exception was raised or if the operation was canceled, accessing the property raises an exception. + + + +## Examples + The following code example demonstrates the use of the event to handle the result of an asynchronous operation. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet6"::: + ]]> How to: Run an Operation in the Background @@ -1182,11 +1182,11 @@ if the supports progress updates; otherwise . The default is . - property to `true` if you want the to support progress updates. When this property is `true`, user code can call the method to raise the event. - + property to `true` if you want the to support progress updates. When this property is `true`, user code can call the method to raise the event. + ]]> @@ -1249,11 +1249,11 @@ if the supports cancellation; otherwise . The default is . - property to `true` if you want the to support cancellation. When this property is `true`, you can call the method to interrupt a background operation. - + property to `true` if you want the to support cancellation. When this property is `true`, you can call the method to interrupt a background operation. + ]]> diff --git a/xml/System.ComponentModel/BindableAttribute.xml b/xml/System.ComponentModel/BindableAttribute.xml index acc5bf9f9c7..93745662b63 100644 --- a/xml/System.ComponentModel/BindableAttribute.xml +++ b/xml/System.ComponentModel/BindableAttribute.xml @@ -61,7 +61,7 @@ ## Remarks You can specify this attribute for multiple members, typically properties, on a control. - If a property has been marked with the set to `true`, then a property change notification should be raised for that property. This means that if the property is , then two-way data binding is supported. If is , you can still bind to the property, but it should not be shown in the default set of properties to bind to, because it might or might not raise a property change notification. + If a property has been marked with the set to `true`, then a property change notification should be raised for that property. This means that if the property is , then two-way data binding is supported. If is , you can still bind to the property, but it should not be shown in the default set of properties to bind to, because it might or might not raise a property change notification. > [!NOTE] > When you mark a property with set to `true`, the value of this attribute is set to the constant member . For a property marked with the set to `false`, the value is . Therefore, to check the value of this attribute in your code, you must specify the attribute as or . @@ -80,7 +80,7 @@ :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BindableAttribute/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BindableAttribute/Overview/source.vb" id="Snippet1"::: - The next code example shows how to check the value of the for `MyProperty`. First, the code gets a with all the properties for the object. Next, the code indexes into the to get `MyProperty`. Finally, the code returns the attributes for this property and saves them in the attributes variable. The code example presents two different ways to check the value of the . In the second code fragment, the example calls the method. In the last code fragment, the example uses the property to check the value. + The next code example shows how to check the value of the for `MyProperty`. First, the code gets a with all the properties for the object. Next, the code indexes into the to get `MyProperty`. Finally, the code returns the attributes for this property and saves them in the attributes variable. The code example presents two different ways to check the value of the . In the second code fragment, the example calls the method. In the last code fragment, the example uses the property to check the value. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic BindableAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BindableAttribute/Overview/source.cs" id="Snippet2"::: diff --git a/xml/System.ComponentModel/BindingList`1.xml b/xml/System.ComponentModel/BindingList`1.xml index 2d4328e5d1c..1c9c584e6b0 100644 --- a/xml/System.ComponentModel/BindingList`1.xml +++ b/xml/System.ComponentModel/BindingList`1.xml @@ -304,7 +304,7 @@ event occurs before a new object is added to the collection represented by the property. This event is raised after the method is called, but before the new item is created and added to the internal list. By handling this event, the programmer can provide custom item creation and insertion behavior without being forced to derive from the class. + The event occurs before a new object is added to the collection represented by the property. This event is raised after the method is called, but before the new item is created and added to the internal list. By handling this event, the programmer can provide custom item creation and insertion behavior without being forced to derive from the class. For more information about supplying custom new item functionality, see the method. For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). @@ -366,11 +366,11 @@ method adds a new item to the collection represented by the property. To add a new item, the following logic is used: + The method adds a new item to the collection represented by the property. To add a new item, the following logic is used: 1. The event is automatically raised. - This event can be programmatically handled to construct a new custom item. This is accomplished in the event handler by setting the property of the parameter to the new item. + This event can be programmatically handled to construct a new custom item. This is accomplished in the event handler by setting the property of the parameter to the new item. Otherwise, the new item is automatically created through its public parameterless constructor. @@ -454,7 +454,7 @@ method adds a new item to the collection represented by the property. raises the event. This allows you to add a new item by setting the property of the parameter to the new item. Otherwise, the new item is automatically created through its public parameterless constructor. + The method adds a new item to the collection represented by the property. raises the event. This allows you to add a new item by setting the property of the parameter to the new item. Otherwise, the new item is automatically created through its public parameterless constructor. ]]> @@ -515,12 +515,12 @@ property is typically used by other components to determine if editing of items in the list is allowed. When is set to a new value, a event of type will occur. + The property is typically used by other components to determine if editing of items in the list is allowed. When is set to a new value, a event of type will occur. ## Examples - The following code example demonstrates how to set the property. For the complete example, see the class overview topic. + The following code example demonstrates how to set the property. For the complete example, see the class overview topic. :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BindingListT/Overview/Form1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BindingListT/Overview/Form1.vb" id="Snippet2"::: @@ -574,14 +574,14 @@ property is typically used by other components to determine if the creation of new items is allowed. defaults to `true` if the type contained in the list has a parameterless constructor or the event is handled. If the event is not handled or the list type does not have a parameterless constructor, then defaults to `false`. + The property is typically used by other components to determine if the creation of new items is allowed. defaults to `true` if the type contained in the list has a parameterless constructor or the event is handled. If the event is not handled or the list type does not have a parameterless constructor, then defaults to `false`. If is explicitly set, the set value will always be used by bound objects to determine if new items can be added to the list. Whether is `true` or `false`, new items can be added by explicitly calling if the list type has a parameterless constructor or the event is handled. In addition, setting causes a event of type to occur. ## Examples - The following code example demonstrates how to set the property. For the complete example, see the class overview topic. + The following code example demonstrates how to set the property. For the complete example, see the class overview topic. :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BindingListT/Overview/Form1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BindingListT/Overview/Form1.vb" id="Snippet2"::: @@ -642,14 +642,14 @@ property is typically used by other components to determine if the removal of items is allowed. + The property is typically used by other components to determine if the removal of items is allowed. When is set to a new value, a event of type occurs. ## Examples - The following code example demonstrates how to set the property. For the complete example, see the class overview topic. + The following code example demonstrates how to set the property. For the complete example, see the class overview topic. :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BindingListT/Overview/Form1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BindingListT/Overview/Form1.vb" id="Snippet2"::: @@ -833,7 +833,7 @@ method removes all the items from the collection represented by the property. + The method removes all the items from the collection represented by the property. calls the method before clearing out the collection and raises the event after it has been cleared. @@ -954,7 +954,7 @@ ## Remarks The class does not provide a base implementation of searching, and so always throws a by default. To enable searching, derive from and perform the following tasks: -- Override to set the property to `true`. +- Override to set the property to `true`. - Override to implement the find algorithm. @@ -1318,7 +1318,7 @@ property to `false` if you wish to suppress events from occurring on the list. + Set the property to `false` if you wish to suppress events from occurring on the list. @@ -1867,7 +1867,7 @@ property indicates whether the supports sorting with the method. + The property indicates whether the supports sorting with the method. The class does not provide a base implementation of sorting, so always returns `false` by default. For more information about implementing sorting, see the method. @@ -2039,7 +2039,7 @@ property is typically used by other components to determine if editing of items in the list is allowed. + The property is typically used by other components to determine if editing of items in the list is allowed. ]]> diff --git a/xml/System.ComponentModel/BrowsableAttribute.xml b/xml/System.ComponentModel/BrowsableAttribute.xml index 9274398af12..7d314f3101c 100644 --- a/xml/System.ComponentModel/BrowsableAttribute.xml +++ b/xml/System.ComponentModel/BrowsableAttribute.xml @@ -78,7 +78,7 @@ The next example shows how to check the value of the for `MyProperty`. First, the code gets a with all the properties for the object. Next, the code indexes into the to get `MyProperty`. Then it returns the attributes for this property and saves them in the attributes variable. - The example presents two different ways of checking the value of the . In the second code fragment, the example calls the method. In the last code fragment, the example uses the property to check the value. + The example presents two different ways of checking the value of the . In the second code fragment, the example calls the method. In the last code fragment, the example uses the property to check the value. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic BrowsableAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BrowsableAttribute/Overview/source.cs" id="Snippet2"::: diff --git a/xml/System.ComponentModel/CancelEventArgs.xml b/xml/System.ComponentModel/CancelEventArgs.xml index 39714065fa7..e2a08295d3c 100644 --- a/xml/System.ComponentModel/CancelEventArgs.xml +++ b/xml/System.ComponentModel/CancelEventArgs.xml @@ -47,25 +47,25 @@ Provides data for a cancelable event. - event of a . - + event of a . + > [!NOTE] -> The event is deprecated and has been replaced by . It is offered as an example here only to illustrate the usage of . - - provides the property to indicate whether the event should be canceled. - - - -## Examples - The following example uses and a to handle the event of a . This code assumes that you have created a with a class-level variable named `isDataSaved`. It also assumes that you have added a statement to invoke the `OtherInitialize` method from the form's method or the constructor (after the call to `InitializeComponent`). - +> The event is deprecated and has been replaced by . It is offered as an example here only to illustrate the usage of . + + provides the property to indicate whether the event should be canceled. + + + +## Examples + The following example uses and a to handle the event of a . This code assumes that you have created a with a class-level variable named `isDataSaved`. It also assumes that you have added a statement to invoke the `OtherInitialize` method from the form's method or the constructor (after the call to `InitializeComponent`). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic CancelEventArgs Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CancelEventArgs/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CancelEventArgs/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CancelEventArgs/Overview/source.vb" id="Snippet1"::: + ]]> @@ -227,15 +227,15 @@ if the event should be canceled; otherwise, . - and a to handle the event of a . This code assumes that you have created a with a class-level variable named `isDataSaved`. It also assumes that you have added a statement to invoke the `OtherInitialize` method from the form's method or the constructor (after the call to `InitializeComponent`). - + and a to handle the event of a . This code assumes that you have created a with a class-level variable named `isDataSaved`. It also assumes that you have added a statement to invoke the `OtherInitialize` method from the form's method or the constructor (after the call to `InitializeComponent`). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic CancelEventArgs Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CancelEventArgs/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CancelEventArgs/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CancelEventArgs/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.ComponentModel/CategoryAttribute.xml b/xml/System.ComponentModel/CategoryAttribute.xml index 076aca36ccf..7abef1c564a 100644 --- a/xml/System.ComponentModel/CategoryAttribute.xml +++ b/xml/System.ComponentModel/CategoryAttribute.xml @@ -57,68 +57,68 @@ Specifies the name of the category in which to group the property or event when displayed in a control set to Categorized mode. - indicates the category to associate the associated property or event with, when listing properties or events in a control set to mode. If a has not been applied to a property or event, the associates it with the **Misc** category. A new category can be created for any name by specifying the name of the category in the constructor for the . - - The property indicates the name of the category that the attribute represents. The property also provides transparent localization of category names. - - - -## Examples - The following example creates the `MyImage` property. The property has two attributes: a and a . - + indicates the category to associate the associated property or event with, when listing properties or events in a control set to mode. If a has not been applied to a property or event, the associates it with the **Misc** category. A new category can be created for any name by specifying the name of the category in the constructor for the . + + The property indicates the name of the category that the attribute represents. The property also provides transparent localization of category names. + + + +## Examples + The following example creates the `MyImage` property. The property has two attributes: a and a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic CategoryAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CategoryAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CategoryAttribute/Overview/source.vb" id="Snippet1"::: - - The next example gets the category for `MyImage`. First, the code gets a with all the properties for the object. Next, the code indexes into the to get `MyImage`. Then it returns the attributes for this property and saves them in the variable `attributes`. - - The example then prints the category by retrieving from the , and writing it to the console screen. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CategoryAttribute/Overview/source.vb" id="Snippet1"::: + + The next example gets the category for `MyImage`. First, the code gets a with all the properties for the object. Next, the code indexes into the to get `MyImage`. Then it returns the attributes for this property and saves them in the variable `attributes`. + + The example then prints the category by retrieving from the , and writing it to the console screen. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic CategoryAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CategoryAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CategoryAttribute/Overview/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CategoryAttribute/Overview/source.vb" id="Snippet2"::: + ]]> - If you use category names other than the predefined names, and you want to localize your category names, you must override the method. - - The class defines the following common categories: - - Category - - Description - - Properties related to available actions. - - Properties related to how an entity appears. - - Properties related to how an entity acts. - - Properties related to data and data source management. - - Properties that are grouped in a default category. - - Properties that are available only at design time. - - Properties related to drag-and-drop operations. - - Properties related to focus. - - Properties related to formatting. - - Properties related to the keyboard. - - Properties related to layout. - - Properties related to the mouse. - - Properties related to the window style of top-level forms. - - + If you use category names other than the predefined names, and you want to localize your category names, you must override the method. + + The class defines the following common categories: + + Category + + Description + + Properties related to available actions. + + Properties related to how an entity appears. + + Properties related to how an entity acts. + + Properties related to data and data source management. + + Properties that are grouped in a default category. + + Properties that are available only at design time. + + Properties related to drag-and-drop operations. + + Properties related to focus. + + Properties related to formatting. + + Properties related to the keyboard. + + Properties related to layout. + + Properties related to the mouse. + + Properties related to the window style of top-level forms. + + For more information, see Attributes. @@ -223,13 +223,13 @@ The name of the category. Initializes a new instance of the class using the specified category name. - property. - - If the name you provide is not a predefined category name, and you do not override the method to provide a localized name, the category name will not be localized. - + property. + + If the name you provide is not a predefined category name, and you do not override the method to provide a localized name, the category name will not be localized. + ]]> @@ -446,11 +446,11 @@ Gets the name of the category for the property or event that this attribute is applied to. The name of the category for the property or event that this attribute is applied to. - to get the localized name of the category the first time it is accessed. - + to get the localized name of the category the first time it is accessed. + ]]> @@ -865,11 +865,11 @@ Looks up the localized name of the specified category. The localized name of the category, or if a localized name does not exist. - property calls this method the first time it is accessed to look up the localized name for the specified category. - + property calls this method the first time it is accessed to look up the localized name for the specified category. + ]]> diff --git a/xml/System.ComponentModel/ComplexBindingPropertiesAttribute.xml b/xml/System.ComponentModel/ComplexBindingPropertiesAttribute.xml index 5e893d4c7a6..19f7d2f7527 100644 --- a/xml/System.ComponentModel/ComplexBindingPropertiesAttribute.xml +++ b/xml/System.ComponentModel/ComplexBindingPropertiesAttribute.xml @@ -55,25 +55,25 @@ Specifies the data source and data member properties for a component that supports complex data binding. This class cannot be inherited. - is used to specify the properties used with complex data binding, such as binding based on . - - The attribute is specified at the class level. It is inheritable and does not allow multiple attributes on the same class. - - A control can support both simple binding, with , as well as complex binding. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following code example demonstrates using to identify a control's `DataSource` and `DataMember` properties for data binding. For a full code listing, see [How to: Apply Attributes in Windows Forms Controls](/dotnet/framework/winforms/controls/how-to-apply-attributes-in-windows-forms-controls). - + is used to specify the properties used with complex data binding, such as binding based on . + + The attribute is specified at the class level. It is inheritable and does not allow multiple attributes on the same class. + + A control can support both simple binding, with , as well as complex binding. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following code example demonstrates using to identify a control's `DataSource` and `DataMember` properties for data binding. For a full code listing, see [How to: Apply Attributes in Windows Forms Controls](/dotnet/framework/winforms/controls/how-to-apply-attributes-in-windows-forms-controls). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.cs" id="Snippet20"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.vb" id="Snippet20"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.vb" id="Snippet20"::: + ]]> @@ -127,11 +127,11 @@ Initializes a new instance of the class using no parameters. - and properties to `null`. - + and properties to `null`. + ]]> @@ -178,11 +178,11 @@ The name of the property to be used as the data source. Initializes a new instance of the class using the specified data source. - property to `dataSource` and the property to `null`. - + property to `dataSource` and the property to `null`. + ]]> @@ -237,11 +237,11 @@ The name of the property to be used as the source for data. Initializes a new instance of the class using the specified data source and data member. - property to `dataSource` and the property to `dataMember`. - + property to `dataSource` and the property to `dataMember`. + ]]> @@ -294,11 +294,11 @@ Gets the name of the data member property for the component to which the is bound. The name of the data member property for the component to which is bound. - property is set in the constructors for this class. - + property is set in the constructors for this class. + ]]> @@ -351,11 +351,11 @@ Gets the name of the data source property for the component to which the is bound. The name of the data source property for the component to which is bound. - property is set in the constructors for this class. - + property is set in the constructors for this class. + ]]> @@ -406,11 +406,11 @@ Represents the default value for the class. - member is a static, read-only field that defines an instance of the class initialized with the parameterless constructor. - + member is a static, read-only field that defines an instance of the class initialized with the parameterless constructor. + ]]> @@ -467,11 +467,11 @@ if the object is equal to the current instance; otherwise, , indicating they are not equal. - method returns `true` if `obj` is of type and the and properties of the two objects are equal. - + method returns `true` if `obj` is of type and the and properties of the two objects are equal. + ]]> diff --git a/xml/System.ComponentModel/Component.xml b/xml/System.ComponentModel/Component.xml index f3fa2fd148f..4df08582b0f 100644 --- a/xml/System.ComponentModel/Component.xml +++ b/xml/System.ComponentModel/Component.xml @@ -197,7 +197,7 @@ class should override this property to provide the ability to disable the raising of events. For example, in the class, if the control is being hosted as an ActiveX control, the property returns `false` if the ActiveX control has its events frozen. + The default implementation of this property always returns `true`. Classes that inherit from the class should override this property to provide the ability to disable the raising of events. For example, in the class, if the control is being hosted as an ActiveX control, the property returns `false` if the ActiveX control has its events frozen. ]]> @@ -790,7 +790,7 @@ will have an if it has been added to an and the assigns an to it. The is responsible for assigning the to the . Changing the value of the component's does not necessarily change the name of the site the is assigned to. The property should be set only by an . + A will have an if it has been added to an and the assigns an to it. The is responsible for assigning the to the . Changing the value of the component's does not necessarily change the name of the site the is assigned to. The property should be set only by an . The property value is `null` if the is removed from its . Assigning `null` to this property does not necessarily remove the from the . diff --git a/xml/System.ComponentModel/ComponentCollection.xml b/xml/System.ComponentModel/ComponentCollection.xml index 112f6b66928..bfd39cf3414 100644 --- a/xml/System.ComponentModel/ComponentCollection.xml +++ b/xml/System.ComponentModel/ComponentCollection.xml @@ -63,21 +63,21 @@ Provides a read-only container for a collection of objects. - . The only way to add objects to this collection is to use the class constructor. - - This collection provides two indexer properties, a string indexer and an integer indexer. The string indexer property returns a component in the collection by name if the property of a component in the collection is not `null` and the property of the property of the component matches the specified string. The integer indexer property returns the at the specified collection index. The method copies the contents of the collection to a specified array, beginning writing to the array at the specified index. - - - -## Examples - The following code example demonstrates how to use a to enumerate a collection of custom `BookComponent` objects. - + . The only way to add objects to this collection is to use the class constructor. + + This collection provides two indexer properties, a string indexer and an integer indexer. The string indexer property returns a component in the collection by name if the property of a component in the collection is not `null` and the property of the property of the component matches the specified string. The integer indexer property returns the at the specified collection index. The method copies the contents of the collection to a specified array, beginning writing to the array at the specified index. + + + +## Examples + The following code example demonstrates how to use a to enumerate a collection of custom `BookComponent` objects. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ComponentCollection/Overview/librarycontainer.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ComponentCollection/Overview/librarycontainer.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ComponentCollection/Overview/librarycontainer.vb" id="Snippet2"::: + ]]> @@ -123,19 +123,19 @@ An array of objects to initialize the collection with. Initializes a new instance of the class using the specified array of components. - in the specified array to the collection. - - - -## Examples - The following code example demonstrates how to create a from an array of `BookComponent` objects. - + in the specified array to the collection. + + + +## Examples + The following code example demonstrates how to create a from an array of `BookComponent` objects. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ComponentCollection/Overview/librarycontainer.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ComponentCollection/Overview/librarycontainer.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ComponentCollection/Overview/librarycontainer.vb" id="Snippet2"::: + ]]> @@ -242,11 +242,11 @@ Gets the in the collection at the specified collection index. The at the specified index. - If the specified index is not within the index range of the collection. @@ -297,16 +297,16 @@ Gets any component in the collection matching the specified name. A component with a name matching the name specified by the parameter, or if the named component cannot be found in the collection. - in the collection if its property is not `null` and the property of its property matches the specified string. - + in the collection if its property is not `null` and the property of its property matches the specified string. + > [!NOTE] -> This string indexer works only when the component is sited, which typically occurs only at design time. To site a at run time, set the property of the . The property of the set to the property must also be set for this property to return the component. - +> This string indexer works only when the component is sited, which typically occurs only at design time. To site a at run time, set the property of the . The property of the set to the property must also be set for this property to return the component. + ]]> diff --git a/xml/System.ComponentModel/ComponentResourceManager.xml b/xml/System.ComponentModel/ComponentResourceManager.xml index 7c1fc37b073..211bf4deccc 100644 --- a/xml/System.ComponentModel/ComponentResourceManager.xml +++ b/xml/System.ComponentModel/ComponentResourceManager.xml @@ -52,14 +52,14 @@ Provides simple functionality for enumerating resources for a component or object. The class is a . - to assign image resources to the property of controls. - + to assign image resources to the property of controls. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ComponentResourceManager/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ComponentResourceManager/Overview/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ComponentResourceManager/Overview/form1.vb" id="Snippet1"::: + ]]> @@ -164,14 +164,14 @@ A from which the derives all information for finding resource files. Creates a that looks up resources in satellite assemblies based on information from the specified . - to assign image resources to the property of controls. - + to assign image resources to the property of controls. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ComponentResourceManager/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ComponentResourceManager/Overview/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ComponentResourceManager/Overview/form1.vb" id="Snippet1"::: + ]]> @@ -241,11 +241,11 @@ A that contains the name of the object to look up in the resources. Applies a resource's value to the corresponding property of the object. - @@ -313,13 +313,13 @@ The culture for which to apply resources. Applies a resource's value to the corresponding property of the object. - method attempts to find a resource with a key in the format of `objectName.propertyName`, where `objectName` is passed in as a parameter and `propertyName` is the name of a property. It will then apply that resource's `value` to the corresponding property of the object. If there is no matching property, the resource will be ignored. - + method attempts to find a resource with a key in the format of `objectName.propertyName`, where `objectName` is passed in as a parameter and `propertyName` is the name of a property. It will then apply that resource's `value` to the corresponding property of the object. If there is no matching property, the resource will be ignored. + ]]> diff --git a/xml/System.ComponentModel/Container.xml b/xml/System.ComponentModel/Container.xml index f398ea2d1a6..276892768aa 100644 --- a/xml/System.ComponentModel/Container.xml +++ b/xml/System.ComponentModel/Container.xml @@ -740,7 +740,7 @@ method cleans up the site as usual, but it does not set the component's property to `null`. + The method cleans up the site as usual, but it does not set the component's property to `null`. ]]> diff --git a/xml/System.ComponentModel/CurrentChangingEventArgs.xml b/xml/System.ComponentModel/CurrentChangingEventArgs.xml index d5fd6a1b27d..4406bc49861 100644 --- a/xml/System.ComponentModel/CurrentChangingEventArgs.xml +++ b/xml/System.ComponentModel/CurrentChangingEventArgs.xml @@ -24,13 +24,13 @@ Provides information for the event. - raises this event when the is changing or when the content of the collection has been reset. - - By default, the event is cancelable when the cause is a move-current operation (such as the and similar methods) and uncancelable when the cause is an irreversible change operation on the collection. - + raises this event when the is changing or when the content of the collection has been reset. + + By default, the event is cancelable when the cause is a move-current operation (such as the and similar methods) and uncancelable when the cause is an irreversible change operation on the collection. + ]]> @@ -70,11 +70,11 @@ Initializes a new instance of the class. - property is `true`. - + property is `true`. + ]]> @@ -179,11 +179,11 @@ if the event is cancelable, otherwise, . The default value is . - and similar methods) and uncancelable when the cause is an irreversible change operation on the collection. - + and similar methods) and uncancelable when the cause is an irreversible change operation on the collection. + ]]> diff --git a/xml/System.ComponentModel/DataObjectAttribute.xml b/xml/System.ComponentModel/DataObjectAttribute.xml index a3883842621..1b8cd95f26a 100644 --- a/xml/System.ComponentModel/DataObjectAttribute.xml +++ b/xml/System.ComponentModel/DataObjectAttribute.xml @@ -55,21 +55,21 @@ Identifies a type as an object suitable for binding to an object. This class cannot be inherited. - attribute to identify an object as suitable for use by an object. Design-time classes such as the class use the attribute to present suitable objects to bind to an object. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following code example demonstrates how you can apply the attribute to indicate an object is suitable for binding to an object. In this example, the `NorthwindData` object is intended for use with an object. - + attribute to identify an object as suitable for use by an object. Design-time classes such as the class use the attribute to present suitable objects to bind to an object. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following code example demonstrates how you can apply the attribute to indicate an object is suitable for binding to an object. In this example, the `NorthwindData` object is intended for use with an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/CS/dataobjectmethodattribute.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet3"::: + ]]> @@ -125,19 +125,19 @@ Initializes a new instance of the class. - property is set to `true` when you use the constructor. - - - -## Examples - The following code example demonstrates using the constructor. - + property is set to `true` when you use the constructor. + + + +## Examples + The following code example demonstrates using the constructor. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/CS/dataobjectmethodattribute.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet3"::: + ]]> @@ -188,13 +188,13 @@ if the object is suitable for binding to an object; otherwise, . Initializes a new instance of the class and indicates whether an object is suitable for binding to an object. - constructor to indicate to a design-time class such as the class that an object should be excluded from the list of suitable objects for binding to an object. - - The property is set to the value of the `isDataObject` parameter. - + constructor to indicate to a design-time class such as the class that an object should be excluded from the list of suitable objects for binding to an object. + + The property is set to the value of the `isDataObject` parameter. + ]]> @@ -237,11 +237,11 @@ Indicates that the class is suitable for binding to an object at design time. This field is read-only. - field returns a new object with the property set to `true`. - + field returns a new object with the property set to `true`. + ]]> @@ -284,11 +284,11 @@ Represents the default value of the class, which indicates that the class is suitable for binding to an object at design time. This field is read-only. - field defines an instance of the class initialized with the constructor, which sets the property to `true`. - + field defines an instance of the class initialized with the constructor, which sets the property to `true`. + ]]> @@ -345,11 +345,11 @@ if this instance is the same as the instance specified by the parameter; otherwise, . - fits the pattern of another object. - + fits the pattern of another object. + ]]> @@ -525,11 +525,11 @@ Indicates that the class is not suitable for binding to an object at design time. This field is read-only. - field returns a new object with the property set to `false`. - + field returns a new object with the property set to `false`. + ]]> diff --git a/xml/System.ComponentModel/DataObjectFieldAttribute.xml b/xml/System.ComponentModel/DataObjectFieldAttribute.xml index 3f8e2587b9f..2a78a87837b 100644 --- a/xml/System.ComponentModel/DataObjectFieldAttribute.xml +++ b/xml/System.ComponentModel/DataObjectFieldAttribute.xml @@ -51,23 +51,23 @@ Provides metadata for a property representing a data field. This class cannot be inherited. - attribute to provide information about the schema of the underlying data. Design-time classes such as the class use the attribute to set properties at design-time based on the exposed schema. - - You apply the attribute to members of the data item objects that are returned by the Select method of an object marked with the attribute. In the following example, the `NorthwindData` class is marked with the attribute, and returns an object containing `NorthwindEmployee` objects from the `GetAllEmployees` method. Fields in the `NorthwindEmployee` class are marked with the attribute to indicate they represent data fields in the underlying data source. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following code example demonstrates how you can apply the to a publicly exposed property to identify metadata associated with the property. In this example the `NorthwindEmployee` type exposes three data properties: `EmployeeID`, `FirstName`, and `LastName`. The attribute is applied to all three properties; however, only the `EmployeeID` property attribute indicates it is the primary key for the data row. - + attribute to provide information about the schema of the underlying data. Design-time classes such as the class use the attribute to set properties at design-time based on the exposed schema. + + You apply the attribute to members of the data item objects that are returned by the Select method of an object marked with the attribute. In the following example, the `NorthwindData` class is marked with the attribute, and returns an object containing `NorthwindEmployee` objects from the `GetAllEmployees` method. Fields in the `NorthwindEmployee` class are marked with the attribute to indicate they represent data fields in the underlying data source. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following code example demonstrates how you can apply the to a publicly exposed property to identify metadata associated with the property. In this example the `NorthwindEmployee` type exposes three data properties: `EmployeeID`, `FirstName`, and `LastName`. The attribute is applied to all three properties; however, only the `EmployeeID` property attribute indicates it is the primary key for the data row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/CS/dataobjectmethodattribute.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet2"::: + ]]> @@ -233,14 +233,14 @@ to indicate that the field can be null in the data store; otherwise, . Initializes a new instance of the class and indicates whether the field is the primary key for the data row, whether the field is a database identity field, and whether the field can be null. - to a publicly exposed property to identify metadata associated with the property. In this example the `NorthwindEmployee` type exposes three data properties: `EmployeeID`, `FirstName`, and `LastName`. The attribute is applied to all three properties; however, only the `EmployeeID` property attribute indicates it is the primary key for the data row. - + to a publicly exposed property to identify metadata associated with the property. In this example the `NorthwindEmployee` type exposes three data properties: `EmployeeID`, `FirstName`, and `LastName`. The attribute is applied to all three properties; however, only the `EmployeeID` property attribute indicates it is the primary key for the data row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/CS/dataobjectmethodattribute.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet2"::: + ]]> @@ -353,11 +353,11 @@ if this instance is the same as the instance specified by the parameter; otherwise, . - fits the pattern of another object. - + fits the pattern of another object. + ]]> @@ -450,13 +450,13 @@ if the property represents an identity field in the underlying data; otherwise, . The default value is . - property to `true` when the attribute is applied to a property that represents an identity field in the underlying data store. Typically an identity field is generated by the data store and uniquely identifies an entity in the data store. - - Set the property with one of the constructors. - + property to `true` when the attribute is applied to a property that represents an identity field in the underlying data store. Typically an identity field is generated by the data store and uniquely identifies an entity in the data store. + + Set the property with one of the constructors. + ]]> @@ -507,13 +507,13 @@ if the property represents a field that can be null in the underlying data store; otherwise, . - property to `true` when then attribute is applied to a property that represents a field in the underlying data store that can be set to null. The value that represents null in the data store may be different from `null` in the programming language. - - Set the property with one of the constructors. - + property to `true` when then attribute is applied to a property that represents a field in the underlying data store that can be set to null. The value that represents null in the data store may be different from `null` in the programming language. + + Set the property with one of the constructors. + ]]> @@ -563,13 +563,13 @@ Gets the length of the property in bytes. The length of the property in bytes, or -1 if not set. - property to the length, in bytes, of the data from the underlying data store. If the property is not set, it will be -1. - - Set the property with one of the constructors. - + property to the length, in bytes, of the data from the underlying data store. If the property is not set, it will be -1. + + Set the property with one of the constructors. + ]]> @@ -620,13 +620,13 @@ if the property is in the primary key of the data store; otherwise, . - property to `true` when the attribute is applied to a property that represents the primary key value of the underlying data. The primary key is typically used by the underlying data store to uniquely identify an entity in the data store, and often is, but is not required to be, a data store identity field. - - Set the property with one of the constructors. - + property to `true` when the attribute is applied to a property that represents the primary key value of the underlying data. The primary key is typically used by the underlying data store to uniquely identify an entity in the data store, and often is, but is not required to be, a data store identity field. + + Set the property with one of the constructors. + ]]> diff --git a/xml/System.ComponentModel/DataObjectMethodAttribute.xml b/xml/System.ComponentModel/DataObjectMethodAttribute.xml index 73439ee5e79..ff045287950 100644 --- a/xml/System.ComponentModel/DataObjectMethodAttribute.xml +++ b/xml/System.ComponentModel/DataObjectMethodAttribute.xml @@ -55,19 +55,19 @@ Identifies a data operation method exposed by a type, what type of operation the method performs, and whether the method is the default data method. This class cannot be inherited. - to identify data operation methods on a type marked with the attribute so that they are more easily identified by callers using reflection. When the attribute is applied to a method, it describes the type of operation the method performs and indicates whether the method is the default data operation method of a type. Components such as the control and the class examine the values of this attribute, if present, to help determine which data method to call at run time. - - - -## Examples - The following code example demonstrates how you can apply the attribute to a publicly exposed method and identify the type of data operation it performs as well as whether it is the type's default data method. In this example the `NorthwindData` type exposes two data methods: one to retrieve a set of data named `GetAllEmployees`, and another to delete data named `DeleteEmployeeByID`. The attribute is applied to both methods, the `GetAllEmployees` method is marked as the default method for the Select data operation, and the `DeleteEmployeeByID` method is marked as the default method for the Delete data operation. - + to identify data operation methods on a type marked with the attribute so that they are more easily identified by callers using reflection. When the attribute is applied to a method, it describes the type of operation the method performs and indicates whether the method is the default data operation method of a type. Components such as the control and the class examine the values of this attribute, if present, to help determine which data method to call at run time. + + + +## Examples + The following code example demonstrates how you can apply the attribute to a publicly exposed method and identify the type of data operation it performs as well as whether it is the type's default data method. In this example the `NorthwindData` type exposes two data methods: one to retrieve a set of data named `GetAllEmployees`, and another to delete data named `DeleteEmployeeByID`. The attribute is applied to both methods, the `GetAllEmployees` method is marked as the default method for the Select data operation, and the `DeleteEmployeeByID` method is marked as the default method for the Delete data operation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/CS/dataobjectmethodattribute.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet3"::: + ]]> @@ -127,19 +127,19 @@ One of the values that describes the data operation the method performs. Initializes a new instance of the class and identifies the type of data operation the method performs. - property is set to `false` when you create a object using this constructor. - - - -## Examples - The following code example demonstrates how you can apply the attribute to a publicly exposed method and identify the type of data operation it performs as well as whether it is the type's default data method. In this example the `NorthwindData` type exposes two data methods: one to retrieve a set of data named `GetAllEmployees`, and another to delete data named `DeleteEmployeeByID`. The attribute is applied to both methods, the `GetAllEmployees` method is marked as the default method for the Select data operation, and the `DeleteEmployeeByID` method is marked as the default method for the Delete data operation. - + property is set to `false` when you create a object using this constructor. + + + +## Examples + The following code example demonstrates how you can apply the attribute to a publicly exposed method and identify the type of data operation it performs as well as whether it is the type's default data method. In this example the `NorthwindData` type exposes two data methods: one to retrieve a set of data named `GetAllEmployees`, and another to delete data named `DeleteEmployeeByID`. The attribute is applied to both methods, the `GetAllEmployees` method is marked as the default method for the Select data operation, and the `DeleteEmployeeByID` method is marked as the default method for the Delete data operation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/CS/dataobjectmethodattribute.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet3"::: + ]]> @@ -192,14 +192,14 @@ to indicate the method that the attribute is applied to is the default method of the data object for the specified ; otherwise, . Initializes a new instance of the class, identifies the type of data operation the method performs, and identifies whether the method is the default data method that the data object exposes. - attribute to a publicly exposed method and identify the type of data operation it performs as well as whether it is the type's default data method. In this example the `NorthwindData` type exposes two data methods: one to retrieve a set of data named `GetAllEmployees`, and another to delete data named `DeleteEmployeeByID`. The attribute is applied to both methods, the `GetAllEmployees` method is marked as the default method for the Select data operation, and the `DeleteEmployeeByID` method is marked as the default method for the Delete data operation. - + attribute to a publicly exposed method and identify the type of data operation it performs as well as whether it is the type's default data method. In this example the `NorthwindData` type exposes two data methods: one to retrieve a set of data named `GetAllEmployees`, and another to delete data named `DeleteEmployeeByID`. The attribute is applied to both methods, the `GetAllEmployees` method is marked as the default method for the Select data operation, and the `DeleteEmployeeByID` method is marked as the default method for the Delete data operation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/CS/dataobjectmethodattribute.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.ComponentModel.DataObjectMethodAttribute/VB/dataobjectmethodattribute.vb" id="Snippet3"::: + ]]> @@ -256,11 +256,11 @@ if this instance is the same as the instance specified by the parameter; otherwise, . - fits the pattern of another object. - + fits the pattern of another object. + ]]> @@ -353,15 +353,15 @@ if the method is the default method exposed by the object for a method type; otherwise, . - control uses the property to distinguish between multiple methods that match the signature requirements for a specific method type. If two methods match the signature requirements, the method with the property set to `true` is selected. - - At design-time the property is used to automatically set the , , , and properties on an instance. - - If the is created using the constructor that only takes a parameter, the property is set to `false`. - + control uses the property to distinguish between multiple methods that match the signature requirements for a specific method type. If two methods match the signature requirements, the method with the property set to `true` is selected. + + At design-time the property is used to automatically set the , , , and properties on an instance. + + If the is created using the constructor that only takes a parameter, the property is set to `false`. + ]]> @@ -418,11 +418,11 @@ if this instance is the same as the instance specified by the parameter; otherwise, . - fits the pattern of another. Its implementation is not the same as that of , however, because it does not test for true equality. - + fits the pattern of another. Its implementation is not the same as that of , however, because it does not test for true equality. + ]]> diff --git a/xml/System.ComponentModel/DateTimeConverter.xml b/xml/System.ComponentModel/DateTimeConverter.xml index 38007bd17f5..5e553afe1b9 100644 --- a/xml/System.ComponentModel/DateTimeConverter.xml +++ b/xml/System.ComponentModel/DateTimeConverter.xml @@ -54,29 +54,29 @@ Provides a type converter to convert objects to and from various other representations. - object to and from a string. - - The method uses the method of the class to convert from a string. - - The method uses the current culture, if a is not supplied. Generally, uses the property to format a date and with the property to format a date and time. If the property is passed, uses yyyy-MM-dd to format a date and to format a date and time. - - For more information about type converters, see the base class and [How to: Implement a Type Converter](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/ayybcxe5(v=vs.120)). - + object to and from a string. + + The method uses the method of the class to convert from a string. + + The method uses the current culture, if a is not supplied. Generally, uses the property to format a date and with the property to format a date and time. If the property is passed, uses yyyy-MM-dd to format a date and to format a date and time. + + For more information about type converters, see the base class and [How to: Implement a Type Converter](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/ayybcxe5(v=vs.120)). + > [!NOTE] -> You should never create an instance of . Instead, call the method of the class. For more information, see the examples in the base class. - - - -## Examples - The following code example converts a variable of type to a string, and vice versa. - +> You should never create an instance of . Instead, call the method of the class. For more information, see the examples in the base class. + + + +## Examples + The following code example converts a variable of type to a string, and vice versa. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Converters/CPP/converters.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BooleanConverter/Overview/converters.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BooleanConverter/Overview/converters.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BooleanConverter/Overview/converters.vb" id="Snippet9"::: + ]]> @@ -182,13 +182,13 @@ if this object can perform the conversion; otherwise, . - to and from a string. - - The `context` parameter can be used to extract additional information about the environment this converter is being invoked from. This can be `null`, so always check. Also, properties on the context object can return `null`. - + to and from a string. + + The `context` parameter can be used to extract additional information about the environment this converter is being invoked from. This can be `null`, so always check. Also, properties on the context object can return `null`. + ]]> @@ -250,11 +250,11 @@ if this converter can perform the conversion; otherwise, . - @@ -320,13 +320,13 @@ Converts the given value object to a . An that represents the converted . - to and from a string. - - The `context` parameter can be used to extract additional information about the environment this converter is being invoked from. This can be `null`, so always check. Also, properties on the context object can return `null`. - + to and from a string. + + The `context` parameter can be used to extract additional information about the environment this converter is being invoked from. This can be `null`, so always check. Also, properties on the context object can return `null`. + ]]> @@ -394,13 +394,13 @@ Converts the given value object to a using the arguments. An that represents the converted . - to and from a string. - - The `context` parameter can be used to extract additional information about the environment this converter is being invoked from. This can be `null`, so always check. Also, properties on the context object can return `null`. - + to and from a string. + + The `context` parameter can be used to extract additional information about the environment this converter is being invoked from. This can be `null`, so always check. Also, properties on the context object can return `null`. + ]]> The conversion cannot be performed. diff --git a/xml/System.ComponentModel/DefaultBindingPropertyAttribute.xml b/xml/System.ComponentModel/DefaultBindingPropertyAttribute.xml index 4e5bda4333f..501ce70cd44 100644 --- a/xml/System.ComponentModel/DefaultBindingPropertyAttribute.xml +++ b/xml/System.ComponentModel/DefaultBindingPropertyAttribute.xml @@ -55,21 +55,21 @@ Specifies the default binding property for a component. This class cannot be inherited. - is specified at the class level. It can be inherited and does not allow multiple attributes on the same class. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following code example demonstrates using the class to specify the default property for data binding. For a full code listing, see [How to: Apply Attributes in Windows Forms Controls](/dotnet/framework/winforms/controls/how-to-apply-attributes-in-windows-forms-controls). - + is specified at the class level. It can be inherited and does not allow multiple attributes on the same class. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following code example demonstrates using the class to specify the default property for data binding. For a full code listing, see [How to: Apply Attributes in Windows Forms Controls](/dotnet/framework/winforms/controls/how-to-apply-attributes-in-windows-forms-controls). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.cs" id="Snippet20"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.vb" id="Snippet20"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/AmbientValueAttribute/Overview/attributesdemocontrol.vb" id="Snippet20"::: + ]]> @@ -123,11 +123,11 @@ Initializes a new instance of the class using no parameters. - property to `null`. - + property to `null`. + ]]> @@ -179,11 +179,11 @@ The name of the default binding property. Initializes a new instance of the class using the specified property name. - property to the value of the `name` parameter. - + property to the value of the `name` parameter. + ]]> @@ -233,11 +233,11 @@ Represents the default value for the class. - member is a static, read-only field that defines an instance of the class initialized with the parameterless constructor. - + member is a static, read-only field that defines an instance of the class initialized with the parameterless constructor. + ]]> @@ -294,11 +294,11 @@ if the object is equal to the current instance; otherwise, , indicating they are not equal. - method returns `true` if the value of the `obj` parameter is of type and the properties of the two objects are equal. - + method returns `true` if the value of the `obj` parameter is of type and the properties of the two objects are equal. + ]]> @@ -394,11 +394,11 @@ Gets the name of the default binding property for the component to which the is bound. The name of the default binding property for the component to which the is bound. - property is set in the constructor. - + property is set in the constructor. + ]]> diff --git a/xml/System.ComponentModel/DefaultEventAttribute.xml b/xml/System.ComponentModel/DefaultEventAttribute.xml index 7c97bf301ef..b26f2c59c6c 100644 --- a/xml/System.ComponentModel/DefaultEventAttribute.xml +++ b/xml/System.ComponentModel/DefaultEventAttribute.xml @@ -58,28 +58,28 @@ Specifies the default event for a component. - property to get the name of the default event. - - For more information, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following example defines a collection class named `MyCollection`. The class is marked with a that specifies `CollectionChanged` as the default event. - + property to get the name of the default event. + + For more information, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following example defines a collection class named `MyCollection`. The class is marked with a that specifies `CollectionChanged` as the default event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DefaultEventAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DefaultEventAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DefaultEventAttribute/Overview/source.vb" id="Snippet1"::: - - The next example creates an instance of `MyCollection`. Then it gets the attributes for the class, extracts the , and prints the name of the default event. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DefaultEventAttribute/Overview/source.vb" id="Snippet1"::: + + The next example creates an instance of `MyCollection`. Then it gets the attributes for the class, extracts the , and prints the name of the default event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DefaultEventAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DefaultEventAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DefaultEventAttribute/Overview/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DefaultEventAttribute/Overview/source.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.ComponentModel/DefaultPropertyAttribute.xml b/xml/System.ComponentModel/DefaultPropertyAttribute.xml index be376b8038f..5348919990b 100644 --- a/xml/System.ComponentModel/DefaultPropertyAttribute.xml +++ b/xml/System.ComponentModel/DefaultPropertyAttribute.xml @@ -58,28 +58,28 @@ Specifies the default property for a component. - property to get the name of the default property. - - For more information, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following example defines a control named `MyControl`. The class is marked with a that specifies `MyProperty` as the default property. - + property to get the name of the default property. + + For more information, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following example defines a control named `MyControl`. The class is marked with a that specifies `MyProperty` as the default property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DefaultPropertyAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DefaultPropertyAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DefaultPropertyAttribute/Overview/source.vb" id="Snippet1"::: - - The next example creates an instance of `MyControl`. Then it gets the attributes for the class, extracts the , and prints the name of the default property. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DefaultPropertyAttribute/Overview/source.vb" id="Snippet1"::: + + The next example creates an instance of `MyControl`. Then it gets the attributes for the class, extracts the , and prints the name of the default property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DefaultPropertyAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DefaultPropertyAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DefaultPropertyAttribute/Overview/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DefaultPropertyAttribute/Overview/source.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.ComponentModel/DescriptionAttribute.xml b/xml/System.ComponentModel/DescriptionAttribute.xml index 1a49820dab9..927962d0668 100644 --- a/xml/System.ComponentModel/DescriptionAttribute.xml +++ b/xml/System.ComponentModel/DescriptionAttribute.xml @@ -57,30 +57,30 @@ Specifies a description for a property or event. - to access the value of this attribute. - - For more information, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following example creates the `MyImage` property. The property has two attributes, a and a . - + to access the value of this attribute. + + For more information, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following example creates the `MyImage` property. The property has two attributes, a and a . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DescriptionAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DescriptionAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DescriptionAttribute/Overview/source.vb" id="Snippet1"::: - - The next example gets the description of `MyImage`. First the code gets a with all the properties for the object. Next it indexes into the to get `MyImage`. Then it returns the attributes for this property and saves them in the attributes variable. - - The example then prints the description by retrieving from the , and writing it to the console screen. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DescriptionAttribute/Overview/source.vb" id="Snippet1"::: + + The next example gets the description of `MyImage`. First the code gets a with all the properties for the object. Next it indexes into the to get `MyImage`. Then it returns the attributes for this property and saves them in the attributes variable. + + The example then prints the description by retrieving from the , and writing it to the console screen. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DescriptionAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DescriptionAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DescriptionAttribute/Overview/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DescriptionAttribute/Overview/source.vb" id="Snippet2"::: + ]]> @@ -329,13 +329,13 @@ Gets or sets the string stored as the description. The string stored as the description. The default value is an empty string (""). - property simply returns this value. - - This extra property exists so that you can derive from and provide a localized version. The derived localizable will maintain a private Boolean field to indicate if it has been localized. On the first access to the property, it will look up the localized string and store it back in the property. - + property simply returns this value. + + This extra property exists so that you can derive from and provide a localized version. The derived localizable will maintain a private Boolean field to indicate if it has been localized. On the first access to the property, it will look up the localized string and store it back in the property. + ]]> @@ -482,11 +482,11 @@ , if this is the default instance; otherwise, . - diff --git a/xml/System.ComponentModel/DesignerAttribute.xml b/xml/System.ComponentModel/DesignerAttribute.xml index 0c5b98c6c05..d31f6f98307 100644 --- a/xml/System.ComponentModel/DesignerAttribute.xml +++ b/xml/System.ComponentModel/DesignerAttribute.xml @@ -67,30 +67,30 @@ Specifies the class used to implement design-time services for a component. - interface. - - Use the property to find the designer's base type. Use the property to get the name of the type of designer associated with this member. - - For more information, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following example creates a class called `MyForm`. `MyForm` has two attributes, a that specifies this class uses the , and a that specifies the category. - + interface. + + Use the property to find the designer's base type. Use the property to get the name of the type of designer associated with this member. + + For more information, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following example creates a class called `MyForm`. `MyForm` has two attributes, a that specifies this class uses the , and a that specifies the category. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DesignerAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DesignerAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DesignerAttribute/Overview/source.vb" id="Snippet1"::: - - The next example creates an instance of `MyForm`. Then it gets the attributes for the class, extracts the , and prints the name of the designer. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DesignerAttribute/Overview/source.vb" id="Snippet1"::: + + The next example creates an instance of `MyForm`. Then it gets the attributes for the class, extracts the , and prints the name of the designer. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DesignerAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DesignerAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DesignerAttribute/Overview/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/DesignerAttribute/Overview/source.vb" id="Snippet2"::: + ]]> @@ -157,11 +157,11 @@ The concatenation of the fully qualified name of the type that provides design-time services for the component this attribute is bound to, and the name of the assembly this type resides in. Initializes a new instance of the class using the name of the type that provides design-time services. - interface. - + interface. + ]]> @@ -217,11 +217,11 @@ A that represents the class that provides design-time services for the component this attribute is bound to. Initializes a new instance of the class using the type that provides design-time services. - interface. - + interface. + ]]> @@ -286,13 +286,13 @@ The fully qualified name of the base class to associate with the designer class. Initializes a new instance of the class using the designer type and the base class for the designer. - interface. - - The `designerBaseTypeName` parameter allows you to attach more than one type of designer for a given class. - + interface. + + The `designerBaseTypeName` parameter allows you to attach more than one type of designer for a given class. + ]]> @@ -357,13 +357,13 @@ A that represents the base class to associate with the . Initializes a new instance of the class, using the name of the designer class and the base class for the designer. - interface. - - The `designerBaseType` parameter allows you to attach more than one type of designer for a given class. - + interface. + + The `designerBaseType` parameter allows you to attach more than one type of designer for a given class. + ]]> @@ -428,13 +428,13 @@ A that represents the base class to associate with the . Initializes a new instance of the class using the types of the designer and designer base class. - interface. - - The `designerBaseType` parameter allows you to attach more than one type of designer for a given class. - + interface. + + The `designerBaseType` parameter allows you to attach more than one type of designer for a given class. + ]]> @@ -695,11 +695,11 @@ Gets a unique ID for this attribute type. A unique ID for this attribute type. - instance for the attribute. overrides this to include the type of the designer base type. - + instance for the attribute. overrides this to include the type of the designer base type. + ]]> diff --git a/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml b/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml index 62836ebc99b..7ab7795c972 100644 --- a/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml +++ b/xml/System.ComponentModel/DesignerSerializationVisibilityAttribute.xml @@ -196,7 +196,7 @@ property is set to . + When you mark a property with `DesignerSerializationVisibilityAttribute.Content`, the value of its property is set to . ]]> @@ -401,7 +401,7 @@ property is set to the constant member . + When you mark a property with `DesignerSerializationVisibilityAttribute.Hidden`, the value of its property is set to the constant member . ]]> @@ -506,7 +506,7 @@ ## Examples The following code example shows how to check the value of the for `MyProperty`. First the code gets a with all the properties for the object. Next, the code indexes into the to get `MyProperty`. Then, the code returns the attributes for this property and saves them in the attributes variable. - This example presents two different ways to check the value of the . In the second code fragment, the example calls the method with a `static` value. In the last code fragment, the example uses the property to check the value. + This example presents two different ways to check the value of the . In the second code fragment, the example calls the method with a `static` value. In the last code fragment, the example uses the property to check the value. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic DesignerSerializationVisibilityAttribute.Visibility Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/DesignerSerializationVisibilityAttribute/Visibility/source.cs" id="Snippet1"::: diff --git a/xml/System.ComponentModel/EditorAttribute.xml b/xml/System.ComponentModel/EditorAttribute.xml index de805584fdf..795c38ba788 100644 --- a/xml/System.ComponentModel/EditorAttribute.xml +++ b/xml/System.ComponentModel/EditorAttribute.xml @@ -67,32 +67,32 @@ Specifies the editor to use to change a property. This class cannot be inherited. - property to find this editor's base type. The only available base type is . - - Use the property to get the name of the type of editor associated with this attribute. - - For general information on using attributes. see [Attributes](/dotnet/standard/attributes/). For more information on design-time attributes, see [Attributes and Design-Time Support](/previous-versions/visualstudio/visual-studio-2013/a19191fh(v=vs.120)). - - - -## Examples - The following code example creates the `MyImage` class. The class is marked with an that specifies the as its editor. - + property to find this editor's base type. The only available base type is . + + Use the property to get the name of the type of editor associated with this attribute. + + For general information on using attributes. see [Attributes](/dotnet/standard/attributes/). For more information on design-time attributes, see [Attributes and Design-Time Support](/previous-versions/visualstudio/visual-studio-2013/a19191fh(v=vs.120)). + + + +## Examples + The following code example creates the `MyImage` class. The class is marked with an that specifies the as its editor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EditorAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EditorAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EditorAttribute/Overview/source.vb" id="Snippet1"::: - - The following code example creates an instance of the `MyImage` class, gets the attributes for the class, and then prints the name of the editor used by `myNewImage`. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EditorAttribute/Overview/source.vb" id="Snippet1"::: + + The following code example creates an instance of the `MyImage` class, gets the attributes for the class, and then prints the name of the editor used by `myNewImage`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EditorAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EditorAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EditorAttribute/Overview/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EditorAttribute/Overview/source.vb" id="Snippet2"::: + ]]> @@ -214,15 +214,15 @@ The fully qualified type name of the base class or interface to use as a lookup key for the editor. This class must be or derive from . Initializes a new instance of the class with the type name and base type name of the editor. - format. - - The represented by the `typeName` parameter must either derive from or implement the base class. - - The represented by the `baseTypeName` parameter is used as a key to find a particular editor, because a data type can have more than one editor associated with it. This can be any class, but is typically or . - + format. + + The represented by the `typeName` parameter must either derive from or implement the base class. + + The represented by the `baseTypeName` parameter is used as a key to find a particular editor, because a data type can have more than one editor associated with it. This can be any class, but is typically or . + ]]> @@ -287,15 +287,15 @@ The of the base class or interface to use as a lookup key for the editor. This class must be or derive from . Initializes a new instance of the class with the type name and the base type. - format. - - The represented by the `typeName` must either derive from or implement the base class. - - The `baseType` parameter is used as a key to find a particular editor, because a data type can have more than one editor associated with it. - + format. + + The represented by the `typeName` must either derive from or implement the base class. + + The `baseType` parameter is used as a key to find a particular editor, because a data type can have more than one editor associated with it. + ]]> @@ -360,13 +360,13 @@ The of the base class or interface to use as a lookup key for the editor. This class must be or derive from . Initializes a new instance of the class with the type and the base type. - represented by the `type` parameter must either derive from or implement the base class. - - The `baseType` parameter is used as a key to find a particular editor, because a data type can have more than one editor associated with it. - + represented by the `type` parameter must either derive from or implement the base class. + + The `baseType` parameter is used as a key to find a particular editor, because a data type can have more than one editor associated with it. + ]]> @@ -430,11 +430,11 @@ Gets the name of the base class or interface serving as a lookup key for this editor. The name of the base class or interface serving as a lookup key for this editor. - property is an assembly qualified type name. The .NET Framework provides both and as valid base classes, but any value is valid here. - + property is an assembly qualified type name. The .NET Framework provides both and as valid base classes, but any value is valid here. + ]]> @@ -639,11 +639,11 @@ Gets a unique ID for this attribute type. A unique ID for this attribute type. - property is used by filtering algorithms to identify two attributes that are the same type. For most attributes, this just returns the instance for the attribute. overrides this to include the type of the editor base type. - + property is used by filtering algorithms to identify two attributes that are the same type. For most attributes, this just returns the instance for the attribute. overrides this to include the type of the editor base type. + ]]> diff --git a/xml/System.ComponentModel/EnumConverter.xml b/xml/System.ComponentModel/EnumConverter.xml index 2e838ea043e..4fad65afe8b 100644 --- a/xml/System.ComponentModel/EnumConverter.xml +++ b/xml/System.ComponentModel/EnumConverter.xml @@ -54,27 +54,27 @@ Provides a type converter to convert objects to and from various other representations. - class provides the property to get an interface that can be used to sort the values of the enumeration. By default, the enumeration values are sorted in the order they appear in the file. - - For more information about type converters, see the base class and [How to: Implement a Type Converter](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/ayybcxe5(v=vs.120)). - + class provides the property to get an interface that can be used to sort the values of the enumeration. By default, the enumeration values are sorted in the order they appear in the file. + + For more information about type converters, see the base class and [How to: Implement a Type Converter](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/ayybcxe5(v=vs.120)). + > [!NOTE] > You should never create an instance of an . Instead, call the method of the class. For more information, see the examples in the base class. -## Examples - The following code example converts a variable of type to a string, and vice versa. The example requires that you have declared an called `Servers` and that it has the following members: - -``` -Windows=1, Exchange=2, BizTalk=3 -``` - +## Examples + The following code example converts a variable of type to a string, and vice versa. The example requires that you have declared an called `Servers` and that it has the following members: + +``` +Windows=1, Exchange=2, BizTalk=3 +``` + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Converters/CPP/converters.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BooleanConverter/Overview/converters.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BooleanConverter/Overview/converters.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BooleanConverter/Overview/converters.vb" id="Snippet12"::: + ]]> @@ -196,13 +196,13 @@ Windows=1, Exchange=2, BizTalk=3 if this converter can perform the conversion; otherwise, . - @@ -264,11 +264,11 @@ Windows=1, Exchange=2, BizTalk=3 if this converter can perform the conversion; otherwise, . - @@ -328,11 +328,11 @@ Windows=1, Exchange=2, BizTalk=3 Gets an that can be used to sort the values of the enumeration. An for sorting the enumeration values. - @@ -397,13 +397,13 @@ Windows=1, Exchange=2, BizTalk=3 Converts the specified value object to an enumeration object. An that represents the converted . - @@ -471,16 +471,16 @@ Windows=1, Exchange=2, BizTalk=3 Converts the given value object to the specified destination type. An that represents the converted . - [!NOTE] -> The behavior of the method is undefined if the enumeration has multiple fields with the same value. - +> The behavior of the method is undefined if the enumeration has multiple fields with the same value. + ]]> @@ -600,14 +600,14 @@ Windows=1, Exchange=2, BizTalk=3 Gets a collection of standard values for the data type this validator is designed for. A that holds a standard set of valid values, or if the data type does not support a standard set of values. - [!NOTE] -> Any fields of the enumeration that are marked with set to `false` will not be returned. - +> Any fields of the enumeration that are marked with set to `false` will not be returned. + ]]> @@ -660,11 +660,11 @@ Windows=1, Exchange=2, BizTalk=3 if the returned from is an exhaustive list of possible values; if other values are possible. - @@ -717,11 +717,11 @@ Windows=1, Exchange=2, BizTalk=3 because should be called to find a common set of values the object supports. This method never returns . - @@ -776,11 +776,11 @@ Windows=1, Exchange=2, BizTalk=3 if the specified value is valid for this object; otherwise, . - diff --git a/xml/System.ComponentModel/EventDescriptorCollection.xml b/xml/System.ComponentModel/EventDescriptorCollection.xml index 759507296f6..30753027167 100644 --- a/xml/System.ComponentModel/EventDescriptorCollection.xml +++ b/xml/System.ComponentModel/EventDescriptorCollection.xml @@ -69,24 +69,24 @@ Represents a collection of objects. - is read-only; it does not implement methods that add or remove events. You must inherit from this class to implement these methods. - - Using the properties available in the class, you can query the collection about its contents. Use the property to determine the number of elements in the collection. Use the property to get a specific property by index number or by name. - - You can also use the method to get a description of the event with the specified name from the collection. - - - -## Examples - The following code example prints all the events on a button in a text box. It requires that `button1` and `textBox1` have been instantiated on a form. - + is read-only; it does not implement methods that add or remove events. You must inherit from this class to implement these methods. + + Using the properties available in the class, you can query the collection about its contents. Use the property to determine the number of elements in the collection. Use the property to get a specific property by index number or by name. + + You can also use the method to get a description of the event with the specified name from the collection. + + + +## Examples + The following code example prints all the events on a button in a text box. It requires that `button1` and `textBox1` have been instantiated on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Overview/source.vb" id="Snippet1"::: + ]]> @@ -152,22 +152,22 @@ An array of type that provides the events for this collection. Initializes a new instance of the class with the given array of objects. - class. - - The attribute applied to this member has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example creates a new class using the events on `button1`. It requires that `button1` has been instantiated on a form. - + class. + + The attribute applied to this member has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example creates a new class using the events on `button1`. It requires that `button1` has been instantiated on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.EventDescriptorCollection Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/.ctor/source.vb" id="Snippet1"::: + ]]> @@ -231,23 +231,23 @@ to specify a read-only collection; otherwise, . Initializes a new instance of the class with the given array of objects. The collection is optionally read-only. - class. - + class. + > [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example creates a new class using the events on `button1`. It requires that `button1` has been instantiated on a form. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example creates a new class using the events on `button1`. It requires that `button1` has been instantiated on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.EventDescriptorCollection Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/.ctor/source.vb" id="Snippet1"::: + ]]> @@ -300,13 +300,13 @@ Adds an to the end of the collection. The position of the within the collection. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. @@ -359,13 +359,13 @@ Removes all objects from the collection. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. @@ -418,13 +418,13 @@ if the collection contains the parameter given; otherwise, . - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -479,23 +479,23 @@ Gets the number of event descriptors in the collection. The number of event descriptors in the collection. - property can be used to set the limits of a loop that iterates through a collection of objects. If the collection is zero-based, be sure to use `Count - 1` as the upper boundary of the loop. - + property can be used to set the limits of a loop that iterates through a collection of objects. If the collection is zero-based, be sure to use `Count - 1` as the upper boundary of the loop. + > [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example uses the property to print the number of events attached to `button1`. It requires that `button1` and `textBox1` have been instantiated on a form. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example uses the property to print the number of events attached to `button1`. It requires that `button1` and `textBox1` have been instantiated on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.Count Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/Count/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Count/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Count/source.vb" id="Snippet1"::: + ]]> @@ -605,22 +605,22 @@ Gets the description of the event with the specified name in the collection. The with the specified name, or if the event does not exist. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example finds a specific . It prints the type of component for this in a text box. It requires that `button1` and `textBox1` have been instantiated on a form. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example finds a specific . It prints the type of component for this in a text box. It requires that `button1` and `textBox1` have been instantiated on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.Find Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/Find/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Find/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Find/source.vb" id="Snippet1"::: + ]]> @@ -675,22 +675,22 @@ Gets an enumerator for this . An enumerator that implements . - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example gets an enumerator for the events on `button1`. It uses the enumerator to print the names of the events in the collection. It requires that `button1` and `textBox1` have been instantiated on a form. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example gets an enumerator for the events on `button1`. It uses the enumerator to print the names of the events in the collection. It requires that `button1` and `textBox1` have been instantiated on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.GetEnumerator Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/GetEnumerator/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/GetEnumerator/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/GetEnumerator/source.vb" id="Snippet1"::: + ]]> @@ -744,13 +744,13 @@ Returns the index of the given . The index of the given within the collection. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -802,13 +802,13 @@ An to insert into the collection. Inserts an to the collection at a specified index. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. @@ -869,14 +869,14 @@ A comparer to use to sort the objects in this collection. Sorts the members of this , using the specified . - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -934,22 +934,22 @@ An array of strings describing the order in which to sort the objects in this collection. Sorts the members of this . The specified order is applied first, followed by the default sort for this collection, which is usually alphabetical. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example defines the sort order for the method. If the contains four objects with the names `A`, `B`, `C`, and `D`, the properties of this would be sorted in the order `D`, `B`, `A`, and `C`. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example defines the sort order for the method. If the contains four objects with the names `A`, `B`, `C`, and `D`, the properties of this would be sorted in the order `D`, `B`, `A`, and `C`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.InternalSort Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/InternalSort/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/InternalSort/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/InternalSort/source.vb" id="Snippet1"::: + ]]> @@ -1011,20 +1011,20 @@ Gets or sets the event with the specified index number. The with the specified index number. - to access that . For example, to get the third , you need to specify `myColl[2]`. - - - -## Examples - The following code example uses the property to print the name of the specified by the index number in a text box. Because the index number is zero-based, this example prints the name of the second . It requires that `button1` and `textBox1` have been instantiated on a form. - + to access that . For example, to get the third , you need to specify `myColl[2]`. + + + +## Examples + The following code example uses the property to print the name of the specified by the index number in a text box. Because the index number is zero-based, this example prints the name of the second . It requires that `button1` and `textBox1` have been instantiated on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.this Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/Item/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Item/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Item/source.vb" id="Snippet1"::: + ]]> @@ -1084,23 +1084,23 @@ Gets or sets the event with the specified name. The with the specified name, or if the event does not exist. - property is case-sensitive when searching for names. That is, the names "Ename" and "ename" are considered to be two different events. - + property is case-sensitive when searching for names. That is, the names "Ename" and "ename" are considered to be two different events. + > [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example uses the property to print the type of the component for the specified by the index. It requires that `button1` and `textBox1` have been instantiated on a form. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example uses the property to print the type of the component for the specified by the index. It requires that `button1` and `textBox1` have been instantiated on a form. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.this1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/Item/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Item/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Item/source1.vb" id="Snippet1"::: + ]]> @@ -1152,13 +1152,13 @@ The to remove from the collection. Removes the specified from the collection. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. @@ -1214,13 +1214,13 @@ The index of the to remove. Removes the at the specified index from the collection. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. @@ -1278,22 +1278,22 @@ Sorts the members of this , using the default sort for this collection, which is usually alphabetical. The new . - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example defines the sort order for the method. If the contains four objects with the names `A`, `B`, `C`, and `D`, the properties of `myNewColl` would be sorted in the order `D`, `B`, `A`, and `C`. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example defines the sort order for the method. If the contains four objects with the names `A`, `B`, `C`, and `D`, the properties of `myNewColl` would be sorted in the order `D`, `B`, `A`, and `C`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.Sort Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/Sort/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Sort/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Sort/source.vb" id="Snippet1"::: + ]]> @@ -1343,23 +1343,23 @@ Sorts the members of this , using the specified . The new . - is applied first, followed by the default sort for this collection, which is usually alphabetical. - + is applied first, followed by the default sort for this collection, which is usually alphabetical. + > [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example defines the sort order for the method. If the contains four objects with the names `A`, `B`, `C`, and `D`, the properties of `myNewColl` would be sorted in the order `D`, `B`, `A`, and `C`. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example defines the sort order for the method. If the contains four objects with the names `A`, `B`, `C`, and `D`, the properties of `myNewColl` would be sorted in the order `D`, `B`, `A`, and `C`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.Sort Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/Sort/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Sort/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Sort/source.vb" id="Snippet1"::: + ]]> @@ -1410,23 +1410,23 @@ Sorts the members of this , given a specified sort order. The new . - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example defines the sort order for the method. If the contains four objects with the names `A`, `B`, `C`, and `D`, the properties of `myNewColl` would be sorted in the order `D`, `B`, `A`, and `C`. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example defines the sort order for the method. If the contains four objects with the names `A`, `B`, `C`, and `D`, the properties of `myNewColl` would be sorted in the order `D`, `B`, `A`, and `C`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.Sort Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/Sort/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Sort/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Sort/source.vb" id="Snippet1"::: + ]]> @@ -1479,23 +1479,23 @@ Sorts the members of this , given a specified sort order and an . The new . - . - + . + > [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example defines the sort order for the method. If the contains four objects with the names `A`, `B`, `C`, and `D`, the properties of `myNewColl` would be sorted in the order `D`, `B`, `A`, and `C`. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example defines the sort order for the method. If the contains four objects with the names `A`, `B`, `C`, and `D`, the properties of `myNewColl` would be sorted in the order `D`, `B`, `A`, and `C`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic EventDescriptorCollection.Sort Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/EventDescriptorCollection/Sort/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Sort/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/EventDescriptorCollection/Sort/source.vb" id="Snippet1"::: + ]]> @@ -1551,13 +1551,13 @@ The zero-based index in at which copying begins. Copies the elements of the collection to an , starting at a particular index. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -1610,13 +1610,13 @@ Gets the number of elements contained in the collection. The number of elements contained in the collection. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -1665,13 +1665,13 @@ if access to the collection is synchronized; otherwise, . - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -1725,13 +1725,13 @@ Gets an object that can be used to synchronize access to the collection. An object that can be used to synchronize access to the collection. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -1787,13 +1787,13 @@ Returns an enumerator that iterates through a collection. An that can be used to iterate through the collection. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -1847,13 +1847,13 @@ Adds an item to the collection. The position into which the new element was inserted. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. @@ -1908,13 +1908,13 @@ Removes all the items from the collection. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. @@ -1970,13 +1970,13 @@ if the is found in the collection; otherwise, . - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -2030,13 +2030,13 @@ Determines the index of a specific item in the collection. The index of if found in the list; otherwise, -1. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -2091,13 +2091,13 @@ The to insert into the collection. Inserts an item to the collection at the specified index. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. @@ -2147,13 +2147,13 @@ if the collection has a fixed size; otherwise, . - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -2202,13 +2202,13 @@ if the collection is read-only; otherwise, . - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -2267,21 +2267,21 @@ Gets or sets the element at the specified index. The element at the specified index. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. - is less than 0. - - -or- - + is less than 0. + + -or- + is equal to or greater than . @@ -2333,13 +2333,13 @@ The to remove from the collection. Removes the first occurrence of a specific object from the collection. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. @@ -2397,13 +2397,13 @@ The zero-based index of the item to remove. Removes the item at the specified index. - [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> The collection is read-only. diff --git a/xml/System.ComponentModel/HandledEventArgs.xml b/xml/System.ComponentModel/HandledEventArgs.xml index f49c1694a56..7be725d9ef4 100644 --- a/xml/System.ComponentModel/HandledEventArgs.xml +++ b/xml/System.ComponentModel/HandledEventArgs.xml @@ -47,13 +47,13 @@ Provides data for events that can be handled completely in an event handler. - property is set in an event handler to indicate that the system should perform no further processing. - - This class is a base class for types such as the , , , and classes. - + property is set in an event handler to indicate that the system should perform no further processing. + + This class is a base class for types such as the , , , and classes. + ]]> diff --git a/xml/System.ComponentModel/HandledEventHandler.xml b/xml/System.ComponentModel/HandledEventHandler.xml index 610ed7f3db9..d883fe17e17 100644 --- a/xml/System.ComponentModel/HandledEventHandler.xml +++ b/xml/System.ComponentModel/HandledEventHandler.xml @@ -63,13 +63,13 @@ A that contains the event data. Represents a method that can handle events which may or may not require further processing after the event handler has returned. - property provides sufficient event data. The event handler can set the property to `true` if all necessary processing has been completed in the handler. - - Typically, events that require this functionality will also require additional event data, and will use a class that derives from along with a corresponding, similarly-named delegate type. For example, the event uses the event-data type and the delegate type. Because delegates are not inherited, the is rarely used. - + property provides sufficient event data. The event handler can set the property to `true` if all necessary processing has been completed in the handler. + + Typically, events that require this functionality will also require additional event data, and will use a class that derives from along with a corresponding, similarly-named delegate type. For example, the event uses the event-data type and the delegate type. Because delegates are not inherited, the is rarely used. + ]]> diff --git a/xml/System.ComponentModel/IBindingList.xml b/xml/System.ComponentModel/IBindingList.xml index 024722c048b..ef43a268acf 100644 --- a/xml/System.ComponentModel/IBindingList.xml +++ b/xml/System.ComponentModel/IBindingList.xml @@ -55,26 +55,26 @@ Provides the features required to support both complex and simple scenarios when binding to a data source. - class. Implementation of a method should exhibit the same behavior as the implementation of that method in the class. - - When you call the or methods, you should raise a event with the enumeration. - - When you call the method, you should raise a event with the enumeration carrying the appropriate index. The added row is in a state where pressing the ESC on a control can remove the new row. Raising the event with the enumeration a second time on this row indicates that the item is now a row not in the "new" state. - - When you remove an item or call the method on a new row (if that row implements ), you should raise a event with the enumeration carrying the appropriate index. - - - -## Examples - The following example provides a simple implementation of the interface. The `CustomerList` class stores customer information in a list. This example assumes that you have used the `Customer` class that can be found in the example in the class. - + class. Implementation of a method should exhibit the same behavior as the implementation of that method in the class. + + When you call the or methods, you should raise a event with the enumeration. + + When you call the method, you should raise a event with the enumeration carrying the appropriate index. The added row is in a state where pressing the ESC on a control can remove the new row. Raising the event with the enumeration a second time on this row indicates that the item is now a row not in the "new" state. + + When you remove an item or call the method on a new row (if that row implements ), you should raise a event with the enumeration carrying the appropriate index. + + + +## Examples + The following example provides a simple implementation of the interface. The `CustomerList` class stores customer information in a list. This example assumes that you have used the `Customer` class that can be found in the example in the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Binding_Editable/CPP/binding_editable.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/IBindingList/Overview/binding_editable.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/IBindingList/Overview/binding_editable.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/IBindingList/Overview/binding_editable.vb" id="Snippet2"::: + ]]> @@ -122,11 +122,11 @@ The to add to the indexes used for searching. Adds the to the indexes used for searching. - @@ -173,18 +173,18 @@ Adds a new item to the list. The item added to the list. - is `true`; otherwise, a is thrown. - - Implementing this method means that the list must understand the type of objects to add to the list and must understand how to create a new instance of that type. For example, if you have a collection of `myCustomer` objects, the method should add a new `myCustomer` object to the list. - + is `true`; otherwise, a is thrown. + + Implementing this method means that the list must understand the type of objects to add to the list and must understand how to create a new instance of that type. For example, if you have a collection of `myCustomer` objects, the method should add a new `myCustomer` object to the list. + > [!NOTE] -> If the objects in this list implement the interface, calling the method should discard an object, not add it to the list, when the object was created using the method. The object should only be added to the list when the method is called. Therefore, you must synchronize the object and the list carefully. - - When this method is called, you should raise a event with the enumeration carrying the appropriate index. The added row is in a state where hitting Esc on a control can remove the new row. Raising the event with the enumeration a second time on this row indicates that the item is now a normal row (not in new state). - +> If the objects in this list implement the interface, calling the method should discard an object, not add it to the list, when the object was created using the method. The object should only be added to the list when the method is called. Therefore, you must synchronize the object and the list carefully. + + When this method is called, you should raise a event with the enumeration carrying the appropriate index. The added row is in a state where hitting Esc on a control can remove the new row. Raising the event with the enumeration a second time on this row indicates that the item is now a normal row (not in new state). + ]]> @@ -275,11 +275,11 @@ if you can add items to the list using ; otherwise, . - or is `true`, this property returns `false`. - + or is `true`, this property returns `false`. + ]]> @@ -325,14 +325,14 @@ if you can remove items from the list; otherwise, . - or is `true`, this property returns `false`. - + or is `true`, this property returns `false`. + > [!NOTE] -> If returns `false`, and throw a . - +> If returns `false`, and throw a . + ]]> @@ -382,13 +382,13 @@ One of the values. Sorts the list based on a and a . - is `true`; otherwise, this method throws a . - + is `true`; otherwise, this method throws a . + ]]> @@ -444,21 +444,21 @@ Returns the index of the row that has the given . The index of the row that has the given . - is `true`, otherwise this method throws a . - - - -## Examples - The following code example demonstrates how to implement the method. - + is `true`, otherwise this method throws a . + + + +## Examples + The following code example demonstrates how to implement the method. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BindingListT/FindCore/Form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BindingListT/FindCore/Form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BindingListT/FindCore/Form1.vb" id="Snippet3"::: + ]]> @@ -506,13 +506,13 @@ if has been called and has not been called; otherwise, . - is `true`; otherwise, this property throws a . - - If returns `true`, items are added or removed in the order of the sort. - + is `true`; otherwise, this property throws a . + + If returns `true`, items are added or removed in the order of the sort. + ]]> @@ -558,11 +558,11 @@ Occurs when the list changes or an item in the list changes. - property is `true`. - + property is `true`. + ]]> @@ -610,11 +610,11 @@ The to remove from the indexes used for searching. Removes the from the indexes used for searching. - @@ -659,13 +659,13 @@ Removes any sort applied using . - is `true`; otherwise, this property throws a . - - When you call this method, you should raise a event with the enumeration. - + is `true`; otherwise, this property throws a . + + When you call this method, you should raise a event with the enumeration. + ]]> @@ -712,11 +712,11 @@ Gets the direction of the sort. One of the values. - is `true`; otherwise, this property throws a . - + is `true`; otherwise, this property throws a . + ]]> @@ -770,11 +770,11 @@ Gets the that is being used for sorting. The that is being used for sorting. - is `true`; otherwise, this property throws a . - + is `true`; otherwise, this property throws a . + ]]> @@ -822,11 +822,11 @@ if a event is raised when the list changes or when an item changes; otherwise, . - event. - + event. + ]]> @@ -872,14 +872,14 @@ if the list supports searching using the method; otherwise, . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BindingListT/FindCore/Form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BindingListT/FindCore/Form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BindingListT/FindCore/Form1.vb" id="Snippet3"::: + ]]> @@ -925,11 +925,11 @@ if the list supports sorting; otherwise, . - , , , , and are supported. - + , , , , and are supported. + ]]> diff --git a/xml/System.ComponentModel/IBindingListView.xml b/xml/System.ComponentModel/IBindingListView.xml index c665267aee5..b5a7cda93bd 100644 --- a/xml/System.ComponentModel/IBindingListView.xml +++ b/xml/System.ComponentModel/IBindingListView.xml @@ -60,11 +60,11 @@ Extends the interface by providing advanced sorting and filtering capabilities. - interface, you implement advanced sorting as a set of property descriptor-direction pairs. You implement filtering as a string to be interpreted by the data source implementation. The interface is implemented by the class. - + interface, you implement advanced sorting as a set of property descriptor-direction pairs. You implement filtering as a string to be interpreted by the data source implementation. The interface is implemented by the class. + ]]> @@ -111,11 +111,11 @@ The containing the sorts to apply to the data source. Sorts the data source based on the given . - is a read-only collection, once constructed. - + is a read-only collection, once constructed. + ]]> @@ -171,11 +171,11 @@ Gets or sets the filter to be used to exclude items from the collection of items returned by the data source. The string used to filter items out in the item collection returned by the data source. - property should exhibit the following behavior when the property is set: The data source returns only the items that meet the filter criteria when the list is accessed by item index or when the list is enumerated. The definition of the filter string is dependent on the data-source implementation, but the behavior associated with setting the filter should be modeled on . - + property should exhibit the following behavior when the property is set: The data source returns only the items that meet the filter criteria when the list is accessed by item index or when the list is enumerated. The definition of the filter string is dependent on the data-source implementation, but the behavior associated with setting the filter should be modeled on . + ]]> @@ -220,11 +220,11 @@ Removes the current filter applied to the data source. - type, you implement filtering as a string to be interpreted by the data source implementation. - + type, you implement filtering as a string to be interpreted by the data source implementation. + ]]> @@ -274,11 +274,11 @@ Gets the collection of sort descriptions currently applied to the data source. The currently applied to the data source. - is a read-only collection, once constructed. - + is a read-only collection, once constructed. + ]]> @@ -323,11 +323,11 @@ if the data source supports advanced sorting; otherwise, . - @@ -372,11 +372,11 @@ if the data source supports filtering; otherwise, . - property, you implement filtering as a string to be interpreted by the data source implementation. - + property, you implement filtering as a string to be interpreted by the data source implementation. + ]]> diff --git a/xml/System.ComponentModel/ICollectionView.xml b/xml/System.ComponentModel/ICollectionView.xml index c495d1a0d1d..0f224378736 100644 --- a/xml/System.ComponentModel/ICollectionView.xml +++ b/xml/System.ComponentModel/ICollectionView.xml @@ -29,11 +29,11 @@ Enables collections to have the functionalities of current record management, custom sorting, filtering, and grouping. - class, which is the base class for , , and . - + class, which is the base class for , , and . + ]]> @@ -163,11 +163,11 @@ if the item belongs to this collection view; otherwise, . - @@ -229,11 +229,11 @@ When implementing this interface, raise this event after the current item has been changed. - event and check the property value before changing the currency and raising event. - + event and check the property value before changing the currency and raising event. + ]]> @@ -266,11 +266,11 @@ When implementing this interface, raise this event before changing the current item. Event handler can cancel this event. - event and check the property value before changing the currency and raising event. - + event and check the property value before changing the currency and raising event. + ]]> diff --git a/xml/System.ComponentModel/ICollectionViewLiveShaping.xml b/xml/System.ComponentModel/ICollectionViewLiveShaping.xml index c293fd56436..c9b5537ea1c 100644 --- a/xml/System.ComponentModel/ICollectionViewLiveShaping.xml +++ b/xml/System.ComponentModel/ICollectionViewLiveShaping.xml @@ -21,16 +21,16 @@ Defines properties that enables sorting, grouping, and filtering on a in real time. - will rearrange the position of data in the when the data is modified. For example, suppose that an application uses a to list stocks in a stock market and the stocks are sorted by stock value. If live sorting is enabled on the stocks' , a stock's position in the moves when the value of the stock becomes greater or less than another stock's value. - - The , , and classes implement the interface. The class also implements the properties defined by to enable setting the properties in XAML. - -## Notes for Inheritors - Implement this interface on your custom to support sorting, grouping, and filtering data in real time. Your can implement the sorting, grouping, and filtering operations itself, or you can delegate one or more of them to another object, such as the underlying collection. If you delegate the shaping operations, the might not have control over whether live shaping is enabled. Your must accept the behavior of the object to which it delegates. In this case, set the appropriate **CanChange*** properties to `false`. If your knows whether the delegate object supports live shaping, it can set the appropriate `IsLive`* properties to the known value. Otherwise, the should set the `IsLive`* properties to `null`. - + will rearrange the position of data in the when the data is modified. For example, suppose that an application uses a to list stocks in a stock market and the stocks are sorted by stock value. If live sorting is enabled on the stocks' , a stock's position in the moves when the value of the stock becomes greater or less than another stock's value. + + The , , and classes implement the interface. The class also implements the properties defined by to enable setting the properties in XAML. + +## Notes for Inheritors + Implement this interface on your custom to support sorting, grouping, and filtering data in real time. Your can implement the sorting, grouping, and filtering operations itself, or you can delegate one or more of them to another object, such as the underlying collection. If you delegate the shaping operations, the might not have control over whether live shaping is enabled. Your must accept the behavior of the object to which it delegates. In this case, set the appropriate **CanChange*** properties to `false`. If your knows whether the delegate object supports live shaping, it can set the appropriate `IsLive`* properties to the known value. Otherwise, the should set the `IsLive`* properties to `null`. + ]]> @@ -62,13 +62,13 @@ if the collection view supports turning live filtering on or off; otherwise, . - can implement live filtering itself, or you can delegate live filtering to another object, such as the underlying collection. If you delegate live filtering, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. In this case, set the property to `false`. - + can implement live filtering itself, or you can delegate live filtering to another object, such as the underlying collection. If you delegate live filtering, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. In this case, set the property to `false`. + ]]> @@ -100,13 +100,13 @@ if the collection view supports turning live grouping on or off; otherwise, . - can implement live grouping itself, or you can delegate live grouping to another object, such as the underlying collection. If you delegate live grouping, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. In this case, set the property to `false`. - + can implement live grouping itself, or you can delegate live grouping to another object, such as the underlying collection. If you delegate live grouping, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. In this case, set the property to `false`. + ]]> @@ -138,13 +138,13 @@ if the collection view supports turning live sorting on or off; otherwise, . - can implement live sorting itself, or you can delegate live sorting to another object, such as the underlying collection. If you delegate live sorting, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. In this case, set the property to `false`. - + can implement live sorting itself, or you can delegate live sorting to another object, such as the underlying collection. If you delegate live sorting, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. In this case, set the property to `false`. + ]]> @@ -176,13 +176,13 @@ if filtering data in real time is enabled; if live filtering is not enabled; if it cannot be determined whether the collection view implements live filtering. - can implement live filtering itself, or you can delegate live filtering to another object, such as the underlying collection. If you delegate live filtering, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. If your knows whether the delegate object supports live filtering, set the property to the known value. Otherwise, set to `null`. - + can implement live filtering itself, or you can delegate live filtering to another object, such as the underlying collection. If you delegate live filtering, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. If your knows whether the delegate object supports live filtering, set the property to the known value. Otherwise, set to `null`. + ]]> @@ -214,13 +214,13 @@ if grouping data in real time is enable; if live grouping is not enabled; if it cannot be determined whether the collection view implements live grouping. - can implement live grouping itself, or you can delegate live grouping to another object, such as the underlying collection. If you delegate live grouping, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. If your knows whether the delegate object supports live grouping, set the property to the known value. Otherwise, set to `null`. - + can implement live grouping itself, or you can delegate live grouping to another object, such as the underlying collection. If you delegate live grouping, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. If your knows whether the delegate object supports live grouping, set the property to the known value. Otherwise, set to `null`. + ]]> @@ -252,13 +252,13 @@ if sorting data in real time is enable; if live sorting is not enabled; if it cannot be determined whether the collection view implements live sorting. - can implement live sorting itself, or you can delegate live sorting to another object, such as the underlying collection. If you delegate live sorting, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. If your knows whether the delegate object supports live sorting, set the property to the known value. Otherwise, set to `null`. - + can implement live sorting itself, or you can delegate live sorting to another object, such as the underlying collection. If you delegate live sorting, the might not have control over whether it is enabled. Your must accept the behavior of the object to which it delegates. If your knows whether the delegate object supports live sorting, set the property to the known value. Otherwise, set to `null`. + ]]> diff --git a/xml/System.ComponentModel/IEditableCollectionView.xml b/xml/System.ComponentModel/IEditableCollectionView.xml index fde62b537fa..fe602dce372 100644 --- a/xml/System.ComponentModel/IEditableCollectionView.xml +++ b/xml/System.ComponentModel/IEditableCollectionView.xml @@ -27,7 +27,7 @@ ## Remarks When a collection view implements the interface, you can directly change the underlying collection, if it allows changes to be made, by using the methods and properties that exposes, regardless of the collection's type. - The types , , and are the types that ship with Windows Presentation Foundation (WPF) that inherit from . These types also implement the , so you can edit a collection that uses one of those types. , in particular, is often used because the property is an . + The types , , and are the types that ship with Windows Presentation Foundation (WPF) that inherit from . These types also implement the , so you can edit a collection that uses one of those types. , in particular, is often used because the property is an . diff --git a/xml/System.ComponentModel/IEditableCollectionViewAddNewItem.xml b/xml/System.ComponentModel/IEditableCollectionViewAddNewItem.xml index 3c8fba49f07..aad0904cee4 100644 --- a/xml/System.ComponentModel/IEditableCollectionViewAddNewItem.xml +++ b/xml/System.ComponentModel/IEditableCollectionViewAddNewItem.xml @@ -41,7 +41,7 @@ ## Examples - The following example enables a user to add various types of items to a collection. The user can enter a new item and submit the entry or cancel the transaction. The example gets an from the property of a and creates an object, whose type is determined by the user. Then the example calls the method to add the object to the collection. + The following example enables a user to add various types of items to a collection. The user can enter a new item and submit the entry or cancel the transaction. The example gets an from the property of a and creates an object, whose type is determined by the user. Then the example calls the method to add the object to the collection. :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/IEditableCollectionViewAddNewItem/Overview/window1.xaml.cs" id="Snippetmainwindowlogic"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/IEditableCollectionViewAddNewItem/Overview/window1.xaml.vb" id="Snippetmainwindowlogic"::: @@ -147,7 +147,7 @@ property is `true`, you can specify an object to add to the collection by calling the method. is `false` if items cannot be added to the collection by using . If is `false`, you may still be able to add an object by using the method. For example, you can add objects to an ADO.NET source by using , but not by using . + If the property is `true`, you can specify an object to add to the collection by calling the method. is `false` if items cannot be added to the collection by using . If is `false`, you may still be able to add an object by using the method. For example, you can add objects to an ADO.NET source by using , but not by using . ]]> diff --git a/xml/System.ComponentModel/IExtenderProvider.xml b/xml/System.ComponentModel/IExtenderProvider.xml index 1041f9aeda5..008c8345aa7 100644 --- a/xml/System.ComponentModel/IExtenderProvider.xml +++ b/xml/System.ComponentModel/IExtenderProvider.xml @@ -46,23 +46,23 @@ Defines the interface for extending properties to other components in a container. - control is an extender provider. When you add a control to a , all other controls on the form have a property added to their list of properties. - - Any component that provides extender properties must implement . A visual designer can then call to determine which objects in a container should receive the extender properties. - - For more information about extender providers, see [How to: Implement an Extender Provider](/previous-versions/visualstudio/visual-studio-2013/d6c1xa43(v=vs.120)). - - - -## Examples - The following code example demonstrates how to implement the interface. This example is part of a larger example discussed in [How to: Implement a HelpLabel Extender Provider](/previous-versions/visualstudio/visual-studio-2013/ms229066(v=vs.120)). - + control is an extender provider. When you add a control to a , all other controls on the form have a property added to their list of properties. + + Any component that provides extender properties must implement . A visual designer can then call to determine which objects in a container should receive the extender properties. + + For more information about extender providers, see [How to: Implement an Extender Provider](/previous-versions/visualstudio/visual-studio-2013/d6c1xa43(v=vs.120)). + + + +## Examples + The following code example demonstrates how to implement the interface. This example is part of a larger example discussed in [How to: Implement a HelpLabel Extender Provider](/previous-versions/visualstudio/visual-studio-2013/ms229066(v=vs.120)). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/IExtenderProvider/Overview/HelpLabel.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/IExtenderProvider/Overview/HelpLabel.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/IExtenderProvider/Overview/HelpLabel.vb" id="Snippet1"::: + ]]> @@ -113,19 +113,19 @@ if this object can provide extender properties to the specified object; otherwise, . - property. This example is part of a larger example discussed in [How to: Implement a HelpLabel Extender Provider](/previous-versions/visualstudio/visual-studio-2013/ms229066(v=vs.120)). - + property. This example is part of a larger example discussed in [How to: Implement a HelpLabel Extender Provider](/previous-versions/visualstudio/visual-studio-2013/ms229066(v=vs.120)). + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/IExtenderProvider/Overview/HelpLabel.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/IExtenderProvider/Overview/HelpLabel.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/IExtenderProvider/Overview/HelpLabel.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.ComponentModel/IListSource.xml b/xml/System.ComponentModel/IListSource.xml index 05e97a2680c..4b1d77921e9 100644 --- a/xml/System.ComponentModel/IListSource.xml +++ b/xml/System.ComponentModel/IListSource.xml @@ -77,7 +77,7 @@ - -- Implementer of , provided the implementer has a strongly typed property (that is, the is anything but ). You can accomplish this by making the default implementation of private. If you want to create an that follows the rules of a strongly typed collection, you should derive from . +- Implementer of , provided the implementer has a strongly typed property (that is, the is anything but ). You can accomplish this by making the default implementation of private. If you want to create an that follows the rules of a strongly typed collection, you should derive from . - Implementer of . diff --git a/xml/System.ComponentModel/INestedSite.xml b/xml/System.ComponentModel/INestedSite.xml index 7964a29264c..ebae062b6cd 100644 --- a/xml/System.ComponentModel/INestedSite.xml +++ b/xml/System.ComponentModel/INestedSite.xml @@ -101,11 +101,11 @@ Gets the full name of the component in this site. The full name of the component in this site. - property returns the full name of the component in this site in the format of [*owner*].[*component*]*.* If this component's site has a null name, the property also returns `null`. - + property returns the full name of the component in this site in the format of [*owner*].[*component*]*.* If this component's site has a null name, the property also returns `null`. + ]]> diff --git a/xml/System.ComponentModel/ISite.xml b/xml/System.ComponentModel/ISite.xml index fd0e91f6458..dfb729074d5 100644 --- a/xml/System.ComponentModel/ISite.xml +++ b/xml/System.ComponentModel/ISite.xml @@ -183,7 +183,7 @@ property indicates that the instance does not have an . + `null` for the property indicates that the instance does not have an . ]]> diff --git a/xml/System.ComponentModel/ISupportInitializeNotification.xml b/xml/System.ComponentModel/ISupportInitializeNotification.xml index d94bdc3b5a6..336e00281cb 100644 --- a/xml/System.ComponentModel/ISupportInitializeNotification.xml +++ b/xml/System.ComponentModel/ISupportInitializeNotification.xml @@ -47,13 +47,13 @@ Allows coordination of initialization for a component and its dependent properties. - interface. You can check to see if the dependent components have completed initialization by checking the property. - - is implemented by the and types. - + interface. You can check to see if the dependent components have completed initialization by checking the property. + + is implemented by the and types. + ]]> @@ -96,13 +96,13 @@ Occurs when initialization of the component is completed. - method for the component, but it may occur later if the component has dependent controls that implement the interface and the dependent controls have not completed initialization. - - For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). - + method for the component, but it may occur later if the component has dependent controls that implement the interface and the dependent controls have not completed initialization. + + For more information about how to handle events, see [Handling and Raising Events](/dotnet/standard/events/). + ]]> @@ -147,11 +147,11 @@ to indicate the component has completed initialization; otherwise, . - property is automatically set to `false` when the method is called, and `true` when the method is called. - + property is automatically set to `false` when the method is called, and `true` when the method is called. + ]]> diff --git a/xml/System.ComponentModel/ISynchronizeInvoke.xml b/xml/System.ComponentModel/ISynchronizeInvoke.xml index bf1370dfea1..5bc12a06f51 100644 --- a/xml/System.ComponentModel/ISynchronizeInvoke.xml +++ b/xml/System.ComponentModel/ISynchronizeInvoke.xml @@ -44,20 +44,20 @@ Provides a way to synchronously or asynchronously execute a delegate. - interface provides synchronous and asynchronous communication between objects about the occurrence of an event. Objects that implement this interface can receive notification that an event has occurred, and they can respond to queries about the event. In this way, clients can ensure that one request has been processed before they submit a subsequent request that depends on completion of the first. - - The class provides two ways to invoke a process: - -1. Asynchronously, by using the method. starts a process and then returns immediately. Use to wait until the process started by completes. - -2. Synchronously, by using the method. starts a process, waits until it completes, and then returns. Use when the control's main thread is different from the calling thread to marshal the call to the proper thread. - + interface provides synchronous and asynchronous communication between objects about the occurrence of an event. Objects that implement this interface can receive notification that an event has occurred, and they can respond to queries about the event. In this way, clients can ensure that one request has been processed before they submit a subsequent request that depends on completion of the first. + + The class provides two ways to invoke a process: + +1. Asynchronously, by using the method. starts a process and then returns immediately. Use to wait until the process started by completes. + +2. Synchronously, by using the method. starts a process, waits until it completes, and then returns. Use when the control's main thread is different from the calling thread to marshal the call to the proper thread. + > [!NOTE] -> The attribute applied to this class has the following property value: | . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - +> The attribute applied to this class has the following property value: | . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + ]]> @@ -119,15 +119,15 @@ Asynchronously executes the delegate on the thread that created this object. An interface that represents the asynchronous operation started by calling this method. - was called. - - The delegate is called asynchronously, and this method returns immediately. You can call this method from any thread. If you need the return value from a process started with this method, call to get the value. - - If you need to call the delegate synchronously, use the method instead. - + was called. + + The delegate is called asynchronously, and this method returns immediately. You can call this method from any thread. If you need the return value from a process started with this method, call to get the value. + + If you need to call the delegate synchronously, use the method instead. + ]]> @@ -184,11 +184,11 @@ Waits until the process started by calling completes, and then returns the value generated by the process. An that represents the return value generated by the asynchronous operation. - passed by this interface. If the asynchronous operation has not completed, this method will wait until the result is available. - + passed by this interface. If the asynchronous operation has not completed, this method will wait until the result is available. + ]]> @@ -248,13 +248,13 @@ Synchronously executes the delegate on the thread that created this object and marshals the call to the creating thread. An that represents the return value from the delegate being invoked, or if the delegate has no return value. - , this method operates synchronously, that is, it waits until the process completes before returning. Exceptions raised during the call are propagated back to the caller. - - Use this method when calling a method from a different thread to marshal the call to the proper thread. - + , this method operates synchronously, that is, it waits until the process completes before returning. Exceptions raised during the call are propagated back to the caller. + + Use this method when calling a method from a different thread to marshal the call to the proper thread. + ]]> @@ -300,11 +300,11 @@ if the caller must call ; otherwise, . - when making method calls to an object that implements this interface. Such objects are bound to a specific thread and are not thread-safe. If you are calling a method from a different thread, you must use the method to marshal the call to the proper thread. - + when making method calls to an object that implements this interface. Such objects are bound to a specific thread and are not thread-safe. If you are calling a method from a different thread, you must use the method to marshal the call to the proper thread. + ]]> diff --git a/xml/System.ComponentModel/ITypeDescriptorContext.xml b/xml/System.ComponentModel/ITypeDescriptorContext.xml index f9a5651f0bd..8fc4986ebb0 100644 --- a/xml/System.ComponentModel/ITypeDescriptorContext.xml +++ b/xml/System.ComponentModel/ITypeDescriptorContext.xml @@ -56,23 +56,23 @@ Provides contextual information about a component, such as its container and property descriptor. - interface provides contextual information about a component. is typically used at design time to provide information about a design-time container. This interface is commonly used in type conversion. For details, see . - + interface provides contextual information about a component. is typically used at design time to provide information about a design-time container. This interface is commonly used in type conversion. For details, see . + > [!NOTE] -> Do not rely on the presence of this interface when you design a type converter. If a particular interface, property, or service is necessary but not available, the type converter should return `null` rather than throw an exception. This interface's properties can return `null` at any time, and you should plan for this. - - - -## Examples - The following code example demonstrates how to use the interface to support type conversion. - +> Do not rely on the presence of this interface when you design a type converter. If a particular interface, property, or service is necessary but not available, the type converter should return `null` rather than throw an exception. This interface's properties can return `null` at any time, and you should plan for this. + + + +## Examples + The following code example demonstrates how to use the interface to support type conversion. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/InstanceDescriptorSample/CPP/instancedescriptor.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ITypeDescriptorContext/Overview/instancedescriptor.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ITypeDescriptorContext/Overview/instancedescriptor.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ITypeDescriptorContext/Overview/instancedescriptor.vb" id="Snippet1"::: + ]]> @@ -121,11 +121,11 @@ Gets the container representing this request. An with the set of objects for this ; otherwise, if there is no container or if the does not use outside objects. - property gets the logical container of the component associated with the type descriptor. - + property gets the logical container of the component associated with the type descriptor. + ]]> @@ -173,11 +173,11 @@ Gets the object that is connected with this type descriptor request. The object that invokes the method on the ; otherwise, if there is no object responsible for the call. - property gets the object that is invoking the interface. For example, if a type converter is given a to convert, returns the actual instance of the control that is using the . You can subsequently query the control for further information about its services and its . - + property gets the object that is invoking the interface. For example, if a type converter is given a to convert, returns the actual instance of the control that is using the . You can subsequently query the control for further information about its services and its . + ]]> @@ -224,15 +224,15 @@ Raises the event. - method to send notification that an instance of an object has changed. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + method to send notification that an instance of an object has changed. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> @@ -285,15 +285,15 @@ if this object can be changed; otherwise, . - method to send notification that an instance of an object is about to be changed. This method also returns a value indicating whether this object can be changed. When `false` is returned, do not change the object. - - Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). - - The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. - + method to send notification that an instance of an object is about to be changed. This method also returns a value indicating whether this object can be changed. When `false` is returned, do not change the object. + + Raising an event invokes the event handler through a delegate. For more information, see [Handling and Raising Events](/dotnet/standard/events/). + + The method also allows derived classes to handle the event without attaching a delegate. This is the preferred technique for handling the event in a derived class. + ]]> diff --git a/xml/System.ComponentModel/ITypedList.xml b/xml/System.ComponentModel/ITypedList.xml index 86597e9b1d0..87f93d04f52 100644 --- a/xml/System.ComponentModel/ITypedList.xml +++ b/xml/System.ComponentModel/ITypedList.xml @@ -57,7 +57,7 @@ - -- Implementer of , provided the implementer has a strongly typed property (that is, the is anything but ). You can accomplish this by making the default implementation of private. If you want to create an that follows the rules of a strongly typed collection, you should derive from . +- Implementer of , provided the implementer has a strongly typed property (that is, the is anything but ). You can accomplish this by making the default implementation of private. If you want to create an that follows the rules of a strongly typed collection, you should derive from . - Implementer of . diff --git a/xml/System.ComponentModel/InstallerTypeAttribute.xml b/xml/System.ComponentModel/InstallerTypeAttribute.xml index 0c4a3088c9a..a73df70c13f 100644 --- a/xml/System.ComponentModel/InstallerTypeAttribute.xml +++ b/xml/System.ComponentModel/InstallerTypeAttribute.xml @@ -56,13 +56,13 @@ Specifies the installer for a type that installs components. - interface. Use the property to get the installer associated with this attribute. - - For more information, see [Attributes](/dotnet/standard/attributes/). - + interface. Use the property to get the installer associated with this attribute. + + For more information, see [Attributes](/dotnet/standard/attributes/). + ]]> diff --git a/xml/System.ComponentModel/LicenseContext.xml b/xml/System.ComponentModel/LicenseContext.xml index db6f1dda953..001b1076029 100644 --- a/xml/System.ComponentModel/LicenseContext.xml +++ b/xml/System.ComponentModel/LicenseContext.xml @@ -286,7 +286,7 @@ at design time. You must override the property to implement design-time license support. + Typically, call this method when you set at design time. You must override the property to implement design-time license support. ]]> diff --git a/xml/System.ComponentModel/LicenseProviderAttribute.xml b/xml/System.ComponentModel/LicenseProviderAttribute.xml index bb66f86ef01..0a7f4ae8688 100644 --- a/xml/System.ComponentModel/LicenseProviderAttribute.xml +++ b/xml/System.ComponentModel/LicenseProviderAttribute.xml @@ -56,33 +56,33 @@ Specifies the to use with a class. This class cannot be inherited. - by marking the component with a . - - Use the property to get the of the . - - For more information about attributes, see [Attributes](/dotnet/standard/attributes/). For more information about licensing, see [How to: License Components and Controls](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/fe8b1eh9(v=vs.120)). - + by marking the component with a . + + Use the property to get the of the . + + For more information about attributes, see [Attributes](/dotnet/standard/attributes/). For more information about licensing, see [How to: License Components and Controls](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/fe8b1eh9(v=vs.120)). + > [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - - - -## Examples - The following code example uses the as the license provider for `MyControl`. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + + + +## Examples + The following code example uses the as the license provider for `MyControl`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic LicenseProviderAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/LicenseProviderAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LicenseProviderAttribute/Overview/source.vb" id="Snippet1"::: - - The next code example creates an instance of the `MyControl` class. Then, it gets the attributes for the class, and prints the name of the license provider used by `myNewControl`. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LicenseProviderAttribute/Overview/source.vb" id="Snippet1"::: + + The next code example creates an instance of the `MyControl` class. Then, it gets the attributes for the class, and prints the name of the license provider used by `myNewControl`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic LicenseProviderAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/LicenseProviderAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LicenseProviderAttribute/Overview/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LicenseProviderAttribute/Overview/source.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.ComponentModel/ListChangedEventArgs.xml b/xml/System.ComponentModel/ListChangedEventArgs.xml index 643386f0dc3..601d3c58b94 100644 --- a/xml/System.ComponentModel/ListChangedEventArgs.xml +++ b/xml/System.ComponentModel/ListChangedEventArgs.xml @@ -52,25 +52,25 @@ Provides data for the event. - event is raised when the data in an changes. - - The property indicates the index of the item that was added, changed, or deleted. If an item was moved, the property indicates the new location of the item and the property indicates the old location. - - If only one item is affected by a change, the property value is -1. - - - -## Examples - The following code example demonstrates the use of this type. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - - To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. - + event is raised when the data in an changes. + + The property indicates the index of the item that was added, changed, or deleted. If an item was moved, the property indicates the new location of the item and the property indicates the old location. + + If only one item is affected by a change, the property value is -1. + + + +## Examples + The following code example demonstrates the use of this type. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + + To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.cs" id="Snippet134"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet134"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet134"::: + ]]> @@ -136,13 +136,13 @@ The that was added, removed, or changed. Initializes a new instance of the class given the type of change and the affected. - , , or . - + , , or . + ]]> @@ -197,11 +197,11 @@ The index of the item that was added, changed, or removed. Initializes a new instance of the class given the type of change and the index of the affected item. - property is set to -1. - + property is set to -1. + ]]> @@ -360,16 +360,16 @@ Gets the type of change. A value indicating the type of change. - event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - - To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. - + event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + + To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.cs" id="Snippet134"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet134"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet134"::: + ]]> @@ -422,21 +422,21 @@ Gets the index of the item affected by the change. The index of the affected by the change. - event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - - To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. - + event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + + To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.cs" id="Snippet134"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet134"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet134"::: + ]]> @@ -489,16 +489,16 @@ Gets the old index of an item that has been moved. The old index of the moved item. - event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - - To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. - + event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + + To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.cs" id="Snippet134"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet134"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet134"::: + ]]> @@ -551,16 +551,16 @@ Gets the that was added, changed, or deleted. The affected by the change. - event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - - To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. - + event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + + To run the example code, paste it into a project that contains an instance of type named `BindingSource1`. Then ensure that the event handler is associated with the event. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.cs" id="Snippet134"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet134"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet134"::: + ]]> diff --git a/xml/System.ComponentModel/ListChangedType.xml b/xml/System.ComponentModel/ListChangedType.xml index b0282f7577c..94c8ad9435f 100644 --- a/xml/System.ComponentModel/ListChangedType.xml +++ b/xml/System.ComponentModel/ListChangedType.xml @@ -45,16 +45,16 @@ Specifies how the list changed. - property of the class to indicate the way an object changes. - - - -## Examples - For an example of using this class, see [Handling DataView Events](/dotnet/framework/data/adonet/dataset-datatable-dataview/handling-dataview-events). - + property of the class to indicate the way an object changes. + + + +## Examples + For an example of using this class, see [Handling DataView Events](/dotnet/framework/data/adonet/dataset-datatable-dataview/handling-dataview-events). + ]]> diff --git a/xml/System.ComponentModel/ListSortDescriptionCollection.xml b/xml/System.ComponentModel/ListSortDescriptionCollection.xml index e25ceb4969d..f2d04aa4056 100644 --- a/xml/System.ComponentModel/ListSortDescriptionCollection.xml +++ b/xml/System.ComponentModel/ListSortDescriptionCollection.xml @@ -62,13 +62,13 @@ Represents a collection of objects. - class is used by the interface. - - The is read-only once constructed. - + class is used by the interface. + + The is read-only once constructed. + ]]> @@ -118,11 +118,11 @@ Initializes a new instance of the class. - is read-only once constructed. - + is read-only once constructed. + ]]> @@ -167,13 +167,13 @@ The array of objects to be contained in the collection. Initializes a new instance of the class with the specified array of objects. - is read-only once constructed. - - Example - + is read-only once constructed. + + Example + ]]> @@ -414,11 +414,11 @@ Gets or sets the specified . The with the specified index. - is read-only once constructed and will throw an if you attempt to set an item. - + is read-only once constructed and will throw an if you attempt to set an item. + ]]> An item is set in the , which is read-only. @@ -467,11 +467,11 @@ in all cases. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -524,13 +524,13 @@ Gets the current instance that can be used to synchronize access to the collection. The current instance of the . - , because this collection, once constructed, does not allow public access to the underlying list. - - For more information on the method, see the property. - + , because this collection, once constructed, does not allow public access to the underlying list. + + For more information on the method, see the property. + ]]> @@ -636,11 +636,11 @@ This member is an explicit interface member implementation. It can be used only Adds an item to the collection. The position into which the new element was inserted. - class implements the interface, it must have an method. However, because the class represents a read-only collection, adding items to the collection is an invalid operation. - + class implements the interface, it must have an method. However, because the class represents a read-only collection, adding items to the collection is an invalid operation. + ]]> In all cases. @@ -688,11 +688,11 @@ This member is an explicit interface member implementation. It can be used only Removes all items from the collection. - class implements the interface, it must have a method. However, because the class represents a read-only collection, clearing items from the collection is an invalid operation. - + class implements the interface, it must have a method. However, because the class represents a read-only collection, clearing items from the collection is an invalid operation. + ]]> In all cases. @@ -746,11 +746,11 @@ This member is an explicit interface member implementation. It can be used only The item to insert into the collection. Inserts an item into the collection at a specified index. - class implements the interface, it must have a method. However, because the class represents a read-only collection, inserting items into the collection is an invalid operation. - + class implements the interface, it must have a method. However, because the class represents a read-only collection, inserting items into the collection is an invalid operation. + ]]> In all cases. @@ -799,11 +799,11 @@ This member is an explicit interface member implementation. It can be used only in all cases. - @@ -851,11 +851,11 @@ This member is an explicit interface member implementation. It can be used only in all cases. - is read-only once constructed. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. - + is read-only once constructed. A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created. + ]]> @@ -961,11 +961,11 @@ This member is an explicit interface member implementation. It can be used only The item to remove from the collection. Removes the first occurrence of an item from the collection. - class implements the interface, it must have a method. However, because the class represents a read-only collection, removing items from the collection is an invalid operation. - + class implements the interface, it must have a method. However, because the class represents a read-only collection, removing items from the collection is an invalid operation. + ]]> In all cases. @@ -1016,11 +1016,11 @@ This member is an explicit interface member implementation. It can be used only The zero-based index of the to remove from the collection. Removes an item from the collection at a specified index. - class implements the interface, it must have a method. However, because the class represents a read-only collection, removing items from the collection is an invalid operation. - + class implements the interface, it must have a method. However, because the class represents a read-only collection, removing items from the collection is an invalid operation. + ]]> In all cases. diff --git a/xml/System.ComponentModel/LookupBindingPropertiesAttribute.xml b/xml/System.ComponentModel/LookupBindingPropertiesAttribute.xml index adcb98338d2..9f23a4fe7d7 100644 --- a/xml/System.ComponentModel/LookupBindingPropertiesAttribute.xml +++ b/xml/System.ComponentModel/LookupBindingPropertiesAttribute.xml @@ -55,36 +55,36 @@ Specifies the properties that support lookup-based binding. This class cannot be inherited. - is used to specify the properties used with lookup-based binding, particularly and controls. - - The is specified at the class level. The class can be inherited and does not allow multiple attributes on the same class. - - - -## Examples - The following code example shows properties used with lookup-based binding. - + is used to specify the properties used with lookup-based binding, particularly and controls. + + The is specified at the class level. The class can be inherited and does not allow multiple attributes on the same class. + + + +## Examples + The following code example shows properties used with lookup-based binding. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.vb" id="Snippet2"::: - - The attribute must include all four members, except when unsetting values. The following code example shows the control. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.vb" id="Snippet2"::: + + The attribute must include all four members, except when unsetting values. The following code example shows the control. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.vb" id="Snippet3"::: - - The following code example shows that a control can support both simple binding as well as list binding. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.vb" id="Snippet3"::: + + The following code example shows that a control can support both simple binding as well as list binding. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.vb" id="Snippet4"::: - - The following code example shows that the attribute can be unset by specifying no arguments. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.vb" id="Snippet4"::: + + The following code example shows that the attribute can be unset by specifying no arguments. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/LookupBindingPropertiesAttribute/Overview/DemoControl.vb" id="Snippet5"::: + ]]> @@ -140,11 +140,11 @@ Initializes a new instance of the class using no parameters. - , , , and properties to `null`. - + , , , and properties to `null`. + ]]> @@ -204,11 +204,11 @@ The name of the property to be used for lookups. Initializes a new instance of the class. - property is set to `dataSource`. - + property is set to `dataSource`. + ]]> @@ -263,11 +263,11 @@ Gets the name of the data source property for the component to which the is bound. The data source property for the component to which the is bound. - property is set in the constructors for this class. - + property is set in the constructors for this class. + ]]> @@ -317,11 +317,11 @@ Represents the default value for the class. - member is a static, read-only field that defines an instance of the class initialized with the parameterless constructor. - + member is a static, read-only field that defines an instance of the class initialized with the parameterless constructor. + ]]> @@ -372,11 +372,11 @@ Gets the name of the display member property for the component to which the is bound. The name of the display member property for the component to which the is bound. - property is set in the constructors for this class. - + property is set in the constructors for this class. + ]]> @@ -434,11 +434,11 @@ if the object is equal to the current instance; otherwise, , indicating they are not equal. - method returns `true` if the `obj` parameter is of type and all the public properties - , , , and - are equal to each other. - + method returns `true` if the `obj` parameter is of type and all the public properties - , , , and - are equal to each other. + ]]> @@ -536,11 +536,11 @@ Gets the name of the lookup member for the component to which this attribute is bound. The name of the lookup member for the component to which the is bound. - property is set in the constructors for this class. - + property is set in the constructors for this class. + ]]> @@ -592,11 +592,11 @@ Gets the name of the value member property for the component to which the is bound. The name of the value member property for the component to which the is bound. - property is set in the constructors for this class. - + property is set in the constructors for this class. + ]]> diff --git a/xml/System.ComponentModel/MaskedTextProvider.xml b/xml/System.ComponentModel/MaskedTextProvider.xml index 0290a3c9282..84d05b6a0d3 100644 --- a/xml/System.ComponentModel/MaskedTextProvider.xml +++ b/xml/System.ComponentModel/MaskedTextProvider.xml @@ -62,18 +62,18 @@ control contains a mask, composed of literal characters and formatting elements, that it tests all user input against. Instead of permanently associating a specific mask-parsing engine with , Windows Forms provides it as a separate service, represented by the class, which defines the syntax of the masking language discussed in the documentation for the property. + The control contains a mask, composed of literal characters and formatting elements, that it tests all user input against. Instead of permanently associating a specific mask-parsing engine with , Windows Forms provides it as a separate service, represented by the class, which defines the syntax of the masking language discussed in the documentation for the property. - Many of the members of the class refer their implementation to similarly named members of the associated . For example, the property of the class refers all access to the of the class. + Many of the members of the class refer their implementation to similarly named members of the associated . For example, the property of the class refers all access to the of the class. - The mask-parsing engine used by is modeled after the Masked Edit control included in Microsoft Visual Basic version 6. Its masking language is described in the documentation for the property. + The mask-parsing engine used by is modeled after the Masked Edit control included in Microsoft Visual Basic version 6. Its masking language is described in the documentation for the property. The following three distinct strings are involved with the class. |String name|Description| |-----------------|-----------------| |Input character or string|Represents the characters used as input that the mask is applied against. In actuality, the input string may be composed of multiple input operations, including , , , and . Therefore, the input string cannot be accessed directly. However, aspects of the input string handling are available though the and , , and properties.| -|Mask|Represents the input formatting mask used to transform the input string into the formatted string. This string is set in the and accessed primarily though the property. Characteristics of the mask are also available through other members, such as the , , and properties.| +|Mask|Represents the input formatting mask used to transform the input string into the formatted string. This string is set in the and accessed primarily though the property. Characteristics of the mask are also available through other members, such as the , , and properties.| |Formatted string|Represents the string that results when the full mask is applied to the input string. The formatted string can be queried with many members of the class, including , , , , , , and so on. The full value of the formatted string is available from the and methods.| > [!NOTE] @@ -554,7 +554,7 @@ class, which is detailed in the property of the class. + This constructor represents the most general overloaded form. The `mask` parameter must conform to the masking language defined by the class, which is detailed in the property of the class. Because neutral cultures cannot be queried for culture-specific information, the constructor will use the method to search for the first non-neutral culture to use to determine the proper separator characters. @@ -632,7 +632,7 @@ method adds the `input` character value to the first available position in the formatted string after the position that was last assigned, which is represented by the property. This method will fail for any of the following reasons: + The method adds the `input` character value to the first available position in the formatted string after the position that was last assigned, which is represented by the property. This method will fail for any of the following reasons: - The input value, `input`, is not printable, or it does not match its corresponding mask element. @@ -771,7 +771,7 @@ method attempts to add the `input` character value to the first available position in the formatted string after the position that was last assigned, which is represented by the property. This method will fail if all available positions are before the last assigned position. This method will fail for any of the following reasons: + The method attempts to add the `input` character value to the first available position in the formatted string after the position that was last assigned, which is represented by the property. This method will fail if all available positions are before the last assigned position. This method will fail for any of the following reasons: - The input value, `input`, is not printable, or it does not match its corresponding mask element. @@ -909,7 +909,7 @@ property's value is set in the constructor. + The property's value is set in the constructor. Even when is `true`, the prompt character must be valid for the current location in the mask in order to be accepted. @@ -963,7 +963,7 @@ property's value is set in the constructor. + The property's value is set in the constructor. If `true`, restricts user input to the ASCII character set. @@ -1021,7 +1021,7 @@ property, should equal the sum of the and the properties. + The total number of editable character positions, represented by the property, should equal the sum of the and the properties. ]]> @@ -1076,7 +1076,7 @@ property, should equal the sum of the and the properties. + The total number of editable character positions, represented by the property, should equal the sum of the and the properties. ]]> @@ -1318,7 +1318,7 @@ property is set in the constructor. + The property is set in the constructor. ]]> @@ -1368,7 +1368,7 @@ property is defined in the class to be the asterisk character (*). + The property is defined in the class to be the asterisk character (*). ]]> @@ -1419,7 +1419,7 @@ property, must equal the sum of the and the properties. This value includes both the required and the optional editable characters. + The total number of editable character positions, represented by the property, must equal the sum of the and the properties. This value includes both the required and the optional editable characters. ]]> @@ -1476,7 +1476,7 @@ property, a temporary collection of editable positions is created that the retrieved operates on. + On every access of the property, a temporary collection of editable positions is created that the retrieved operates on. This collection is read-only. @@ -2539,7 +2539,7 @@ property is used to represent a result that is not valid for indexing operations, such as the method. + The property is used to represent a result that is not valid for indexing operations, such as the method. When you use the provider or implement your own, you should use this property to decide if an index is invalid, rather than hard-coding knowledge of invalid values. @@ -2722,9 +2722,9 @@ ## Remarks Password protection can be initiated using one of the following two ways: -- Setting the property to a non-`null` value. +- Setting the property to a non-`null` value. -- Setting the property to `true`, which also sets the property to the value. +- Setting the property to `true`, which also sets the property to the value. is used by the and methods to determine whether to reveal the actual input characters or obscure them with . @@ -2967,7 +2967,7 @@ property is the standard indexer for the class. + The property is the standard indexer for the class. ]]> @@ -3020,7 +3020,7 @@ property represents the farthest edit position in the mask, relative to the origin, that has been assigned an input character. For languages read left-to-right (LTR), such as English, this is the rightmost assigned position; for languages read right-to-left (RTL), this would be the leftmost position. + The property represents the farthest edit position in the mask, relative to the origin, that has been assigned an input character. For languages read left-to-right (LTR), such as English, this is the rightmost assigned position; for languages read right-to-left (RTL), this would be the leftmost position. ]]> @@ -3072,7 +3072,7 @@ property represents the total number of characters in the mask, including both the literal and editable characters. The number of literal characters can be determined by subtracting the value of the from the . + The property represents the total number of characters in the mask, including both the literal and editable characters. The number of literal characters can be determined by subtracting the value of the from the . also describes the length of the formatted string, including input characters, literals, and prompt characters. @@ -3131,7 +3131,7 @@ property is set in the constructor. This mask must contain only valid characters as defined by the masking language. + The property is set in the constructor. This mask must contain only valid characters as defined by the masking language. ]]> @@ -3187,9 +3187,9 @@ property checks only required input elements. To determine whether all required and optional input elements have been entered, use the property of the class instead. + The property checks only required input elements. To determine whether all required and optional input elements have been entered, use the property of the class instead. - The current value of the property determines which formatting elements are considered required and which are optional. + The current value of the property determines which formatting elements are considered required and which are optional. ]]> @@ -3243,7 +3243,7 @@ property instead. The current value of the property determines which formatting elements are considered required and which are optional. + To verify if only required input elements have been entered, use the property instead. The current value of the property determines which formatting elements are considered required and which are optional. ]]> @@ -3302,7 +3302,7 @@ property is set to a non-`null` character, output methods such as and will obscure the input characters with the specified password character. Setting this property to `null` will disable password protection functionality. + For sensitive user input, it is common practice to conceal the actual information entered by the user during output operations. If the property is set to a non-`null` character, output methods such as and will obscure the input characters with the specified password character. Setting this property to `null` will disable password protection functionality. ]]> @@ -3364,7 +3364,7 @@ property represents the prompt character that is used by the and methods to represent the current state of the formatted input string. A prompt character is placed in editable positions that have not yet been assigned an input value. Some versions of the method also depend on the value of the property. + The property represents the prompt character that is used by the and methods to represent the current state of the formatted input string. A prompt character is placed in editable positions that have not yet been assigned an input value. Some versions of the method also depend on the value of the property. ]]> @@ -4222,9 +4222,9 @@ can treat two categories of characters, paces and prompt characters, in a special manner. Normally, each input character will be tested against the mask and either accepted or rejected. Operating on the assumption that the property is set to a value other than `null`, then setting the property to `true` will result in special processing for the prompt character. When a prompt character is added, it causes the current mask character position to be cleared and the current position to be advanced to the next editable character. + can treat two categories of characters, paces and prompt characters, in a special manner. Normally, each input character will be tested against the mask and either accepted or rejected. Operating on the assumption that the property is set to a value other than `null`, then setting the property to `true` will result in special processing for the prompt character. When a prompt character is added, it causes the current mask character position to be cleared and the current position to be advanced to the next editable character. - takes precedence over the property as described in the following table. + takes precedence over the property as described in the following table. |||Resulting behavior| |---------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| @@ -4288,7 +4288,7 @@ can treat two categories of characters, spaces and prompt characters, in a special manner. Normally, each input character will be tested against the mask and either accepted or rejected. Setting the property to `true` will result in the current mask character position being cleared and the current position being advanced to the next editable character. + can treat two categories of characters, spaces and prompt characters, in a special manner. Normally, each input character will be tested against the mask and either accepted or rejected. Setting the property to `true` will result in the current mask character position being cleared and the current position being advanced to the next editable character. is useful when assigning text that was saved excluding the prompt, where the prompt is replaced with a space. Before restoring such a string, setting to `true` will reset the prompt characters at the positions occupied by spaces in the input string. @@ -4493,7 +4493,7 @@ property determines the result. + Input masks can contain literal and editable characters. If an attempt is made to add an input character to the position in a mask occupied by a literal, the value of the property determines the result. - If this property is `true`, it is valid to overwrite a literal with the same value when adding input characters. For example, a forward slash character value, `'/'`, could be added to the third position of the mask `"00/00/000"`. @@ -4551,7 +4551,7 @@ method will always include prompt and literal characters in the return value, regardless of the value of the or properties. This method will always display password characters if the property is set to a character value other than `null`. + The method will always include prompt and literal characters in the return value, regardless of the value of the or properties. This method will always display password characters if the property is set to a character value other than `null`. is commonly used to obtain the string to display in associated user interface elements, such as . @@ -4617,7 +4617,7 @@ method includes prompts and literals according to the current values of the and properties, respectively. It will always return the original input characters, ignoring the value of the property. + This version of the overloaded method includes prompts and literals according to the current values of the and properties, respectively. It will always return the original input characters, ignoring the value of the property. > [!IMPORTANT] > Because this method reveals information that is usually protected in the user interface by password characters, it should be used with extreme caution to avoid accidentally revealing sensitive user data. @@ -4678,7 +4678,7 @@ method includes prompts and literals according to the current values of the and properties, respectively. If the `ignorePasswordChar` parameter is `true`, it will return the original input characters, ignoring the value of the property. If this parameter is `false`, it will use the password character to obscure editable user input if the property is set to a value other than `null`. + This version of the overloaded method includes prompts and literals according to the current values of the and properties, respectively. If the `ignorePasswordChar` parameter is `true`, it will return the original input characters, ignoring the value of the property. If this parameter is `false`, it will use the password character to obscure editable user input if the property is set to a value other than `null`. > [!IMPORTANT] > Because this method potentially reveals information that is usually protected in the user interface by password characters, it should be used with extreme caution to avoid accidentally revealing sensitive user data. @@ -4742,7 +4742,7 @@ method includes prompts and literals according to the values of the `IncludePrompt` and `IncludeLiterals` parameters, respectively. Notice that these parameters override the values of the properties. This method will always return the original input characters, ignoring the value of the property. + This version of the overloaded method includes prompts and literals according to the values of the `IncludePrompt` and `IncludeLiterals` parameters, respectively. Notice that these parameters override the values of the properties. This method will always return the original input characters, ignoring the value of the property. > [!IMPORTANT] > Because this method reveals information that is usually protected in the user interface by password characters, it should be used with extreme caution to avoid accidentally revealing sensitive user data. @@ -4805,7 +4805,7 @@ method returns a substring of the formatted string, starting at the position `startPos` and including the subsequent number of characters specified by the `length` parameter. The returned string includes prompts and literals according to the current values of the and properties, respectively. The return string will contain the original input characters; the property is always ignored. + This version of the overloaded method returns a substring of the formatted string, starting at the position `startPos` and including the subsequent number of characters specified by the `length` parameter. The returned string includes prompts and literals according to the current values of the and properties, respectively. The return string will contain the original input characters; the property is always ignored. > [!IMPORTANT] > Because this method reveals information that is usually protected in the user interface by password characters, it should be used with extreme caution to avoid accidentally revealing sensitive user data. @@ -4880,7 +4880,7 @@ method returns a substring of the formatted string, starting at the position `startPos` and including the subsequent number of characters specified by the `length` parameter. The returned string includes prompts and literals according to the current values of the and properties, respectively. If the `ignorePasswordChar` parameter is `true`, it will return the original input characters, ignoring the value of the property. If this parameter is `false`, it will use the password character to obscure editable user input if the property is set to a value other than `null`. + This version of the overloaded method returns a substring of the formatted string, starting at the position `startPos` and including the subsequent number of characters specified by the `length` parameter. The returned string includes prompts and literals according to the current values of the and properties, respectively. If the `ignorePasswordChar` parameter is `true`, it will return the original input characters, ignoring the value of the property. If this parameter is `false`, it will use the password character to obscure editable user input if the property is set to a value other than `null`. > [!IMPORTANT] > Because this method potentially reveals information that is usually protected in the user interface by password characters, it should be used with extreme caution to avoid accidentally revealing sensitive user data. @@ -4964,7 +4964,7 @@ method returns a substring of the formatted string, starting at the position `startPos` and including the subsequent number of characters specified by the `length` parameter. The return string includes prompts and literals according to the values of the `IncludePrompt` and `IncludeLiterals` parameters, respectively. Notice that these parameters override the values of the properties. This method will always return the original input characters, ignoring the value of the property. + This version of the overloaded method returns a substring of the formatted string, starting at the position `startPos` and including the subsequent number of characters specified by the `length` parameter. The return string includes prompts and literals according to the values of the `IncludePrompt` and `IncludeLiterals` parameters, respectively. Notice that these parameters override the values of the properties. This method will always return the original input characters, ignoring the value of the property. > [!IMPORTANT] > Because this method reveals information that is usually protected in the user interface by password characters, it should be used with extreme caution to avoid accidentally revealing sensitive user data. @@ -5045,7 +5045,7 @@ method returns a substring of the formatted string, starting at the position `startPos` and including the subsequent number of characters specified by the `length` parameter. The return string includes prompts and literals according to the values of the `IncludePrompt` and `IncludeLiterals` parameters, respectively. Notice that these parameters override the values of the and properties. If the `ignorePasswordChar` parameter is `true`, it will return the original input characters, ignoring the value of the property. If this parameter is `false`, it will use the password character to obscure editable user input if the property is set to a value other than `null`. + This version of the overloaded method returns a substring of the formatted string, starting at the position `startPos` and including the subsequent number of characters specified by the `length` parameter. The return string includes prompts and literals according to the values of the `IncludePrompt` and `IncludeLiterals` parameters, respectively. Notice that these parameters override the values of the and properties. If the `ignorePasswordChar` parameter is `true`, it will return the original input characters, ignoring the value of the property. If this parameter is `false`, it will use the password character to obscure editable user input if the property is set to a value other than `null`. > [!IMPORTANT] > Because this method potentially reveals information that is usually protected in the user interface by password characters, it should be used with extreme caution to avoid accidentally revealing sensitive user data. @@ -5192,11 +5192,11 @@ ## Remarks A character is said to be *escaped* if it is valid input, but is not assigned to that position in the formatted string. Escaped characters fall into the following three categories: -- Prompt characters are escaped if the property is `true`. +- Prompt characters are escaped if the property is `true`. -- Input characters are escaped if they have the same value as the literal in the mask, and if the property is `true`. +- Input characters are escaped if they have the same value as the literal in the mask, and if the property is `true`. -- Space characters are escaped if the property is `true`. +- Space characters are escaped if the property is `true`. The method will also return `false` if the `pos` parameter is less than zero or greater than the of the . diff --git a/xml/System.ComponentModel/MemberDescriptor.xml b/xml/System.ComponentModel/MemberDescriptor.xml index 004bf15971f..20dfada62c9 100644 --- a/xml/System.ComponentModel/MemberDescriptor.xml +++ b/xml/System.ComponentModel/MemberDescriptor.xml @@ -58,23 +58,23 @@ Represents a class member, such as a property or event. This is an abstract base class. - is the base class for the and the classes. The class provides a description of an event, and the class provides a description of a property. - - This class defines properties and methods to access its stored attributes. The property gets the collection of attributes. The , , , and properties retrieve the values of those specific attributes. The and properties provide the name of the member. - - The also defines an method to compare this to another. - + is the base class for the and the classes. The class provides a description of an event, and the class provides a description of a property. + + This class defines properties and methods to access its stored attributes. The property gets the collection of attributes. The , , , and properties retrieve the values of those specific attributes. The and properties provide the name of the member. + + The also defines an method to compare this to another. + > [!NOTE] -> Typically, you inherit from the and classes, and not from this class. - - - -## Examples - Since most of the usage of this class will fall on the inherited classes and , refer to the examples in these classes. - +> Typically, you inherit from the and classes, and not from this class. + + + +## Examples + Since most of the usage of this class will fall on the inherited classes and , refer to the examples in these classes. + ]]> @@ -235,11 +235,11 @@ An array of objects with the attributes you want to add to the member. Initializes a new instance of the class with the name in the specified and the attributes in both the old and the array. - array to the attributes in the old . - + array to the attributes in the old . + ]]> @@ -346,11 +346,11 @@ Gets or sets an array of attributes. An array of type that contains the attributes of this member. - method. - + method. + ]]> @@ -397,11 +397,11 @@ Gets the collection of attributes for this member. An that provides the attributes for this member, or an empty collection if there are no attributes in the . - for this member, this property calls the method to create a new using the array of objects passed to the constructor. - + for this member, this property calls the method to create a new using the array of objects passed to the constructor. + ]]> @@ -448,11 +448,11 @@ Gets the name of the category to which the member belongs, as specified in the . The name of the category to which the member belongs. If there is no , the category name is set to the default category, . - @@ -502,11 +502,11 @@ Creates a collection of attributes using the array of attributes passed to the constructor. A new that contains the attributes. - property when there is no for this member. If there are no attributes in the , this will return an empty . - + property when there is no for this member. If there are no attributes in the , this will return an empty . + ]]> @@ -552,11 +552,11 @@ Gets the description of the member, as specified in the . The description of the member. If there is no , the property value is set to the default, which is an empty string (""). - @@ -606,11 +606,11 @@ if this member should be set only at design time; if the member can be set during run time. - , the return value is the default, which is `false`. - + , the return value is the default, which is `false`. + ]]> @@ -760,13 +760,13 @@ An that lists the attributes in the parent class. Initially, this is empty. When overridden in a derived class, adds the attributes of the inheriting class to the specified list of attributes in the parent class. - with the attributes is created once. If there are duplicate attributes in the list, only the first instance is saved; all subsequent duplicate attributes are removed from the list. - + with the attributes is created once. If there are duplicate attributes in the list, only the first instance is saved; all subsequent duplicate attributes are removed from the list. + ]]> @@ -1020,11 +1020,11 @@ Retrieves the object that should be used during invocation of members. The object to be used during member invocations. - method may return a different value. - + method may return a different value. + ]]> @@ -1189,11 +1189,11 @@ if the member is browsable; otherwise, . If there is no , the property value is set to the default, which is . - diff --git a/xml/System.ComponentModel/MergablePropertyAttribute.xml b/xml/System.ComponentModel/MergablePropertyAttribute.xml index 9a4fbe1a082..0c40cf4de60 100644 --- a/xml/System.ComponentModel/MergablePropertyAttribute.xml +++ b/xml/System.ComponentModel/MergablePropertyAttribute.xml @@ -78,7 +78,7 @@ The next example shows how to check the value of the for `MyProperty`. First the code gets a with all the properties for the object. Next it indexes into the to get `MyProperty`. Then it returns the attributes for this property and saves them in the attributes variable. - The example presents two different ways of checking the value of the . In the second code fragment, the example calls the method with a `static` value. In the last code fragment, the example uses the property to check the value. + The example presents two different ways of checking the value of the . In the second code fragment, the example calls the method with a `static` value. In the last code fragment, the example uses the property to check the value. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic MergablePropertyAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/MergablePropertyAttribute/Overview/source.cs" id="Snippet2"::: diff --git a/xml/System.ComponentModel/NestedContainer.xml b/xml/System.ComponentModel/NestedContainer.xml index a66f976f850..1fe22972918 100644 --- a/xml/System.ComponentModel/NestedContainer.xml +++ b/xml/System.ComponentModel/NestedContainer.xml @@ -75,7 +75,7 @@ - Site characteristics such as and are routed through the owning component's site. -- The site's property is a qualified name that includes the owning component's name followed by a period (.) and the child component's name. +- The site's property is a qualified name that includes the owning component's name followed by a period (.) and the child component's name. - provides support for the as a service. diff --git a/xml/System.ComponentModel/NotifyParentPropertyAttribute.xml b/xml/System.ComponentModel/NotifyParentPropertyAttribute.xml index aac08b907bd..9d3c218d684 100644 --- a/xml/System.ComponentModel/NotifyParentPropertyAttribute.xml +++ b/xml/System.ComponentModel/NotifyParentPropertyAttribute.xml @@ -57,21 +57,21 @@ Indicates that the parent property is notified when the value of the property that this attribute is applied to is modified. This class cannot be inherited. - to a property if its parent property should receive notification of changes to the property's values. For example, in the Properties window, the property has nested properties such as and . These nested properties are marked with `NotifyParentPropertyAttribute(true)` so they notify the parent property to update its value and display when the property values change. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following code example demonstrates how to use the and the class to create an expandable property on a custom control. - + to a property if its parent property should receive notification of changes to the property's values. For example, in the Properties window, the property has nested properties such as and . These nested properties are marked with `NotifyParentPropertyAttribute(true)` so they notify the parent property to update its value and display when the property values change. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following code example demonstrates how to use the and the class to create an expandable property on a custom control. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ExpandableObjectConverter/Overview/DemoControl.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ExpandableObjectConverter/Overview/DemoControl.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ExpandableObjectConverter/Overview/DemoControl.vb" id="Snippet1"::: + ]]> @@ -126,14 +126,14 @@ if the parent should be notified of changes; otherwise, . Initializes a new instance of the class, using the specified value to determine whether the parent property is notified of changes to the value of the property. - and the class to create an expandable property on a custom control. - + and the class to create an expandable property on a custom control. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ExpandableObjectConverter/Overview/DemoControl.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ExpandableObjectConverter/Overview/DemoControl.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ExpandableObjectConverter/Overview/DemoControl.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.ComponentModel/ProgressChangedEventArgs.xml b/xml/System.ComponentModel/ProgressChangedEventArgs.xml index bd62d62aee1..f43c1b7f6cc 100644 --- a/xml/System.ComponentModel/ProgressChangedEventArgs.xml +++ b/xml/System.ComponentModel/ProgressChangedEventArgs.xml @@ -53,15 +53,15 @@ Provides data for the event. - class. This example is part of a larger example for the class. - + class. This example is part of a larger example for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet7"::: + ]]> @@ -173,21 +173,21 @@ Gets the asynchronous task progress percentage. A percentage value indicating the asynchronous task progress. - property determines what percentage of an asynchronous task has been completed. - - - -## Examples - The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - - To run the example code, paste it into a project that contains an instance of type named `PictureBox1`. Then ensure that the event handler is associated with the event. - + property determines what percentage of an asynchronous task has been completed. + + + +## Examples + The following code example demonstrates the use of this member. In the example, an event handler reports on the occurrence of the event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + + To run the example code, paste it into a project that contains an instance of type named `PictureBox1`. Then ensure that the event handler is associated with the event. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.cs" id="Snippet517"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet517"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet517"::: + ]]> @@ -244,16 +244,16 @@ Gets a unique user state. A unique indicating the user state. - event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . - - To run the example code, paste it into a project that contains an instance of type named `PictureBox1`. Then ensure that the event handler is associated with the event. - + event. This report helps you to learn when the event occurs and can assist you in debugging. To report on multiple events or on events that occur frequently, consider replacing with or appending the message to a multiline . + + To run the example code, paste it into a project that contains an instance of type named `PictureBox1`. Then ensure that the event handler is associated with the event. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.cs" id="Snippet517"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet517"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/CollectionChangeEventArgs/Overview/EventExamples.vb" id="Snippet517"::: + ]]> diff --git a/xml/System.ComponentModel/PropertyChangedEventArgs.xml b/xml/System.ComponentModel/PropertyChangedEventArgs.xml index ddd4f57a946..54181f6f23d 100644 --- a/xml/System.ComponentModel/PropertyChangedEventArgs.xml +++ b/xml/System.ComponentModel/PropertyChangedEventArgs.xml @@ -55,13 +55,13 @@ Provides data for the event. - event is raised when a property is changed on a component. A object specifies the name of the property that changed. - - provides the property to get the name of the property that changed. - + event is raised when a property is changed on a component. A object specifies the name of the property that changed. + + provides the property to get the name of the property that changed. + ]]> @@ -116,11 +116,11 @@ The name of the property that changed. Initializes a new instance of the class. - value or `null` for the `propertyName` parameter indicates that all of the properties have changed. - + value or `null` for the `propertyName` parameter indicates that all of the properties have changed. + ]]> @@ -178,11 +178,11 @@ Gets the name of the property that changed. The name of the property that changed. - value or `null` for the `propertyName` parameter indicates that all of the properties have changed. - + value or `null` for the `propertyName` parameter indicates that all of the properties have changed. + ]]> diff --git a/xml/System.ComponentModel/PropertyDescriptor.xml b/xml/System.ComponentModel/PropertyDescriptor.xml index 02fab42dd32..d1ec22b9659 100644 --- a/xml/System.ComponentModel/PropertyDescriptor.xml +++ b/xml/System.ComponentModel/PropertyDescriptor.xml @@ -100,7 +100,7 @@ :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/PropertyDescriptor/Overview/propertydescriptor.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/PropertyDescriptor/Overview/propertydescriptor.vb" id="Snippet1"::: - The following code example shows how to implement a custom property descriptor that provides a read-only wrapper around a property. The `SerializeReadOnlyPropertyDescriptor` is used in a custom designer to provide a read-only property descriptor for the control's property. + The following code example shows how to implement a custom property descriptor that provides a read-only wrapper around a property. The `SerializeReadOnlyPropertyDescriptor` is used in a custom designer to provide a read-only property descriptor for the control's property. :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/PropertyDescriptor/Overview/SerializeReadOnlyPropertyDescriptor.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/PropertyDescriptor/Overview/SerializeReadOnlyPropertyDescriptor.vb" id="Snippet1"::: @@ -1986,7 +1986,7 @@ Note: The class property indicates whether value change notifications for this property may originate from outside the property descriptor, such as from the component itself, or whether notifications will only originate from direct calls made to the method. For example, the component may implement the interface, or may have an explicit `name.Changed` event for this property. + The property indicates whether value change notifications for this property may originate from outside the property descriptor, such as from the component itself, or whether notifications will only originate from direct calls made to the method. For example, the component may implement the interface, or may have an explicit `name.Changed` event for this property. ]]> diff --git a/xml/System.ComponentModel/PropertyDescriptorCollection.xml b/xml/System.ComponentModel/PropertyDescriptorCollection.xml index 00eeb7d113f..0af1afe8e40 100644 --- a/xml/System.ComponentModel/PropertyDescriptorCollection.xml +++ b/xml/System.ComponentModel/PropertyDescriptorCollection.xml @@ -74,7 +74,7 @@ ## Remarks is read-only; it does not implement methods that add or remove properties. You must inherit from this class to implement these methods. - Using the properties available in the class, you can query the collection about its contents. Use the property to determine the number of elements in the collection. Use the property to get a specific property by index number or by name. + Using the properties available in the class, you can query the collection about its contents. Use the property to determine the number of elements in the collection. Use the property to get a specific property by index number or by name. In addition to properties, you can use the method to get a description of the property with the specified name from the collection. @@ -475,12 +475,12 @@ property to set the limits of a loop that iterates through a collection of objects. Because the collection is zero-based, be sure to use `Count - 1` as the upper boundary of the loop. + You can use the property to set the limits of a loop that iterates through a collection of objects. Because the collection is zero-based, be sure to use `Count - 1` as the upper boundary of the loop. ## Examples - The following code example uses the property to print the number of properties on `button1`. It requires that `button1` and `textBox1` have been instantiated on a form. + The following code example uses the property to print the number of properties on `button1`. It requires that `button1` and `textBox1` have been instantiated on a form. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic PropertyDescriptorCollection.Count Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/PropertyDescriptorCollection/Count/source.cs" id="Snippet1"::: @@ -949,7 +949,7 @@ ## Examples - The following code example uses the property to print the name of the specified by the index number in a text box. Because the index number is zero-based, this example prints the name of the second . It requires that `button1` has been instantiated on a form. + The following code example uses the property to print the name of the specified by the index number in a text box. Because the index number is zero-based, this example prints the name of the second . It requires that `button1` has been instantiated on a form. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic PropertyDescriptorCollection.this Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/PropertyDescriptorCollection/Item/source.cs" id="Snippet1"::: @@ -1021,12 +1021,12 @@ property is case-sensitive when searching for names. That is, the names "Pname" and "pname" are considered to be two different properties. + The property is case-sensitive when searching for names. That is, the names "Pname" and "pname" are considered to be two different properties. ## Examples - The following code example uses the property to print the type of component for the specified by the index. It requires that `button1` and `textBox1` have been instantiated on a form. + The following code example uses the property to print the type of component for the specified by the index. It requires that `button1` and `textBox1` have been instantiated on a form. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic PropertyDescriptorCollection.this1 Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/PropertyDescriptorCollection/Item/source1.cs" id="Snippet1"::: diff --git a/xml/System.ComponentModel/ReadOnlyAttribute.xml b/xml/System.ComponentModel/ReadOnlyAttribute.xml index ef59a7d7547..70b4b69eb47 100644 --- a/xml/System.ComponentModel/ReadOnlyAttribute.xml +++ b/xml/System.ComponentModel/ReadOnlyAttribute.xml @@ -78,7 +78,7 @@ The next code example shows how to check the value of the for `MyProperty`. First, the code gets a with all the properties for the object. Next, it indexes into the to get `MyProperty`. Then it returns the attributes for this property and saves them in the attributes variable. - The example presents two different ways of checking the value of the . In the second code fragment, the example calls the method. In the last code fragment, the example uses the property to check the value. + The example presents two different ways of checking the value of the . In the second code fragment, the example calls the method. In the last code fragment, the example uses the property to check the value. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic ReadOnlyAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ReadOnlyAttribute/Overview/source.cs" id="Snippet2"::: diff --git a/xml/System.ComponentModel/RunWorkerCompletedEventArgs.xml b/xml/System.ComponentModel/RunWorkerCompletedEventArgs.xml index 1931898877c..94fe9cf51b0 100644 --- a/xml/System.ComponentModel/RunWorkerCompletedEventArgs.xml +++ b/xml/System.ComponentModel/RunWorkerCompletedEventArgs.xml @@ -52,22 +52,22 @@ Provides data for the *MethodName* event. - method. The method in turn raises the event asynchronously and passes it a instance. If the asynchronous operation returns a value, the event handler typically assigns it to the property. When the asynchronous operation completes, the event is raised and is passed a instance that contains information about the status of the operation (whether it was cancelled, faulted, or completed successfully). If it completed successfully, its property contains the value returned by the asynchronous operation and previously assigned to the property. - + > [!NOTE] -> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). - -## Examples - The following code example illustrates the use of . This example is part of a larger sample for the class. - +> The attribute applied to this class has the following property value: . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). + +## Examples + The following code example illustrates the use of . This example is part of a larger sample for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet6"::: + ]]> @@ -166,20 +166,20 @@ When using the [event-based asynchronous pattern](/dotnet/standard/asynchronous- Gets a value that represents the result of an asynchronous operation. An representing the result of an asynchronous operation. - event handler should always check the and properties before accessing the property. If an exception was raised or if the operation was canceled, accessing the property raises an exception. - - - -## Examples - The following code example demonstrates the use of the event to handle the result of an asynchronous operation. This code example is part of a larger example provided for the class. - + event handler should always check the and properties before accessing the property. If an exception was raised or if the operation was canceled, accessing the property raises an exception. + + + +## Examples + The following code example demonstrates the use of the event to handle the result of an asynchronous operation. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.ComponentModel.BackgroundWorker/CPP/fibonacciform.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/BackgroundWorker/Overview/fibonacciform.vb" id="Snippet6"::: + ]]> diff --git a/xml/System.ComponentModel/ToolboxItemAttribute.xml b/xml/System.ComponentModel/ToolboxItemAttribute.xml index f9b16193d79..1dfff3bb310 100644 --- a/xml/System.ComponentModel/ToolboxItemAttribute.xml +++ b/xml/System.ComponentModel/ToolboxItemAttribute.xml @@ -56,19 +56,19 @@ Represents an attribute of a toolbox item. - class provides a way to specify an attribute for a . In addition to what the class provides, this class of object stores the type of the toolbox item. - - - -## Examples - The following code example demonstrates the use of with the class as a base class for a custom toolbox item implementation. This code example is part of a larger example provided for the class. - + class provides a way to specify an attribute for a . In addition to what the class provides, this class of object stores the type of the toolbox item. + + + +## Examples + The following code example demonstrates the use of with the class as a base class for a custom toolbox item implementation. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemAttribute/Overview/Form1.vb" id="Snippet2"::: + ]]> @@ -126,11 +126,11 @@ to create a toolbox item attribute for a default type; to associate no default toolbox item support for this attribute. Initializes a new instance of the class and specifies whether to use default initialization values. - property is set to . - + property is set to . + ]]> @@ -182,11 +182,11 @@ The names of the type of the toolbox item and of the assembly that contains the type. Initializes a new instance of the class using the specified name of the type. - *,* \<*name of the assembly*> (for example, System.Drawing.Design.ToolboxItem, System.Drawing.Design). - + *,* \<*name of the assembly*> (for example, System.Drawing.Design.ToolboxItem, System.Drawing.Design). + ]]> @@ -279,11 +279,11 @@ Initializes a new instance of the class and sets the type to the default, . This field is read-only. - property is set to . - + property is set to . + ]]> @@ -430,11 +430,11 @@ if the current value of the attribute is the default; otherwise, . - class. - + class. + ]]> diff --git a/xml/System.ComponentModel/ToolboxItemFilterAttribute.xml b/xml/System.ComponentModel/ToolboxItemFilterAttribute.xml index a751eaad4df..e5450754287 100644 --- a/xml/System.ComponentModel/ToolboxItemFilterAttribute.xml +++ b/xml/System.ComponentModel/ToolboxItemFilterAttribute.xml @@ -61,22 +61,22 @@ Specifies the filter string and filter type to use for a toolbox item. - provides a mechanism by which toolbox items can be marked for use only with designers that have a matching attribute or code that determines whether the item should be enabled or disabled in the toolbox. - - A can be applied to a to indicate a filter string and filter type that specify when to enable or disable the item. can also be applied to a designer to indicate its requirements for enabling items in the toolbox. This type of attribute can be used to indicate that a toolbox item can only be enabled when a designer with a matching filter string is being used. The type of the filter is indicated in the property by a that indicates whether and how a filter string match is used, or whether to use custom code to determine whether to enable an item. - - - -## Examples - The following code example demonstrates how to apply the . - + provides a mechanism by which toolbox items can be marked for use only with designers that have a matching attribute or code that determines whether the item should be enabled or disabled in the toolbox. + + A can be applied to a to indicate a filter string and filter type that specify when to enable or disable the item. can also be applied to a designer to indicate its requirements for enabling items in the toolbox. This type of attribute can be used to indicate that a toolbox item can only be enabled when a designer with a matching filter string is being used. The type of the filter is indicated in the property by a that indicates whether and how a filter string match is used, or whether to use custom code to determine whether to enable an item. + + + +## Examples + The following code example demonstrates how to apply the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/IToolboxUserExample/CPP/samplecontrol.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.vb" id="Snippet1"::: + ]]> @@ -182,15 +182,15 @@ A indicating the type of the filter. Initializes a new instance of the class using the specified filter string and type. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/IToolboxUserExample/CPP/samplecontrol.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/ToolboxItemFilterAttribute/Overview/samplecontrol.vb" id="Snippet1"::: + ]]> @@ -345,11 +345,11 @@ Gets the type of the filter. A that indicates the type of the filter. - on the current designer, indicates the rules to use to determine whether a particular toolbox item should be enabled in the toolbox. - + on the current designer, indicates the rules to use to determine whether a particular toolbox item should be enabled in the toolbox. + ]]> diff --git a/xml/System.ComponentModel/TypeConverter+StandardValuesCollection.xml b/xml/System.ComponentModel/TypeConverter+StandardValuesCollection.xml index 261962ef6f7..29dac893969 100644 --- a/xml/System.ComponentModel/TypeConverter+StandardValuesCollection.xml +++ b/xml/System.ComponentModel/TypeConverter+StandardValuesCollection.xml @@ -224,7 +224,7 @@ property can be used to set the limits of a loop that iterates through a collection of objects. Since collection is zero-based, be sure to use `Count - 1` as the upper bound of the loop. + The property can be used to set the limits of a loop that iterates through a collection of objects. Since collection is zero-based, be sure to use `Count - 1` as the upper bound of the loop. ]]> diff --git a/xml/System.ComponentModel/TypeConverterAttribute.xml b/xml/System.ComponentModel/TypeConverterAttribute.xml index 59acb3e9f5b..45ab6fe9f39 100644 --- a/xml/System.ComponentModel/TypeConverterAttribute.xml +++ b/xml/System.ComponentModel/TypeConverterAttribute.xml @@ -71,36 +71,36 @@ Specifies what type to use as a converter for the object this attribute is bound to. - . Use the property to get the name of the class that provides the data conversion for the object this attribute is bound to. - - For more information about attributes, see [Attributes](/dotnet/standard/attributes/). For more information about type converters, see the base class and [How to: Implement a Type Converter](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/ayybcxe5(v=vs.120)). - - In order to establish a type converter on a custom class that provides type conversion behavior for XAML, you apply the attribute to your type. The argument of the attribute references your type converter implementation. Your type converter should be able to accept values from a string that is used for attributes or initialization text in XAML markup, and convert that string into your intended destination type. For more information, see [TypeConverters and XAML](/dotnet/framework/wpf/advanced/typeconverters-and-xaml). - - Rather than applying to all values of a type, a type converter behavior for XAML can also be established on a specific property. In this case, you apply to the property definition (the outer definition, not the specific `get` and `set` definitions). - - A type converter behavior for XAML usage of a custom attachable member can be assigned by applying to the `get` method accessor that supports the XAML usage. For more information, see [Attached Properties Overview](/dotnet/framework/wpf/advanced/attached-properties-overview). - - For complex XAML serialization cases that require additional state from the object runtime, consider defining a value serializer in addition to a type converter, and attribute both support classes on your custom types or custom members. For more information, see . - - - -## Examples - The following example declares `MyClass` to use the type converter called `MyClassConverter`. This example assumes that `MyClassConverter` has been implemented elsewhere. The class implementing the converter (`MyClassConverter`) must inherit from the class. - + . Use the property to get the name of the class that provides the data conversion for the object this attribute is bound to. + + For more information about attributes, see [Attributes](/dotnet/standard/attributes/). For more information about type converters, see the base class and [How to: Implement a Type Converter](https://learn.microsoft.com/previous-versions/visualstudio/visual-studio-2013/ayybcxe5(v=vs.120)). + + In order to establish a type converter on a custom class that provides type conversion behavior for XAML, you apply the attribute to your type. The argument of the attribute references your type converter implementation. Your type converter should be able to accept values from a string that is used for attributes or initialization text in XAML markup, and convert that string into your intended destination type. For more information, see [TypeConverters and XAML](/dotnet/framework/wpf/advanced/typeconverters-and-xaml). + + Rather than applying to all values of a type, a type converter behavior for XAML can also be established on a specific property. In this case, you apply to the property definition (the outer definition, not the specific `get` and `set` definitions). + + A type converter behavior for XAML usage of a custom attachable member can be assigned by applying to the `get` method accessor that supports the XAML usage. For more information, see [Attached Properties Overview](/dotnet/framework/wpf/advanced/attached-properties-overview). + + For complex XAML serialization cases that require additional state from the object runtime, consider defining a value serializer in addition to a type converter, and attribute both support classes on your custom types or custom members. For more information, see . + + + +## Examples + The following example declares `MyClass` to use the type converter called `MyClassConverter`. This example assumes that `MyClassConverter` has been implemented elsewhere. The class implementing the converter (`MyClassConverter`) must inherit from the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic TypeConverterAttribute Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/TypeConverterAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/TypeConverterAttribute/Overview/source.vb" id="Snippet1"::: - - The next example creates an instance of `MyClass`. Then it gets the attributes for the class, and prints the name of the type converter used by `MyClass`. - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/TypeConverterAttribute/Overview/source.vb" id="Snippet1"::: + + The next example creates an instance of `MyClass`. Then it gets the attributes for the class, and prints the name of the type converter used by `MyClass`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/Classic TypeConverterAttribute Example/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.ComponentModel/TypeConverterAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/TypeConverterAttribute/Overview/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ComponentModel/TypeConverterAttribute/Overview/source.vb" id="Snippet2"::: + ]]> @@ -161,11 +161,11 @@ Initializes a new instance of the class with the default type converter, which is an empty string (""). - . - + . + ]]> @@ -224,11 +224,11 @@ The fully qualified name of the class to use for data conversion for the object this attribute is bound to. Initializes a new instance of the class, using the specified type name as the data converter for the object this attribute is bound to. - . - + . + ]]> @@ -287,11 +287,11 @@ A that represents the type of the converter class to use for data conversion for the object this attribute is bound to. Initializes a new instance of the class, using the specified type as the data converter for the object this attribute is bound to. - . - + . + ]]> diff --git a/xml/System.ComponentModel/TypeDescriptionProvider.xml b/xml/System.ComponentModel/TypeDescriptionProvider.xml index 42a1ed5ffcd..12b1fefb255 100644 --- a/xml/System.ComponentModel/TypeDescriptionProvider.xml +++ b/xml/System.ComponentModel/TypeDescriptionProvider.xml @@ -839,7 +839,7 @@ method reverses the method to convert a reflection type back into a runtime type. Using the method is preferred over using the property, which was used in earlier versions to return the runtime type. + The method reverses the method to convert a reflection type back into a runtime type. Using the method is preferred over using the property, which was used in earlier versions to return the runtime type. ]]> diff --git a/xml/System.ComponentModel/TypeDescriptor.xml b/xml/System.ComponentModel/TypeDescriptor.xml index 4099a7deebc..2f7a1eb69bc 100644 --- a/xml/System.ComponentModel/TypeDescriptor.xml +++ b/xml/System.ComponentModel/TypeDescriptor.xml @@ -681,7 +681,7 @@ property and the interface are obsolete. For more information, see the property. + The property and the interface are obsolete. For more information, see the property. ]]> @@ -740,9 +740,9 @@ property returns a type that can be passed to the method to define a type description provider for COM types. + The property returns a type that can be passed to the method to define a type description provider for COM types. - The property and other members in this class replace the functionality in the obsolete interface. To implement a mapping layer between a COM object and , add a to handle type . + The property and other members in this class replace the functionality in the obsolete interface. To implement a mapping layer between a COM object and , add a to handle type . ]]> @@ -1453,10 +1453,10 @@ ## Remarks The attributes returned by the method may be dynamically modified from the original component's source listing by extender providers (), filter services (), and attribute filters. - When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. + When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. > [!NOTE] -> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. +> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. @@ -1534,12 +1534,12 @@ ## Remarks Call this version of this method only when you do not have an instance of the object. - For attributes with set to `true`, the attribute collection removes duplicate instances. These are instances in which the property returns equal values. + For attributes with set to `true`, the attribute collection removes duplicate instances. These are instances in which the property returns equal values. - When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. + When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. > [!NOTE] -> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. +> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. ]]> @@ -1614,10 +1614,10 @@ ## Remarks The attributes returned by the method may be dynamically modified from the original components source listing by extender providers (), filter services (), and attribute filters. - When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. + When you define a custom attribute with set to `true`, you must override the property to make it unique. If all instances of your attribute are unique, override to return the object identity of your attribute. If only some instances of your attribute are unique, return a value from that would return equality in those cases. For example, some attributes have a constructor parameter that acts as a unique key. For these attributes, return the value of the constructor parameter from the property. > [!NOTE] -> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. +> The default implementation of returns the type identity regardless of the value of the property. In order to return multiple instances of an attribute from the , your attribute must override the property. ]]> @@ -3235,7 +3235,7 @@ ## Examples - For an example of this method, see the property. + For an example of this method, see the property. ]]> @@ -4784,7 +4784,7 @@ property gets a object that you can pass to the methods to define a type description provider for interface types. + The property gets a object that you can pass to the methods to define a type description provider for interface types. ]]> diff --git a/xml/System.Configuration.Install/AssemblyInstaller.xml b/xml/System.Configuration.Install/AssemblyInstaller.xml index d2d38f77f26..2e74ba5335b 100644 --- a/xml/System.Configuration.Install/AssemblyInstaller.xml +++ b/xml/System.Configuration.Install/AssemblyInstaller.xml @@ -248,7 +248,7 @@ property of an is set to the logfile name. + In the following example, the property of an is set to the logfile name. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyInstaller_Rollback/CPP/assemblyinstaller_rollback.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/AssemblyInstaller/CommandLine/assemblyinstaller_rollback.cs" id="Snippet3"::: @@ -361,7 +361,7 @@ ## Examples - In the following sample, the property of an is displayed to the console. + In the following sample, the property of an is displayed to the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyInstaller_HelpText/CPP/assemblyinstaller_helptext.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/AssemblyInstaller/HelpText/assemblyinstaller_helptext.cs" id="Snippet2"::: @@ -399,7 +399,7 @@ method of each installer contained in the property of this instance. The object specified by the `savedState` parameter is updated to reflect the status of the installation after the contained installers have run. If all the methods succeed, the method is called. Otherwise, the method is called. + This method calls the method of each installer contained in the property of this instance. The object specified by the `savedState` parameter is updated to reflect the status of the installation after the contained installers have run. If all the methods succeed, the method is called. Otherwise, the method is called. @@ -642,7 +642,7 @@ ## Examples - In the following example, an is created by invoking the constructor. The property of this object is set to `true` and the method is invoked on the `MyAssembly_HelpText.exe` assembly. Due to this, the log messages are displayed on the console. + In the following example, an is created by invoking the constructor. The property of this object is set to `true` and the method is invoked on the `MyAssembly_HelpText.exe` assembly. Due to this, the log messages are displayed on the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/AssemblyInstaller_HelpText/CPP/assemblyinstaller_helptext.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/AssemblyInstaller/HelpText/assemblyinstaller_helptext.cs" id="Snippet1"::: diff --git a/xml/System.Configuration.Install/InstallContext.xml b/xml/System.Configuration.Install/InstallContext.xml index 0691dea2762..5a2d922a0d7 100644 --- a/xml/System.Configuration.Install/InstallContext.xml +++ b/xml/System.Configuration.Install/InstallContext.xml @@ -18,30 +18,30 @@ Contains information about the current installation. - is created by an installation executable, such as InstallUtil.exe, that installs assemblies. The installation program invokes the constructor, passing it the default log-file path and command-line parameters. - - Prior to calling its , , , or methods, the installation program sets the property of an to the instance of . Before calling these methods, an that contains an installer collection in the property sets the property of each contained installer. - - The property contains a parsed version of the command line that is entered to run the installation executable. The property contains information such as the path to a log file, whether to display log information on the console, and whether to show a user interface during the installation. Call the method to find out whether a command-line parameter is `true`. - - Use the method to write status messages to the installation log file and the console. - - - -## Examples - The following example demonstrates the constructors, the property and the and methods of the class. - - When the method of the installer is called, it checks for parameters from the command line. Depending on that, it displays the progress messages onto the console and also saves it to the specified log file. - - When the program is invoked without any arguments, an empty is created. When "/LogFile" and "/LogtoConsole" are specified, the is created by passing the respective arguments to . - + is created by an installation executable, such as InstallUtil.exe, that installs assemblies. The installation program invokes the constructor, passing it the default log-file path and command-line parameters. + + Prior to calling its , , , or methods, the installation program sets the property of an to the instance of . Before calling these methods, an that contains an installer collection in the property sets the property of each contained installer. + + The property contains a parsed version of the command line that is entered to run the installation executable. The property contains information such as the path to a log file, whether to display log information on the console, and whether to show a user interface during the installation. Call the method to find out whether a command-line parameter is `true`. + + Use the method to write status messages to the installation log file and the console. + + + +## Examples + The following example demonstrates the constructors, the property and the and methods of the class. + + When the method of the installer is called, it checks for parameters from the command line. Depending on that, it displays the progress messages onto the console and also saves it to the specified log file. + + When the program is invoked without any arguments, an empty is created. When "/LogFile" and "/LogtoConsole" are specified, the is created by passing the respective arguments to . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/InstallContext_InstallContext/CPP/installcontext_installcontext.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet1"::: + ]]> @@ -75,24 +75,24 @@ Initializes a new instance of the class. - [!NOTE] -> This example shows how to use one of the overloaded versions of the constructor. For other examples that might be available, see the individual overload topics. - - When the program is invoked without any arguments, an empty is created. - +> This example shows how to use one of the overloaded versions of the constructor. For other examples that might be available, see the individual overload topics. + + When the program is invoked without any arguments, an empty is created. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/InstallContext_InstallContext/CPP/installcontext_installcontext.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet2"::: + ]]> @@ -120,22 +120,22 @@ The command-line parameters entered when running the installation program, or if none were entered. Initializes a new instance of the class, and creates a log file for the installation. - property. If a log-file path is specified in the command-line parameters, it is used to create the file. If the log file argument is not specified in the command line, the value of the `logFilePath` parameter is used. To suppress the creation of a log file, pass the "/logfile= " command-line parameter. - - - -## Examples - This example is an excerpt of the example in the class overview of class. - - When "/LogFile" and "/LogtoConsole" are specified, the is created by passing the respective arguments to . - + property. If a log-file path is specified in the command-line parameters, it is used to create the file. If the log file argument is not specified in the command line, the value of the `logFilePath` parameter is used. To suppress the creation of a log file, pass the "/logfile= " command-line parameter. + + + +## Examples + This example is an excerpt of the example in the class overview of class. + + When "/LogFile" and "/LogtoConsole" are specified, the is created by passing the respective arguments to . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/InstallContext_InstallContext/CPP/installcontext_installcontext.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet3"::: + ]]> @@ -171,22 +171,22 @@ if the specified parameter is set to "yes", "true", "1", or an empty string (""); otherwise, . - property, which contains a parsed version of the command-line parameters, to determine whether the specified parameter is `true`. - - - -## Examples - This example is an excerpt of the sample in the class overview of the class. - - It uses the method to find out if the `LogtoConsole` parameter has been set. If `yes`, it will then use the method to write status messages to the installation log file and the console. - + property, which contains a parsed version of the command-line parameters, to determine whether the specified parameter is `true`. + + + +## Examples + This example is an excerpt of the sample in the class overview of the class. + + It uses the method to find out if the `LogtoConsole` parameter has been set. If `yes`, it will then use the method to write status messages to the installation log file and the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/InstallContext_InstallContext/CPP/installcontext_installcontext.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet4"::: + ]]> @@ -216,22 +216,22 @@ The message to write. Writes a message to the console and to the log file for the installation. - method. Text written to the log file will not be seen by the user unless InstallUtil.exe is used to run the installation and "/LogToConsole= true" is specified in the command line. - - - -## Examples - This example is an excerpt of the example in the class overview of class. - - It uses the method to find out if the `LogtoConsole` parameter has been set. If `yes`, it will then use the method to write status messages to the installation log file and the console. - + method. Text written to the log file will not be seen by the user unless InstallUtil.exe is used to run the installation and "/LogToConsole= true" is specified in the command line. + + + +## Examples + This example is an excerpt of the example in the class overview of class. + + It uses the method to find out if the `LogtoConsole` parameter has been set. If `yes`, it will then use the method to write status messages to the installation log file and the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/InstallContext_InstallContext/CPP/installcontext_installcontext.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet4"::: + ]]> @@ -258,22 +258,22 @@ Gets the command-line parameters that were entered when InstallUtil.exe was run. A that represents the command-line parameters that were entered when the installation executable was run. - is created, the command-line parameters are parsed into the property. Both the keys and the values of the parameters are strings. - - - -## Examples - This example is an excerpt of the example in the class overview of class. - - The sample retrieves the property to see if any command line argument has been entered by the user. It also uses the method to find out if the `LogtoConsole` parameter has been set. If `yes`, it will then use the method to write status messages to the installation log file and the console. - + is created, the command-line parameters are parsed into the property. Both the keys and the values of the parameters are strings. + + + +## Examples + This example is an excerpt of the example in the class overview of class. + + The sample retrieves the property to see if any command line argument has been entered by the user. It also uses the method to find out if the `LogtoConsole` parameter has been set. If `yes`, it will then use the method to write status messages to the installation log file and the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/InstallContext_InstallContext/CPP/installcontext_installcontext.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallContext/Overview/installcontext_installcontext.vb" id="Snippet6"::: + ]]> diff --git a/xml/System.Configuration.Install/InstallEventArgs.xml b/xml/System.Configuration.Install/InstallEventArgs.xml index fceff91cb1d..34f58a9ea92 100644 --- a/xml/System.Configuration.Install/InstallEventArgs.xml +++ b/xml/System.Configuration.Install/InstallEventArgs.xml @@ -18,22 +18,22 @@ Provides data for the events: , , , , , , , . - contains an that holds information about the current state of the installation. The , , , , , , , and event handlers use this information. - - - -## Examples - The following example demonstrates the constructors and the property of the class. - - There are two new events called `BeforeCommit` and `AfterCommit`. The handlers of these events are invoked from the protected methods named `OnBeforeCommit` and `OnAfterCommit` respectively. These events are raised when the method is called. - + contains an that holds information about the current state of the installation. The , , , , , , , and event handlers use this information. + + + +## Examples + The following example demonstrates the constructors and the property of the class. + + There are two new events called `BeforeCommit` and `AfterCommit`. The handlers of these events are invoked from the protected methods named `OnBeforeCommit` and `OnAfterCommit` respectively. These events are raised when the method is called. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/InstallEventArgs/CPP/installeventargs.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.vb" id="Snippet1"::: + ]]> @@ -78,17 +78,17 @@ Initializes a new instance of the class, and leaves the property empty. - constructors and the property of the class. - - There are two new events called `BeforeCommit` and `AfterCommit`. The handlers of these events are invoked from the protected methods named `OnBeforeCommit` and `OnAfterCommit` respectively. These events are raised when the method is called. - + constructors and the property of the class. + + There are two new events called `BeforeCommit` and `AfterCommit`. The handlers of these events are invoked from the protected methods named `OnBeforeCommit` and `OnAfterCommit` respectively. These events are raised when the method is called. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/InstallEventArgs/CPP/installeventargs.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.vb" id="Snippet1"::: + ]]> @@ -115,17 +115,17 @@ An that represents the current state of the installation. Initializes a new instance of the class, and specifies the value for the property. - constructors and the property of the class. - - There are two new events called `BeforeCommit` and `AfterCommit`. The handlers of these events are invoked from the protected methods named `OnBeforeCommit` and `OnAfterCommit` respectively. These events are raised when the method is called. - + constructors and the property of the class. + + There are two new events called `BeforeCommit` and `AfterCommit`. The handlers of these events are invoked from the protected methods named `OnBeforeCommit` and `OnAfterCommit` respectively. These events are raised when the method is called. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/InstallEventArgs/CPP/installeventargs.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.vb" id="Snippet1"::: + ]]> @@ -153,17 +153,17 @@ Gets an that represents the current state of the installation. An that represents the current state of the installation. - constructors and the property of the class. - - There are two new events called `BeforeCommit` and `AfterCommit`. The handlers of these events are invoked from the protected methods named `OnBeforeCommit` and `OnAfterCommit` respectively. These events are raised when the method is called. - + constructors and the property of the class. + + There are two new events called `BeforeCommit` and `AfterCommit`. The handlers of these events are invoked from the protected methods named `OnBeforeCommit` and `OnAfterCommit` respectively. These events are raised when the method is called. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/InstallEventArgs/CPP/installeventargs.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/InstallEventArgs/Overview/installeventargs.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Configuration.Install/Installer.xml b/xml/System.Configuration.Install/Installer.xml index 89b86c6716a..f964fe663fd 100644 --- a/xml/System.Configuration.Install/Installer.xml +++ b/xml/System.Configuration.Install/Installer.xml @@ -45,15 +45,15 @@ - Invoke the installers. For example, use the InstallUtil.exe to invoke the installers. - The property contains a collection of installers. If this instance of is part of an installer collection, the property is set to the instance that contains the collection. For an example of the use of the collection, see the class. + The property contains a collection of installers. If this instance of is part of an installer collection, the property is set to the instance that contains the collection. For an example of the use of the collection, see the class. - The , , , and methods of the class go through the collection of installers stored in the property, and invokes the corresponding method of each installer. + The , , , and methods of the class go through the collection of installers stored in the property, and invokes the corresponding method of each installer. The , , , and methods are not always called on the same instance. For example, one instance might be used while installing and committing an application, and then the reference to that instance is released. Later, uninstalling the application creates a reference to a new instance, meaning that the method is called by a different instance of . For this reason, in your derived class, do not save the state of a computer in an installer. Instead, use an that is preserved across calls and passed into your , , , and methods. Two situations illustrate the need to save information in the state-saver . First, suppose that your installer sets a registry key. It should save the key's original value in the . If the installation is rolled back, the original value can be restored. Second, suppose the installer replaces an existing file. Save the existing file in a temporary directory and the location of the new location of the file in the . If the installation is rolled back, the newer file is deleted and replaced by the original from the temporary location. - The property contains information about the installation. For example, information about the location of the log file for the installation, the location of the file to save information required by the method, and the command line that was entered when the installation executable was run. + The property contains information about the installation. For example, information about the location of the log file for the installation, the location of the file to save information required by the method, and the command line that was entered when the installation executable was run. @@ -465,16 +465,16 @@ property contains installation information. For example, information about the location of the log file for the installation, the location of the file to save information required by the method, and the command line that was entered when the installation executable was run. + The property contains installation information. For example, information about the location of the log file for the installation, the location of the file to save information required by the method, and the command line that was entered when the installation executable was run. - The program that calls the , , , or methods sets the property with information that the methods need. + The program that calls the , , , or methods sets the property with information that the methods need. - If an installer belongs to an installer collection, the parent installer sets the property before calling any of these methods. The parent installer can be accessed through the property. + If an installer belongs to an installer collection, the parent installer sets the property before calling any of these methods. The parent installer can be accessed through the property. ## Examples - The following example demonstrates the property of the class. The contents of the property contain information about the location of the log file for the installation, the location of the file to save information required by the method, and the command line that was entered when the installation executable was run. These contents are then displayed on the console. + The following example demonstrates the property of the class. The contents of the property contain information about the location of the log file for the installation, the location of the file to save information required by the method, and the command line that was entered when the installation executable was run. These contents are then displayed on the console. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Installer_Context/CPP/installer_context.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/Installer/Context/installer_context.cs" id="Snippet1"::: @@ -514,7 +514,7 @@ property. This property is defined in the class, which, when called, returns the description of the and the command line options for the installation executable, such as the Installutil.exe utility, that can be passed to and understood by the . + The following example demonstrates the property. This property is defined in the class, which, when called, returns the description of the and the command line options for the installation executable, such as the Installutil.exe utility, that can be passed to and understood by the . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Installer_HelpText/CPP/installer_helptext.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/Installer/HelpText/installer_helptext.cs" id="Snippet1"::: @@ -614,14 +614,14 @@ property contains a collection of installers that install objects needed by this instance to correctly install the component. The , , , and methods of the class go through the collection of installers and invokes the corresponding method of each installer. + The property contains a collection of installers that install objects needed by this instance to correctly install the component. The , , , and methods of the class go through the collection of installers and invokes the corresponding method of each installer. - If this instance of is contained in an installer collection, the property is the instance that contains the collection. For an example of the use of the collection, see the class. + If this instance of is contained in an installer collection, the property is the instance that contains the collection. For an example of the use of the collection, see the class. ## Examples - The following example demonstrates the and properties. The property shows the associated with an . + The following example demonstrates the and properties. The property shows the associated with an . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Installer_Installers/CPP/installer_installers.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/Installer/Installers/installer_installers.cs" id="Snippet1"::: @@ -1093,14 +1093,14 @@ is part of an installer collection, the property is set to the instance that contains the collection. For an example of the use of the collection, see the class. + If this instance of is part of an installer collection, the property is set to the instance that contains the collection. For an example of the use of the collection, see the class. - The property contains a collection of installers. The , , , and methods of the class go through the collection of installers and invokes the corresponding method of each installer. + The property contains a collection of installers. The , , , and methods of the class go through the collection of installers and invokes the corresponding method of each installer. ## Examples - The following example demonstrates the property. The property gets the containing the collection that this belongs to. + The following example demonstrates the property. The property gets the containing the collection that this belongs to. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Installer_Installers/CPP/installer_installers.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/Installer/Installers/installer_installers.cs" id="Snippet2"::: diff --git a/xml/System.Configuration.Install/InstallerCollection.xml b/xml/System.Configuration.Install/InstallerCollection.xml index 63e7ed8c48c..81a20ec51d7 100644 --- a/xml/System.Configuration.Install/InstallerCollection.xml +++ b/xml/System.Configuration.Install/InstallerCollection.xml @@ -29,11 +29,11 @@ - The methods add multiple installers to the collection. -- The method and the property, which is the indexer, each add a single installer to the collection at the specified index. +- The method and the property, which is the indexer, each add a single installer to the collection at the specified index. Remove installers through the method. Check whether an installer is in the collection by using the method. Find where an installer is located in the collection by using the method. - The installers in a collection are run when the installer containing the collection, as specified by the property, calls their , , , or methods. + The installers in a collection are run when the installer containing the collection, as specified by the property, calls their , , , or methods. For examples of the usage of an installer collection, see the and classes. @@ -85,7 +85,7 @@ property of the added is set to specify the containing this collection. + The property of the added is set to specify the containing this collection. @@ -139,7 +139,7 @@ property of each added is set to the containing this collection. + The property of each added is set to the containing this collection. @@ -184,7 +184,7 @@ property of each added is set to the containing this collection. + The property of each added is set to the containing this collection. @@ -389,7 +389,7 @@ is placed in the , the property of the is set to the that contains the collection. + When the specified is placed in the , the property of the is set to the that contains the collection. @@ -518,7 +518,7 @@ property of the removed is set to `null`. + The property of the removed is set to `null`. diff --git a/xml/System.Configuration.Install/TransactedInstaller.xml b/xml/System.Configuration.Install/TransactedInstaller.xml index 96e550c2e0b..0709c681935 100644 --- a/xml/System.Configuration.Install/TransactedInstaller.xml +++ b/xml/System.Configuration.Install/TransactedInstaller.xml @@ -18,22 +18,22 @@ Defines an installer that either succeeds completely or fails and leaves the computer in its initial state. - property of this instance. - - - -## Examples - The following example demonstrates the , and methods of the class. - - This example provides an implementation similar to that of [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). It installs assemblies with the options preceding that particular assembly. If an option is not specified for an assembly, the previous assembly's options are used if there is a previous assembly in the list. If either the "/u" or "/uninstall" option is specified, the assemblies are uninstalled. If the "/?" or "/help" option is provided, the help information is displayed to the console. - + property of this instance. + + + +## Examples + The following example demonstrates the , and methods of the class. + + This example provides an implementation similar to that of [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). It installs assemblies with the options preceding that particular assembly. If an option is not specified for an assembly, the previous assembly's options are used if there is a previous assembly in the list. If either the "/u" or "/uninstall" option is specified, the assemblies are uninstalled. If the "/?" or "/help" option is provided, the help information is displayed to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/TransactedInstaller/CPP/transactedinstaller.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/TransactedInstaller/Overview/transactedinstaller.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/TransactedInstaller/Overview/transactedinstaller.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/TransactedInstaller/Overview/transactedinstaller.vb" id="Snippet1"::: + ]]> @@ -81,22 +81,22 @@ An in which this method saves information needed to perform a commit, rollback, or uninstall operation. Performs the installation. - method of each installer contained in the property of this instance. The object referenced by the `savedState` parameter is updated to reflect the status of the installation after the contained installers have run. If all the methods succeed, the method is called. Otherwise, the method is called for each installer. - - - -## Examples - The following example demonstrates the , and methods of the class. - - This example provides an implementation similar to that of InstallUtil.exe. It installs assemblies with the options preceding that particular assembly. If an option is not specified for an assembly, the previous assemblies options are taken if there is a previous assembly in the list. If the '/u' or '/uninstall' option is specified then the assemblies are uninstalled. If the '/?' or '/help' option is provided then the help information is printed to the console. - + method of each installer contained in the property of this instance. The object referenced by the `savedState` parameter is updated to reflect the status of the installation after the contained installers have run. If all the methods succeed, the method is called. Otherwise, the method is called for each installer. + + + +## Examples + The following example demonstrates the , and methods of the class. + + This example provides an implementation similar to that of InstallUtil.exe. It installs assemblies with the options preceding that particular assembly. If an option is not specified for an assembly, the previous assemblies options are taken if there is a previous assembly in the list. If the '/u' or '/uninstall' option is specified then the assemblies are uninstalled. If the '/?' or '/help' option is provided then the help information is printed to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/TransactedInstaller/CPP/transactedinstaller.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/TransactedInstaller/Overview/transactedinstaller.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/TransactedInstaller/Overview/transactedinstaller.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/TransactedInstaller/Overview/transactedinstaller.vb" id="Snippet1"::: + ]]> The parameter is . @@ -136,25 +136,25 @@ An that contains the state of the computer after the installation completed. Removes an installation. - method calls the method of each installer in the property to uninstall any resources set during installation. Any exceptions during uninstallation are ignored. - + method calls the method of each installer in the property to uninstall any resources set during installation. Any exceptions during uninstallation are ignored. + > [!NOTE] -> Although the and methods save the state of the computer after the installations, the file containing the from the `savedState` parameter might have been deleted at some point after the installation was complete. If the file is deleted, the `savedState` parameter is `null`. - - - -## Examples - The following example demonstrates the , and methods of the class. - - This example provides an implementation similar to that of [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). It installs assemblies with the options preceding that particular assembly. If an option is not specified for an assembly, the previous assembly's options are used if there is a previous assembly in the list. If either the "/u" or "/uninstall" option is specified, the assemblies are uninstalled. If the "/?" or "/help" option is provided, the help information is displayed to the console. - +> Although the and methods save the state of the computer after the installations, the file containing the from the `savedState` parameter might have been deleted at some point after the installation was complete. If the file is deleted, the `savedState` parameter is `null`. + + + +## Examples + The following example demonstrates the , and methods of the class. + + This example provides an implementation similar to that of [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). It installs assemblies with the options preceding that particular assembly. If an option is not specified for an assembly, the previous assembly's options are used if there is a previous assembly in the list. If either the "/u" or "/uninstall" option is specified, the assemblies are uninstalled. If the "/?" or "/help" option is provided, the help information is displayed to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/TransactedInstaller/CPP/transactedinstaller.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Configuration.Install/TransactedInstaller/Overview/transactedinstaller.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/TransactedInstaller/Overview/transactedinstaller.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Configuration.Install/TransactedInstaller/Overview/transactedinstaller.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Configuration.Internal/IConfigurationManagerInternal.xml b/xml/System.Configuration.Internal/IConfigurationManagerInternal.xml index 2ca88fcc140..a9052ea941e 100644 --- a/xml/System.Configuration.Internal/IConfigurationManagerInternal.xml +++ b/xml/System.Configuration.Internal/IConfigurationManagerInternal.xml @@ -358,7 +358,7 @@ property is used by during configuration initialization. + The property is used by during configuration initialization. ]]> diff --git a/xml/System.Configuration.Provider/ProviderBase.xml b/xml/System.Configuration.Provider/ProviderBase.xml index e3eef85bc8d..e93ed49237d 100644 --- a/xml/System.Configuration.Provider/ProviderBase.xml +++ b/xml/System.Configuration.Provider/ProviderBase.xml @@ -33,22 +33,22 @@ Provides a base implementation for the extensible provider model. - class is simple, containing only a few basic methods and properties that are common to all providers. Feature-specific providers (such as ) inherit from and establish the necessary methods and properties that the implementation-specific providers for that feature must support. Implementation-specific providers (such as ) inherit in turn from a feature-specific provider (in this case, ). - - The most important aspect of the provider model is that the implementation (for example, whether data is persisted as a text file or in a database) is abstracted from the application code. The type of the implementation-specific provider for the given feature is designated in a configuration file. The feature-level provider then reads in the type from the configuration file and acts as a factory to the feature code. The application developer can then use the feature classes in the application code. The implementation type can be swapped out in the configuration file, eliminating the need to rewrite the code to accommodate the different implementation methodology. - - The providers included with ASP.NET are mostly abstractions of data persistence implementations for features like profiles or membership. However, this model can be applied to any other kind of feature functionality that could be abstracted and implemented in multiple ways. - - - -## Examples - For an example of how to use the class, see [Profile Provider Implementation Example](/previous-versions/aspnet/ta63b872(v=vs.100)). - + class is simple, containing only a few basic methods and properties that are common to all providers. Feature-specific providers (such as ) inherit from and establish the necessary methods and properties that the implementation-specific providers for that feature must support. Implementation-specific providers (such as ) inherit in turn from a feature-specific provider (in this case, ). + + The most important aspect of the provider model is that the implementation (for example, whether data is persisted as a text file or in a database) is abstracted from the application code. The type of the implementation-specific provider for the given feature is designated in a configuration file. The feature-level provider then reads in the type from the configuration file and acts as a factory to the feature code. The application developer can then use the feature classes in the application code. The implementation type can be swapped out in the configuration file, eliminating the need to rewrite the code to accommodate the different implementation methodology. + + The providers included with ASP.NET are mostly abstractions of data persistence implementations for features like profiles or membership. However, this model can be applied to any other kind of feature functionality that could be abstracted and implemented in multiple ways. + + + +## Examples + For an example of how to use the class, see [Profile Provider Implementation Example](/previous-versions/aspnet/ta63b872(v=vs.100)). + ]]> Profile Provider Implementation Example @@ -119,11 +119,11 @@ Gets a brief, friendly description suitable for display in administrative tools or other user interfaces (UIs). A brief, friendly description suitable for display in administrative tools or other UIs. - property is returned as a default. - + property is returned as a default. + ]]> @@ -165,18 +165,18 @@ A collection of the name/value pairs representing the provider-specific attributes specified in the configuration for this provider. Initializes the configuration builder. - prior to performing provider-specific initialization, this method is a central location for preventing double initialization. - - - -## Examples - For an example of how to use , see [Profile Provider Implementation Example](/previous-versions/aspnet/ta63b872(v=vs.100)). - + prior to performing provider-specific initialization, this method is a central location for preventing double initialization. + + + +## Examples + For an example of how to use , see [Profile Provider Implementation Example](/previous-versions/aspnet/ta63b872(v=vs.100)). + ]]> The name of the provider is . @@ -220,11 +220,11 @@ Gets the friendly name used to refer to the provider during configuration. The friendly name used to refer to the provider during configuration. - property also provides a friendly description, the property is used as an identifier for the provider. - + property also provides a friendly description, the property is used as an identifier for the provider. + ]]> diff --git a/xml/System.Configuration.Provider/ProviderCollection.xml b/xml/System.Configuration.Provider/ProviderCollection.xml index fa0e9496f94..a21413d821e 100644 --- a/xml/System.Configuration.Provider/ProviderCollection.xml +++ b/xml/System.Configuration.Provider/ProviderCollection.xml @@ -41,11 +41,11 @@ Represents a collection of provider objects that inherit from . - class utilizes an underlying object to store the provider name/value pairs. - + class utilizes an underlying object to store the provider name/value pairs. + ]]> @@ -78,11 +78,11 @@ Initializes a new instance of the class. - constructor initializes the underlying object used to store the items of the collection. - + constructor initializes the underlying object used to store the items of the collection. + ]]> @@ -122,20 +122,20 @@ The provider to be added. Adds a provider to the collection. - method first checks for any exceptions (as listed in the Exceptions section), and then calls the method. It passes in the object referenced by the `provider` parameter as well as the property of the provider to be used as the key in the object. - + method first checks for any exceptions (as listed in the Exceptions section), and then calls the method. It passes in the object referenced by the `provider` parameter as well as the property of the provider to be used as the key in the object. + ]]> The collection is read-only. is . - The of is . - + The of is . + -or- - + The length of the of is less than 1. @@ -212,11 +212,11 @@ The index of the collection item at which to start the copying process. Copies the contents of the collection to the given array starting at the specified index. - @@ -294,11 +294,11 @@ Returns an object that implements the interface to iterate through the collection. An object that implements to iterate through the collection. - class stores its collection in a object. The method calls the method. - + class stores its collection in a object. The method calls the method. + ]]> @@ -339,11 +339,11 @@ in all cases. - interface. - + interface. + ]]> @@ -457,13 +457,13 @@ Sets the collection to be read-only. - class is read/write by default. The method makes the collection read-only. After a collection is set to read-only, some method calls (such as and will result in an exception. - - Note that most provider-based features will set their object to read-only after creating instances of all of the configured providers. - + class is read/write by default. The method makes the collection read-only. After a collection is set to read-only, some method calls (such as and will result in an exception. + + Note that most provider-based features will set their object to read-only after creating instances of all of the configured providers. + ]]> @@ -503,11 +503,11 @@ Gets the current object. The current object. - interface. - + interface. + ]]> @@ -553,11 +553,11 @@ The index of the array at which to start copying provider instances from the collection. Copies the elements of the to an array, starting at a particular array index. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Configuration/AppSettingsSection.xml b/xml/System.Configuration/AppSettingsSection.xml index 9edc775b9d9..6559f10902f 100644 --- a/xml/System.Configuration/AppSettingsSection.xml +++ b/xml/System.Configuration/AppSettingsSection.xml @@ -33,23 +33,23 @@ Provides configuration system support for the configuration section. This class cannot be inherited. - object, you should use the property of the class or the property of the class. - - - -## Examples - The following example shows how to use the class in a console application. It reads and writes the key/value pairs that are contained by the `appSettings` section. It also shows how to access the property of the class. - + object, you should use the property of the class or the property of the class. + + + +## Examples + The following example shows how to use the class in a console application. It reads and writes the key/value pairs that are contained by the `appSettings` section. It also shows how to access the property of the class. + > [!NOTE] -> Before you compile this code, add a reference in your project to System.Configuration.dll. - +> Before you compile this code, add a reference in your project to System.Configuration.dll. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/CS/UsingAppSettingsSection.cs" id="Snippet21"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/AppSettingsSection.vb" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/UsingAppSettingsSection.vb" id="Snippet21"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/UsingAppSettingsSection.vb" id="Snippet21"::: + ]]> @@ -167,15 +167,15 @@ Gets or sets a configuration file that provides additional settings or overrides the settings specified in the element. A configuration file that provides additional settings or overrides the settings specified in the element. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/CS/UsingAppSettingsSection.cs" id="Snippet22"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/AppSettingsSection.vb" id="Snippet22"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/UsingAppSettingsSection.vb" id="Snippet22"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/UsingAppSettingsSection.vb" id="Snippet22"::: + ]]> @@ -423,15 +423,15 @@ Gets a collection of key/value pairs that contains application settings. A collection of key/value pairs that contains the application settings from the configuration file. - property to read the `appSettings` values. - + property to read the `appSettings` values. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/CS/UsingAppSettingsSection.cs" id="Snippet24"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/AppSettingsSection.vb" id="Snippet24"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/UsingAppSettingsSection.vb" id="Snippet24"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.AppSettingsSection/VB/UsingAppSettingsSection.vb" id="Snippet24"::: + ]]> diff --git a/xml/System.Configuration/ApplicationSettingsBase.xml b/xml/System.Configuration/ApplicationSettingsBase.xml index 08804059c29..011e81d2f2d 100644 --- a/xml/System.Configuration/ApplicationSettingsBase.xml +++ b/xml/System.Configuration/ApplicationSettingsBase.xml @@ -149,9 +149,9 @@ 3. Each has some of its properties set based on other attributes that are optionally present on the wrapper's properties, such as the default value or the settings provider. -4. All other attributes are simply put into an attribute bag, the property of the class. +4. All other attributes are simply put into an attribute bag, the property of the class. -5. All objects are added to a represented by the property of the class. This collection is then passed to the method. +5. All objects are added to a represented by the property of the class. This collection is then passed to the method. As implied by step 3 mentioned previously, natively works with several property attributes, specifically the following: , , and . All other settings attributes are simply passed through to the appropriate underlying provider. @@ -246,7 +246,7 @@ property to the value of the `settingsKey` parameter. This property is useful in disambiguating different instances of the settings wrapper class in the same application domain. + This constructor initializes the property to the value of the `settingsKey` parameter. This property is useful in disambiguating different instances of the settings wrapper class in the same application domain. For information about how reflection is used during the instantiation of a wrapper class, see the default constructor. @@ -294,7 +294,7 @@ ## Remarks The object specified by the `owner` parameter acts as the owner of the current instance of this applications settings class. During the initialization of the settings wrapper class derived from , the owner's site is queried for a . If one exists, it is used in preference to native settings provider for all the properties of the wrapper class, as specified by the . - This constructor initializes the property to the value of the `settingsKey` parameter. This property is useful in disambiguating different instances of the wrapper class in the same application domain. + This constructor initializes the property to the value of the `settingsKey` parameter. This property is useful in disambiguating different instances of the wrapper class in the same application domain. For information about how reflection is used during the instantiation of a wrapper class, see the default constructor. @@ -350,7 +350,7 @@ ## Remarks Each settings wrapper class derived from has a context associated with it. The context is passed to the settings provider for each property to identify how the property is used. Context therefore acts as a hint to help the settings provider determine how best to persist the associated application settings values. - In contrast, the property enables the settings provider to disambiguate multiple instances of the same wrapper class. + In contrast, the property enables the settings provider to disambiguate multiple instances of the same wrapper class. ]]> @@ -452,7 +452,7 @@ property, also known as the indexer, is routinely used in the settings wrapper class derived from . binds the public property of the wrapper class to the corresponding settings property. + The property, also known as the indexer, is routinely used in the settings wrapper class derived from . binds the public property of the wrapper class to the corresponding settings property. raises several events depending on the operation being performed: @@ -725,7 +725,7 @@ property reflects over the metadata of the settings wrapper class, which is derived from , to dynamically determine the set of available application settings properties. + The `get` accessor of the property reflects over the metadata of the settings wrapper class, which is derived from , to dynamically determine the set of available application settings properties. The class natively recognizes certain characteristics of an application setting, such as its name, property type, settings provider, default value, read only status, and a serialization preference. These characteristics are mirrored as properties in the class. All other attributes of the settings property are just passed through to its associated settings provider. @@ -917,7 +917,7 @@ ## Remarks The method clears the currently cached property values, causing a reload of these values from persistent storage when they are subsequently accessed. This method performs the following actions: -- It clears the currently cached properties by clearing the collection represented by the property. +- It clears the currently cached properties by clearing the collection represented by the property. - It raises the event for every member of the collection. @@ -1050,7 +1050,7 @@ ## Examples - The following code example shows the method being called from the event handler for the primary form. This method also appends an extra period to the settings property that is associated with the form's property. + The following code example shows the method being called from the event handler for the primary form. This method also appends an extra period to the settings property that is associated with the form's property. The full code example is listed in the class overview. @@ -1170,7 +1170,7 @@ property is provided to enable client code, and in particular the settings provider, to disambiguate between multiple instances of the same application settings class. + The property is provided to enable client code, and in particular the settings provider, to disambiguate between multiple instances of the same application settings class. Unless the settings wrapper class is designed using the singleton pattern, there can be multiple instances of the same application settings class in a single application. The value of should be set according to how the property values are intended to be shared. @@ -1178,9 +1178,9 @@ - If the settings properties of the wrapper are intended to be per instance, then should have a unique value for every instance. The version of the constructor enables you to initialize to a unique string. - In contrast, the property provides hints to the settings provider to enable it to persist values in an efficient and orderly manner. + In contrast, the property provides hints to the settings provider to enable it to persist values in an efficient and orderly manner. - The class contains a similar property that helps identify the source of the event. + The class contains a similar property that helps identify the source of the event. ]]> diff --git a/xml/System.Configuration/ClientSettingsSection.xml b/xml/System.Configuration/ClientSettingsSection.xml index aa88af089bb..c6e2930e29d 100644 --- a/xml/System.Configuration/ClientSettingsSection.xml +++ b/xml/System.Configuration/ClientSettingsSection.xml @@ -88,7 +88,7 @@ constructor initializes the property. + The default constructor initializes the property. ]]> @@ -179,7 +179,7 @@ property is itself a configuration property. + The property is itself a configuration property. ]]> diff --git a/xml/System.Configuration/CommaDelimitedStringCollection.xml b/xml/System.Configuration/CommaDelimitedStringCollection.xml index 6daa15c9c64..dc10e8f76fc 100644 --- a/xml/System.Configuration/CommaDelimitedStringCollection.xml +++ b/xml/System.Configuration/CommaDelimitedStringCollection.xml @@ -33,19 +33,19 @@ Represents a collection of string elements separated by commas. This class cannot be inherited. - type. - + type. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/CS/CommaDelimitedStringCollection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet1"::: + ]]> @@ -79,14 +79,14 @@ Creates a new instance of the class. - constructor. This code example is part of a larger example provided for the class overview. - + constructor. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/CS/CommaDelimitedStringCollection.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet2"::: + ]]> @@ -126,11 +126,11 @@ A string value. Adds a string to the comma-delimited collection. - property to be set to `true`. - + property to be set to `true`. + ]]> @@ -170,19 +170,19 @@ An array of strings to add to the collection. Adds all the strings in a string array to the collection. - method. This code example is part of a larger example provided for the class overview. - + method. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/CS/CommaDelimitedStringCollection.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet3"::: + ]]> @@ -219,11 +219,11 @@ Clears the collection. - property to be set to `true`. - + property to be set to `true`. + ]]> @@ -300,19 +300,19 @@ The value of the new element to add to the collection. Adds a string element to the collection at the specified index. - property to be set to `true`. - - - -## Examples - The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class overview. - + property to be set to `true`. + + + +## Examples + The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/CS/CommaDelimitedStringCollection.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet9"::: + ]]> @@ -350,19 +350,19 @@ if the has been modified; otherwise, . - property is `true` after the , , , or method has been called. Also, the property is `true` after the property is used to modify an element of the string collection. - - - -## Examples - The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class overview. - + property is `true` after the , , , or method has been called. Also, the property is `true` after the property is used to modify an element of the string collection. + + + +## Examples + The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/CS/CommaDelimitedStringCollection.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet7"::: + ]]> @@ -400,19 +400,19 @@ if the specified string element in the is read-only; otherwise, . - method on the class. - - - -## Examples - The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class overview. - + method on the class. + + + +## Examples + The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/CS/CommaDelimitedStringCollection.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet8"::: + ]]> @@ -453,11 +453,11 @@ Gets or sets a string element in the collection based on the index. A string element in the collection. - property to be set to `true`. - + property to be set to `true`. + ]]> @@ -497,19 +497,19 @@ The string to remove. Removes a string element from the collection. - property to be set to `true`. - - - -## Examples - The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class overview. - + property to be set to `true`. + + + +## Examples + The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/CS/CommaDelimitedStringCollection.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.CommaDelimitedStringCollection/VB/CommaDelimitedStringCollection.vb" id="Snippet10"::: + ]]> @@ -546,11 +546,11 @@ Sets the collection object to read-only. - collection can be modified, call the method. - + collection can be modified, call the method. + ]]> diff --git a/xml/System.Configuration/Configuration.xml b/xml/System.Configuration/Configuration.xml index 1de3888dbd7..e6e8937b93e 100644 --- a/xml/System.Configuration/Configuration.xml +++ b/xml/System.Configuration/Configuration.xml @@ -133,12 +133,12 @@ Note: If you use a static method that takes a path property to access and change the `appSettings` configuration section defined by default in the open configuration file. + Use the property to access and change the `appSettings` configuration section defined by default in the open configuration file. ## Examples - The following code example demonstrates how to use the property. + The following code example demonstrates how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.Configuration/CS/Configuration.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.Configuration/VB/Configuration.vb" id="Snippet5"::: @@ -223,12 +223,12 @@ Note: If you use a static method that takes a path property to access and change the `connectionStrings` configuration section defined in the open configuration file. + Use the property to access and change the `connectionStrings` configuration section defined in the open configuration file. ## Examples - The following code example demonstrates how to use the property. + The following code example demonstrates how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.Configuration/CS/Configuration.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.Configuration/VB/Configuration.vb" id="Snippet6"::: @@ -277,7 +277,7 @@ Note: If you use a static method that takes a path ## Examples - The following code example demonstrates how to use the property. + The following code example demonstrates how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.Configuration/CS/Configuration.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.Configuration/VB/Configuration.vb" id="Snippet7"::: @@ -322,12 +322,12 @@ Note: If you use a static method that takes a path property represents a merged view and no actual file exists for the application, the path to the parent configuration file is returned. + If the value for this property represents a merged view and no actual file exists for the application, the path to the parent configuration file is returned. ## Examples - The following code example demonstrates how to use the property. + The following code example demonstrates how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.Configuration/CS/Configuration.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.Configuration/VB/Configuration.vb" id="Snippet8"::: @@ -470,14 +470,14 @@ Note: If you use a static method that takes a path property also returns `true` when the resource represented by this object inherits settings from a Web.config file. + The property also returns `true` when the resource represented by this object inherits settings from a Web.config file. - The property returns `false` when this object represents a location-specific configuration. + The property returns `false` when this object represents a location-specific configuration. ## Examples - The following code example demonstrates how to use the property. + The following code example demonstrates how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.Configuration/CS/Configuration.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.Configuration/VB/Configuration.vb" id="Snippet9"::: @@ -521,7 +521,7 @@ Note: If you use a static method that takes a path property applies only when the property returns `true`. If this configuration inherits all of its settings, or no locations are defined, an empty collection is returned. + The property applies only when the property returns `true`. If this configuration inherits all of its settings, or no locations are defined, an empty collection is returned. ]]> @@ -647,7 +647,7 @@ Note: If you use a static method that takes a path method persists any configuration settings that have been modified since this object was created. If a configuration file does not exist at the physical location represented by the property, a new configuration file will be created to contain any settings that are different from the inherited configuration. + The method persists any configuration settings that have been modified since this object was created. If a configuration file does not exist at the physical location represented by the property, a new configuration file will be created to contain any settings that are different from the inherited configuration. If the configuration file has changed since this object was created, a run-time error occurs. @@ -703,7 +703,7 @@ Note: If you use a static method that takes a path ## Remarks The method persists configuration settings in the object based on the `saveMode` parameter. - If a configuration file does not exist at the physical location represented by the property, a new configuration file will be created to contain any settings that are different from the inherited configuration. + If a configuration file does not exist at the physical location represented by the property, a new configuration file will be created to contain any settings that are different from the inherited configuration. If the configuration file has changed since this object was created, a run-time error occurs. @@ -770,7 +770,7 @@ Note: If you use a static method that takes a path ## Remarks The method persists configuration settings in the object based on the `saveMode` and `forceSaveAll` parameters. - If a configuration file does not exist at the physical location represented by the property, a new configuration file will be created to contain any settings that are different from the inherited configuration. + If a configuration file does not exist at the physical location represented by the property, a new configuration file will be created to contain any settings that are different from the inherited configuration. If the configuration file has changed since this object was created, a run-time error occurs. @@ -837,7 +837,7 @@ Note: If you use a static method that takes a path If a configuration file does not exist at the physical location represented by the - property, a new configuration file will be created to contain any settings that are different from the inherited configuration. + property, a new configuration file will be created to contain any settings that are different from the inherited configuration. If the configuration file has changed since this object was created, a run-time error occurs. @@ -892,7 +892,7 @@ Note: If you use a static method that takes a path ## Remarks The method persists configuration settings in the object to a new file based on the `saveMode` parameter. - If a configuration file does not exist at the physical location represented by the property, a new configuration file will be created to contain any settings that are different from the inherited configuration. + If a configuration file does not exist at the physical location represented by the property, a new configuration file will be created to contain any settings that are different from the inherited configuration. If the configuration file has changed since this object was created, a run-time error occurs. @@ -950,7 +950,7 @@ Note: If you use a static method that takes a path ## Remarks The method persists configuration settings in the object to a new file based on the `saveMode` and `forceSaveAll` parameters. - If a configuration file does not exist at the physical location represented by the property, a new configuration file will be created to contain any settings that are different from the inherited configuration. + If a configuration file does not exist at the physical location represented by the property, a new configuration file will be created to contain any settings that are different from the inherited configuration. If the configuration file has changed since this object was created, a run-time error occurs. @@ -1003,12 +1003,12 @@ Note: If you use a static method that takes a path property to retrieve the object representing the collection of section groups for this object. If this object represents an inherited view, the merged list of section groups will be returned. + Configuration sections can be combined into groups for convenience and added functionality. Access the property to retrieve the object representing the collection of section groups for this object. If this object represents an inherited view, the merged list of section groups will be returned. ## Examples - The following code example demonstrates how to use the property. + The following code example demonstrates how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.Configuration/CS/Configuration.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.Configuration/VB/Configuration.vb" id="Snippet10"::: @@ -1052,12 +1052,12 @@ Note: If you use a static method that takes a path property to retrieve a object representing the collection of sections for this object. If this object represents a merged configuration, the merged list of sections will be returned. + Access the property to retrieve a object representing the collection of sections for this object. If this object represents a merged configuration, the merged list of sections will be returned. ## Examples - The following example shows how to retrieve the property value and to display the number of the sections in the collection. + The following example shows how to retrieve the property value and to display the number of the sections in the collection. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.Configuration/CS/Configuration.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.Configuration/VB/Configuration.vb" id="Snippet11"::: diff --git a/xml/System.Configuration/ConfigurationCollectionAttribute.xml b/xml/System.Configuration/ConfigurationCollectionAttribute.xml index 6f4c266ecdd..7d0694c6a81 100644 --- a/xml/System.Configuration/ConfigurationCollectionAttribute.xml +++ b/xml/System.Configuration/ConfigurationCollectionAttribute.xml @@ -189,12 +189,12 @@ property allows you to assign a different name to the configuration element. For example, you could use `addUrl` instead of "add". + The property allows you to assign a different name to the configuration element. For example, you could use `addUrl` instead of "add". ## Examples - The following example shows how to use the property. + The following example shows how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationCollectionAttribute/CS/customcollectionsection.cs" id="Snippet20"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationCollectionAttribute/VB/customcollectionsection.vb" id="Snippet20"::: @@ -238,7 +238,7 @@ property allows you to assign a different name to the `` configuration element. For example, you could use `clearUrls` instead of "clear". + The property allows you to assign a different name to the `` configuration element. For example, you could use `clearUrls` instead of "clear". @@ -321,7 +321,7 @@ property is used by reflection to get the configuration element type. + The property is used by reflection to get the configuration element type. ]]> @@ -362,12 +362,12 @@ property allows you to assign a different name to the `` configuration element. For example, you could use `removeUrl` instead of "remove". + The property allows you to assign a different name to the `` configuration element. For example, you could use `removeUrl` instead of "remove". ## Examples - The following example shows how to use the property. + The following example shows how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationCollectionAttribute/CS/customcollectionsection.cs" id="Snippet20"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationCollectionAttribute/VB/customcollectionsection.vb" id="Snippet20"::: diff --git a/xml/System.Configuration/ConfigurationElement.xml b/xml/System.Configuration/ConfigurationElement.xml index 3c50d92540b..fe2806f15ac 100644 --- a/xml/System.Configuration/ConfigurationElement.xml +++ b/xml/System.Configuration/ConfigurationElement.xml @@ -185,7 +185,7 @@ property makes it easy to determine which version of .NET is targeted. The property of the top-level instance indicates the targeted framework version. + The property makes it easy to determine which version of .NET is targeted. The property of the top-level instance indicates the targeted framework version. ]]> @@ -290,7 +290,7 @@ property. + The following example shows how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet80"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet80"::: @@ -413,7 +413,7 @@ ## Remarks A object provides the context necessary for a object to make decisions based upon where it is being evaluated. - The object provides environment details related to an element of the configuration. For example, you can use the property to determine whether a was set in Machine.config, or you can determine which hierarchy a element belongs to by using the property. + The object provides environment details related to an element of the configuration. For example, you can use the property to determine whether a was set in Machine.config, or you can determine which hierarchy a element belongs to by using the property. ]]> @@ -838,7 +838,7 @@ property to get or set the values of a object. + Use the property to get or set the values of a object. In C#, this property is the indexer for the class. @@ -892,7 +892,7 @@ property to get or set the values of a object. + Use the property to get or set the values of a object. In C#, this property is the indexer for the class. @@ -974,10 +974,10 @@ property allows you to lock all the attributes at once, with the exception of the one you specify. To do that, you use the method, as explained in the Example section. + The property allows you to lock all the attributes at once, with the exception of the one you specify. To do that, you use the method, as explained in the Example section. > [!NOTE] -> The property allows you to prevent the child configuration elements of the element to which you apply the rule from being modified. Use the property if you want to put a general lock on the parent element itself and its child elements. +> The property allows you to prevent the child configuration elements of the element to which you apply the rule from being modified. Use the property if you want to put a general lock on the parent element itself and its child elements. @@ -1030,15 +1030,15 @@ property allows you to lock all the elements at once, except for the one you specify. + The property allows you to lock all the elements at once, except for the one you specify. > [!NOTE] -> The property allows you to prevent the child configuration elements of the element to which you apply the rule from being modified. Use the property if you want to put a general lock on the element itself and its child elements. +> The property allows you to prevent the child configuration elements of the element to which you apply the rule from being modified. Use the property if you want to put a general lock on the element itself and its child elements. ## Examples - The following example shows how to use the property. + The following example shows how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ConfigurationElement.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ConfigurationElement.vb" id="Snippet5"::: @@ -1083,17 +1083,17 @@ property allows you to lock all the attributes you specify. + The property allows you to lock all the attributes you specify. To do that you use the method, as explained in the Example section. > [!NOTE] -> The property allows you to prevent the child configuration elements of the element to which you apply the rule from being modified. Use if you want to put a general lock on the element itself and its child elements. +> The property allows you to prevent the child configuration elements of the element to which you apply the rule from being modified. Use if you want to put a general lock on the element itself and its child elements. ## Examples - The following example shows how to use the property. + The following example shows how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ConfigurationElement.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ConfigurationElement.vb" id="Snippet8"::: @@ -1141,17 +1141,17 @@ property allows you to lock all the elements you specify. + The property allows you to lock all the elements you specify. To do that, you use the method, as explained in the next example. > [!NOTE] -> The property allows you to prevent the child configuration elements of the element to which you apply the rule from being modified. Use if you want to put a general lock on the element itself and its child elements. +> The property allows you to prevent the child configuration elements of the element to which you apply the rule from being modified. Use if you want to put a general lock on the element itself and its child elements. ## Examples - The following example shows how to use the property. + The following example shows how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ConfigurationElement.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ConfigurationElement.vb" id="Snippet4"::: @@ -1197,7 +1197,7 @@ property if you want to put a general lock on the element itself and its child elements. + Use the property if you want to put a general lock on the element itself and its child elements. @@ -1488,12 +1488,12 @@ property, also called the property bag, contains all the properties (attributes) that apply to the element. + The property, also called the property bag, contains all the properties (attributes) that apply to the element. ## Examples - For an example that shows how to use the property, refer to the class. + For an example that shows how to use the property, refer to the class. ]]> diff --git a/xml/System.Configuration/ConfigurationElementCollection.xml b/xml/System.Configuration/ConfigurationElementCollection.xml index d3997ddf31a..f742d2c9acf 100644 --- a/xml/System.Configuration/ConfigurationElementCollection.xml +++ b/xml/System.Configuration/ConfigurationElementCollection.xml @@ -967,7 +967,7 @@ ## Examples - The following code example shows how to get the property. + The following code example shows how to get the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.configuration.configurationelementcollection/cs/customcollectionsection.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.configuration.configurationelementcollection/vb/customcollectionsection.vb" id="Snippet5"::: @@ -1206,7 +1206,7 @@ property to name a custom . + Override the property to name a custom . ]]> @@ -1248,7 +1248,7 @@ property to `true` causes a `` directive to be written to the configuration file when the collection is serialized. + Setting the property to `true` causes a `` directive to be written to the configuration file when the collection is serialized. ]]> diff --git a/xml/System.Configuration/ConfigurationElementCollectionType.xml b/xml/System.Configuration/ConfigurationElementCollectionType.xml index ab76908b947..b569e511b0d 100644 --- a/xml/System.Configuration/ConfigurationElementCollectionType.xml +++ b/xml/System.Configuration/ConfigurationElementCollectionType.xml @@ -32,13 +32,13 @@ Specifies the type of a object. - property. It is used by the configuration system during run time to correctly merge configuration settings. It is also used when creating a custom class that extends . - - By default, the type of a object is `AddRemoveClearMap`. If a `BasicMap` is required, override the property when extending . - + property. It is used by the configuration system during run time to correctly merge configuration settings. It is also used when creating a custom class that extends . + + By default, the type of a object is `AddRemoveClearMap`. If a `BasicMap` is required, override the property when extending . + ]]> diff --git a/xml/System.Configuration/ConfigurationErrorsException.xml b/xml/System.Configuration/ConfigurationErrorsException.xml index b99a2a8b7b0..5a2025e5306 100644 --- a/xml/System.Configuration/ConfigurationErrorsException.xml +++ b/xml/System.Configuration/ConfigurationErrorsException.xml @@ -44,35 +44,35 @@ The exception that is thrown when a configuration error has occurred. - exception is thrown when any error occurs while configuration information is being read or written. - - - -## Examples - The following code example creates a custom section and generates a exception when it modifies its properties. - + exception is thrown when any error occurs while configuration information is being read or written. + + + +## Examples + The following code example creates a custom section and generates a exception when it modifies its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/CS/ConfigurationErrorsException.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/VB/ConfigurationErrorsException.vb" id="Snippet1"::: - - The following example is a configuration excerpt used by the previous example. - -```xml - - - -
- - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/VB/ConfigurationErrorsException.vb" id="Snippet1"::: + + The following example is a configuration excerpt used by the previous example. + +```xml + + + +
+ + + +``` + ]]> @@ -492,19 +492,19 @@ Gets a description of why this configuration exception was thrown. A description of why this was thrown. - property does not contain the name of the configuration file or the line number at which this exception occurred. If you want a message that contains the name of the configuration file and the line number, along with the message, use the property. - - - -## Examples - The following code example shows how to get the property value. - + property does not contain the name of the configuration file or the line number at which this exception occurred. If you want a message that contains the name of the configuration file and the line number, along with the message, use the property. + + + +## Examples + The following code example shows how to get the property value. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/CS/ConfigurationErrorsException.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/VB/ConfigurationErrorsException.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/VB/ConfigurationErrorsException.vb" id="Snippet6"::: + ]]> @@ -541,11 +541,11 @@ Gets a collection of errors that detail the reasons this exception was thrown. An object that contains errors that identify the reasons this exception was thrown. - property collects as many errors as possible that might occur during an operation, such as reading a configuration file. The exception thrown shows only the first error. You can access to see all the errors issued. - + property collects as many errors as possible that might occur during an operation, such as reading a configuration file. The exception thrown shows only the first error. You can access to see all the errors issued. + ]]> @@ -582,14 +582,14 @@ Gets the path to the configuration file that caused this configuration exception to be thrown. The path to the configuration file that caused this to be thrown. - property value. - + property value. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/CS/ConfigurationErrorsException.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/VB/ConfigurationErrorsException.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/VB/ConfigurationErrorsException.vb" id="Snippet4"::: + ]]> @@ -639,11 +639,11 @@ Gets the path to the configuration file from which the internal object was loaded when this configuration exception was thrown. The path to the configuration file from which the internal object was loaded when this configuration exception was thrown. - method returns the name of the configuration file that contains the object being parsed when the exception occurred. - + method returns the name of the configuration file that contains the object being parsed when the exception occurred. + ]]> @@ -684,11 +684,11 @@ Gets the path to the configuration file that the internal was reading when this configuration exception was thrown. The path of the configuration file the internal object was accessing when the exception occurred. - method returns the name of the configuration file that the object was accessing when the exception occurred. - + method returns the name of the configuration file that the object was accessing when the exception occurred. + ]]> @@ -738,11 +738,11 @@ Gets the line number within the configuration file that the internal object represented when this configuration exception was thrown. The line number within the configuration file that contains the object being parsed when this configuration exception was thrown. - method returns the name of the configuration file that contains the object being parsed when the exception occurred. - + method returns the name of the configuration file that contains the object being parsed when the exception occurred. + ]]> @@ -783,11 +783,11 @@ Gets the line number within the configuration file that the internal object was processing when this configuration exception was thrown. The line number within the configuration file that the object was accessing when the exception occurred. - method returns the name of the configuration file that the object was accessing when the exception occurred. - + method returns the name of the configuration file that the object was accessing when the exception occurred. + ]]> @@ -839,11 +839,11 @@ The contextual information about the source or destination. Sets the object with the file name and line number at which this configuration exception occurred. - method sets a object with the file name and line number at which this exception occurred. During deserialization, the exception is reconstituted from the object that is transmitted over the stream. - + method sets a object with the file name and line number at which this exception occurred. During deserialization, the exception is reconstituted from the object that is transmitted over the stream. + ]]> @@ -880,14 +880,14 @@ Gets the line number within the configuration file at which this configuration exception was thrown. The line number within the configuration file at which this exception was thrown. - property value. - + property value. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/CS/ConfigurationErrorsException.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/VB/ConfigurationErrorsException.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/VB/ConfigurationErrorsException.vb" id="Snippet5"::: + ]]> @@ -924,14 +924,14 @@ Gets an extended description of why this configuration exception was thrown. An extended description of why this exception was thrown. - property value. - + property value. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/CS/ConfigurationErrorsException.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/VB/ConfigurationErrorsException.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationErrorsException/VB/ConfigurationErrorsException.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Configuration/ConfigurationException.xml b/xml/System.Configuration/ConfigurationException.xml index a1c6a709a8f..31aaa7c156b 100644 --- a/xml/System.Configuration/ConfigurationException.xml +++ b/xml/System.Configuration/ConfigurationException.xml @@ -45,14 +45,14 @@ The exception that is thrown when a configuration system error has occurred. - exception is thrown if the application attempts to read or write data to the configuration file but is unsuccessful. Some possible reasons for this can include malformed XML in the configuration file, file permission issues, and configuration properties with values that are not valid. - + exception is thrown if the application attempts to read or write data to the configuration file but is unsuccessful. Some possible reasons for this can include malformed XML in the configuration file, file permission issues, and configuration properties with values that are not valid. + > [!NOTE] -> The object is maintained for backward compatibility. The object replaces it for the configuration system. - +> The object is maintained for backward compatibility. The object replaces it for the configuration system. + ]]> @@ -495,11 +495,11 @@ Gets a description of why this configuration exception was thrown. A description of why this exception was thrown. - property does not contain the name of the configuration file, nor the line number at which this exception occurred. If you want a message that contains the name of the configuration file and the line number, along with the message returned by the property, use the property. - + property does not contain the name of the configuration file, nor the line number at which this exception occurred. If you want a message that contains the name of the configuration file and the line number, along with the message returned by the property, use the property. + ]]> @@ -590,11 +590,11 @@ The contextual information about the source or destination. Sets the object with the file name and line number at which this configuration exception occurred. - method sets a object with the file name and line number at which this exception occurred. During deserialization, the exception is reconstituted from the object that is transmitted over the stream. - + method sets a object with the file name and line number at which this exception occurred. During deserialization, the exception is reconstituted from the object that is transmitted over the stream. + ]]> @@ -774,11 +774,11 @@ Gets an extended description of why this configuration exception was thrown. An extended description of why this exception was thrown. - property contains a concatenation of the , , and properties. - + property contains a concatenation of the , , and properties. + ]]> diff --git a/xml/System.Configuration/ConfigurationLocation.xml b/xml/System.Configuration/ConfigurationLocation.xml index dd403442216..2f56abe1a58 100644 --- a/xml/System.Configuration/ConfigurationLocation.xml +++ b/xml/System.Configuration/ConfigurationLocation.xml @@ -33,19 +33,19 @@ Represents a element within a configuration file. - class represents a single `location` element within a configuration file. Locations are used to specify configuration settings that apply only to a specified resource, such as a specific page, file, or subdirectory, within your Web application. Use the class to obtain the path and the object that applies to the specified resource. - - - -## Examples - In the following code example, the Web configuration for the application `MySampleApp` is loaded, and then the locations defined in the configuration are displayed. - + class represents a single `location` element within a configuration file. Locations are used to specify configuration settings that apply only to a specified resource, such as a specific page, file, or subdirectory, within your Web application. Use the class to obtain the path and the object that applies to the specified resource. + + + +## Examples + In the following code example, the Web configuration for the application `MySampleApp` is loaded, and then the locations defined in the configuration are displayed. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/ConfigurationLocationCollection/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/ConfigurationLocationCollection/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/ConfigurationLocationCollection/VB/sample.vb" id="Snippet1"::: + ]]> @@ -117,22 +117,22 @@ Gets the relative path to the resource whose configuration settings are represented by this object. The relative path to the resource whose configuration settings are represented by this . - property is relative to the root of your Web site. - + property is relative to the root of your Web site. + > [!NOTE] -> The property might contain a comma-delimited list of paths to which the configuration setting applies. - - - -## Examples - The following code example shows how to access the property and display the value returned to the console. - +> The property might contain a comma-delimited list of paths to which the configuration setting applies. + + + +## Examples + The following code example shows how to access the property and display the value returned to the console. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/ConfigurationLocationCollection/CS/sample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/ConfigurationLocationCollection/VB/sample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/ConfigurationLocationCollection/VB/sample.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.Configuration/ConfigurationLocationCollection.xml b/xml/System.Configuration/ConfigurationLocationCollection.xml index aa3bb0ed33f..4ae7bf145d5 100644 --- a/xml/System.Configuration/ConfigurationLocationCollection.xml +++ b/xml/System.Configuration/ConfigurationLocationCollection.xml @@ -33,22 +33,22 @@ Contains a collection of objects. - class to iterate through a collection of objects, which represent the resources for which location-specific configuration settings are defined. is the type returned by the property. - + class to iterate through a collection of objects, which represent the resources for which location-specific configuration settings are defined. is the type returned by the property. + > [!NOTE] -> The class might not reference the collection of objects in the order that they are specified in the configuration file. - - - -## Examples - In the following code example, the Web configuration for the application `MySampleApp` is loaded, and the locations defined in this configuration are displayed by iterating through the object returned by the property. - +> The class might not reference the collection of objects in the order that they are specified in the configuration file. + + + +## Examples + In the following code example, the Web configuration for the application `MySampleApp` is loaded, and the locations defined in this configuration are displayed by iterating through the object returned by the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/ConfigurationLocationCollection/CS/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/ConfigurationLocationCollection/VB/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/ConfigurationLocationCollection/VB/sample.vb" id="Snippet1"::: + ]]> @@ -89,11 +89,11 @@ Gets the object at the specified index. The at the specified index. - accessor to the class to get a specific object from the collection by specifying its index within the collection. - + accessor to the class to get a specific object from the collection by specifying its index within the collection. + ]]> diff --git a/xml/System.Configuration/ConfigurationLockCollection.xml b/xml/System.Configuration/ConfigurationLockCollection.xml index f6a7c91ea48..18007bb7697 100644 --- a/xml/System.Configuration/ConfigurationLockCollection.xml +++ b/xml/System.Configuration/ConfigurationLockCollection.xml @@ -41,19 +41,19 @@ Contains a collection of locked configuration objects. This class cannot be inherited. - collection exists for the locked attributes of a configuration section, and is accessed through the property of the class. Another collection exists for the locked elements of a configuration section, and is accessed through the property of the class. - - - -## Examples - The following code example demonstrates how to use the type. - + collection exists for the locked attributes of a configuration section, and is accessed through the property of the class. Another collection exists for the locked elements of a configuration section, and is accessed through the property of the class. + + + +## Examples + The following code example demonstrates how to use the type. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/CS/ConfigurationLockCollection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet1"::: + ]]> @@ -96,19 +96,19 @@ The name of the configuration object. Locks a configuration object by adding it to the collection. - collection specifies that the configuration object is locked and cannot be modified until it has been removed from the collection. - - - -## Examples - The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class. - + collection specifies that the configuration object is locked and cannot be modified until it has been removed from the collection. + + + +## Examples + The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/CS/ConfigurationLockCollection.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet3"::: + ]]> Occurs when the does not match an existing configuration object within the collection. @@ -146,14 +146,14 @@ Gets a list of configuration objects contained in the collection. A comma-delimited string that lists the lock configuration objects in the collection. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/CS/ConfigurationLockCollection.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet5"::: + ]]> @@ -190,14 +190,14 @@ Clears all configuration objects from the collection. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/CS/ConfigurationLockCollection.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet11"::: + ]]> @@ -315,14 +315,14 @@ Gets the number of locked configuration objects contained in the collection. The number of locked configuration objects contained in the collection. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/CS/ConfigurationLockCollection.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet4"::: + ]]> @@ -398,14 +398,14 @@ if the collection has parent elements; otherwise, . - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/CS/ConfigurationLockCollection.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet7"::: + ]]> @@ -443,14 +443,14 @@ if the collection has been modified; otherwise, . - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/CS/ConfigurationLockCollection.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet8"::: + ]]> @@ -492,14 +492,14 @@ if the specified configuration object in the collection is read-only; otherwise, . - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/CS/ConfigurationLockCollection.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet9"::: + ]]> The specified configuration object is not in the collection. @@ -578,14 +578,14 @@ The name of the configuration object. Removes a configuration object from the collection. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/CS/ConfigurationLockCollection.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet10"::: + ]]> Occurs when the does not match an existing configuration object within the collection. @@ -626,14 +626,14 @@ A comma-delimited string. Locks a set of configuration objects based on the supplied list. - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/CS/ConfigurationLockCollection.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationLockCollection/VB/ConfigurationLockCollection.vb" id="Snippet12"::: + ]]> Occurs when an item in the parameter is not a valid lockable configuration attribute. diff --git a/xml/System.Configuration/ConfigurationProperty.xml b/xml/System.Configuration/ConfigurationProperty.xml index 1114016b144..c22a93ce979 100644 --- a/xml/System.Configuration/ConfigurationProperty.xml +++ b/xml/System.Configuration/ConfigurationProperty.xml @@ -416,7 +416,7 @@ property to get the for a specified configuration-property object. + The following code example shows how to use the property to get the for a specified configuration-property object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/CS/ConfigurationProperty.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/VB/ConfigurationProperty.vb" id="Snippet5"::: @@ -468,7 +468,7 @@ object is passed into its constructor. That same object will be returned by the property. + The default value of a new object is passed into its constructor. That same object will be returned by the property. @@ -662,12 +662,12 @@ object to be the key for the containing element when implementing the element. If this flag is not used, the property will return `false`. + You can define a new object to be the key for the containing element when implementing the element. If this flag is not used, the property will return `false`. ## Examples - The following code example shows how to get the property for a specified property. + The following code example shows how to get the property for a specified property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/CS/ConfigurationProperty.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/VB/ConfigurationProperty.vb" id="Snippet7"::: @@ -719,7 +719,7 @@ property value for a specified configuration-property object. + The following code example shows how to get the property value for a specified configuration-property object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/CS/ConfigurationProperty.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/VB/ConfigurationProperty.vb" id="Snippet8"::: @@ -919,7 +919,7 @@ ## Examples - The following example shows how to get the property value for a specified configuration-property object. + The following example shows how to get the property value for a specified configuration-property object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/CS/ConfigurationProperty.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationProperty/VB/ConfigurationProperty.vb" id="Snippet10"::: diff --git a/xml/System.Configuration/ConfigurationPropertyAttribute.xml b/xml/System.Configuration/ConfigurationPropertyAttribute.xml index da764c85b24..f95c3c5e406 100644 --- a/xml/System.Configuration/ConfigurationPropertyAttribute.xml +++ b/xml/System.Configuration/ConfigurationPropertyAttribute.xml @@ -39,59 +39,59 @@ Declaratively instructs .NET to instantiate a configuration property. This class cannot be inherited. - to decorate a configuration property, which will instruct .NET to instantiate and to initialize the property using the value of the decorating parameter. - + to decorate a configuration property, which will instruct .NET to instantiate and to initialize the property using the value of the decorating parameter. + > [!NOTE] -> The simplest way to create a custom configuration element is to use the attributed (declarative) model. You declare the custom public properties and decorate them with the attribute. For each property marked with this attribute, .NET uses reflection to read the decorating parameters and create a related instance. You can also use the programmatic model, in which case it is your responsibility to declare the custom public properties and return their collection. - - The .NET configuration system provides attribute types that you can use during the creation of custom configuration elements. There are two kinds of attribute types: - -1. The types instructing .NET how to instantiate the custom configuration-element properties. These types include: - - - - - - - -2. The types instructing .NET how to validate the custom configuration-element properties. These types include: - - - - - - - - - - - - - - - - - - -## Examples - The following example shows how to define the properties of a custom object using the attribute. - - The example contains two classes. The `UrlsSection` custom class uses the to define its own properties. The `UsingConfigurationPropertyAttribute` class uses the `UrlsSection` to read and write the custom section in the application configuration file. - +> The simplest way to create a custom configuration element is to use the attributed (declarative) model. You declare the custom public properties and decorate them with the attribute. For each property marked with this attribute, .NET uses reflection to read the decorating parameters and create a related instance. You can also use the programmatic model, in which case it is your responsibility to declare the custom public properties and return their collection. + + The .NET configuration system provides attribute types that you can use during the creation of custom configuration elements. There are two kinds of attribute types: + +1. The types instructing .NET how to instantiate the custom configuration-element properties. These types include: + + - + + - + +2. The types instructing .NET how to validate the custom configuration-element properties. These types include: + + - + + - + + - + + - + + - + + + +## Examples + The following example shows how to define the properties of a custom object using the attribute. + + The example contains two classes. The `UrlsSection` custom class uses the to define its own properties. The `UsingConfigurationPropertyAttribute` class uses the `UrlsSection` to read and write the custom section in the application configuration file. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/CS/customsection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/VB/customsection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/VB/customsection.vb" id="Snippet1"::: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/CS/ConfigurationPropertyAttribute.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/VB/ConfigurationPropertyAttribute.vb" id="Snippet21"::: - - The following is an excerpt of the configuration file containing the custom section as defined in the previous sample. - -```xml - - - -
- - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/VB/ConfigurationPropertyAttribute.vb" id="Snippet21"::: + + The following is an excerpt of the configuration file containing the custom section as defined in the previous sample. + +```xml + + + +
+ + + +``` + ]]> @@ -169,14 +169,14 @@ Gets or sets the default value for the decorated property. The object representing the default value of the decorated configuration-element property. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/CS/customsection.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/VB/customsection.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/VB/customsection.vb" id="Snippet3"::: + ]]> @@ -214,11 +214,11 @@ if the property represents the default collection of an element; otherwise, . The default is . - property value is ignored if the decorated property is not a collection. - + property value is ignored if the decorated property is not a collection. + ]]> @@ -256,19 +256,19 @@ if the property is a key property for an element of the collection; otherwise, . The default is . - property applies only if the property you decorate is a collection. It does not have any effect if the property is not a collection. Multiple elements can be marked as . - - - -## Examples - The following example shows how to use the property. - + property applies only if the property you decorate is a collection. It does not have any effect if the property is not a collection. Multiple elements can be marked as . + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/CS/customsection.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/VB/customsection.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/VB/customsection.vb" id="Snippet2"::: + ]]> @@ -306,14 +306,14 @@ if the property is required; otherwise, . The default is . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/CS/customsection.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/VB/customsection.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationPropertyAttribute/VB/customsection.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Configuration/ConfigurationPropertyCollection.xml b/xml/System.Configuration/ConfigurationPropertyCollection.xml index 6d764173288..fbdd2cc0f16 100644 --- a/xml/System.Configuration/ConfigurationPropertyCollection.xml +++ b/xml/System.Configuration/ConfigurationPropertyCollection.xml @@ -40,33 +40,33 @@ Represents a collection of configuration-element properties. - class represents the collection of the objects that can be attributes or objects of a configuration element. - - The class represents an individual configuration setting. It allows you to get or set the name, type, and default value for a particular configuration entity (attribute or element). Additional options allow you to specify whether the attribute is required, is an element key, or represents a default element collection. - - - -## Examples - The following example shows one possible use of the . Refer to the example of the related type . - - - - The following is an excerpt from the configuration used by the above example. - -```xml - - - -
- - - -``` - + class represents the collection of the objects that can be attributes or objects of a configuration element. + + The class represents an individual configuration setting. It allows you to get or set the name, type, and default value for a particular configuration entity (attribute or element). Additional options allow you to specify whether the attribute is required, is an element key, or represents a default element collection. + + + +## Examples + The following example shows one possible use of the . Refer to the example of the related type . + + + + The following is an excerpt from the configuration used by the above example. + +```xml + + + +
+ + + +``` + ]]> @@ -105,18 +105,18 @@ Initializes a new instance of the class. - to create a new collection that will contain the objects as they apply to your configuration element. - - - -## Examples - The following example shows how to use the constructor. - - - + to create a new collection that will contain the objects as they apply to your configuration element. + + + +## Examples + The following example shows how to use the constructor. + + + ]]> @@ -162,18 +162,18 @@ The to add. Adds a configuration property to the collection. - method will add the specified object, if it is not already contained within the collection. - - - -## Examples - The following example shows how to use the method. - - - + method will add the specified object, if it is not already contained within the collection. + + + +## Examples + The following example shows how to use the method. + + + ]]> @@ -216,17 +216,17 @@ Removes all configuration property objects from the collection. - method. - - - - The following example shows how to call the above method and save the changes to the configuration file. - - - + method. + + + + The following example shows how to call the above method and save the changes to the configuration file. + + + ]]> @@ -274,13 +274,13 @@ if the specified is contained in the collection; otherwise, . - method. - - - + method. + + + ]]> @@ -328,13 +328,13 @@ Index at which to begin copying. Copies this ConfigurationPropertyCollection to an array. - method. - - - + method. + + + ]]> @@ -418,17 +418,17 @@ Gets the object as it applies to the collection. The object as it applies to the collection. - method. - - - - The following example shows how to call the above method to enumerate the objects in the collection. - - - + method. + + + + The following example shows how to call the above method to enumerate the objects in the collection. + + + ]]> @@ -475,13 +475,13 @@ if access to the is synchronized; otherwise, . - property value. - - - + property value. + + + ]]> @@ -528,13 +528,13 @@ Gets the collection item with the specified name. The with the specified . - property. - - - + property. + + + ]]> @@ -582,22 +582,22 @@ if the specified was removed; otherwise, . - object was not contained within the collection. - - - -## Examples - The following example shows how to use the method. - - - - The following example shows how to call the above method and save the changes to the configuration file. - - - + object was not contained within the collection. + + + +## Examples + The following example shows how to use the method. + + + + The following example shows how to call the above method and save the changes to the configuration file. + + + ]]> @@ -643,13 +643,13 @@ Gets the object to synchronize access to the collection. The object to synchronize access to the collection. - property value. - - - + property value. + + + ]]> diff --git a/xml/System.Configuration/ConfigurationSection.xml b/xml/System.Configuration/ConfigurationSection.xml index 1edb8a8c06f..61782cc88c8 100644 --- a/xml/System.Configuration/ConfigurationSection.xml +++ b/xml/System.Configuration/ConfigurationSection.xml @@ -371,7 +371,7 @@ Note: If you use a static method that takes a property. + The following example shows how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSection/CS/CustomConfigurationSection.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSection/VB/CustomConfigurationSection.vb" id="Snippet3"::: diff --git a/xml/System.Configuration/ConfigurationSectionCollection.xml b/xml/System.Configuration/ConfigurationSectionCollection.xml index b1b84d3cd2a..c739995099a 100644 --- a/xml/System.Configuration/ConfigurationSectionCollection.xml +++ b/xml/System.Configuration/ConfigurationSectionCollection.xml @@ -40,39 +40,39 @@ Represents a collection of related sections within a configuration file. - class to iterate through a collection of objects. You can access this collection of objects using the property or the property. - - The class is also used in the creation of custom types that extend the class. - - - -## Examples - The following code example shows how to use the class. - + class to iterate through a collection of objects. You can access this collection of objects using the property or the property. + + The class is also used in the creation of custom types that extend the class. + + + +## Examples + The following code example shows how to use the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/CS/ConfigurationSectionCollection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet1"::: - - The following example is an excerpt of the configuration file used by the previous example. - -```xml - - - - -
- - - - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet1"::: + + The following example is an excerpt of the configuration file used by the previous example. + +```xml + + + + +
+ + + + + + +``` + ]]> @@ -117,19 +117,19 @@ The section to be added. Adds a object to the object. - object if it is not already contained within the collection. - - - -## Examples - The following example shows how to use the method. - + object if it is not already contained within the collection. + + + +## Examples + The following example shows how to use the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/CS/ConfigurationSectionCollection.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet10"::: + ]]> @@ -169,14 +169,14 @@ Clears this object. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/CS/ConfigurationSectionCollection.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet3"::: + ]]> @@ -344,14 +344,14 @@ Gets the specified object contained in this object. The object with the specified name. - . - + . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/CS/ConfigurationSectionCollection.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet4"::: + ]]> @@ -409,14 +409,14 @@ Gets an enumerator that can iterate through this object. An that can be used to iterate through this object. - . - + . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/CS/ConfigurationSectionCollection.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet5"::: + ]]> @@ -460,14 +460,14 @@ Gets the key of the specified object contained in this object. The key of the object at the specified index. - . - + . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/CS/ConfigurationSectionCollection.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet6"::: + ]]> @@ -523,11 +523,11 @@ The applicable object. Used by the system during serialization. - method is used during serialization; that is, when persisting configuration data to a configuration file. - + method is used during serialization; that is, when persisting configuration data to a configuration file. + ]]> @@ -577,21 +577,21 @@ Gets the specified object. The object at the specified index. - object. - - In C#, this property is the indexer for the class. - - - -## Examples - The following code example shows how to use . - + object. + + In C#, this property is the indexer for the class. + + + +## Examples + The following code example shows how to use . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/CS/ConfigurationSectionCollection.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet8"::: + ]]> @@ -635,21 +635,21 @@ Gets the specified object. The object with the specified name. - object. - - In C#, this property is the indexer for the class. - - - -## Examples - The following code example shows how to use . - + object. + + In C#, this property is the indexer for the class. + + + +## Examples + The following code example shows how to use . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/CS/ConfigurationSectionCollection.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet8"::: + ]]> @@ -690,14 +690,14 @@ Gets the keys to all objects contained in this object. A object that contains the keys of all sections in this collection. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/CS/ConfigurationSectionCollection.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet7"::: + ]]> @@ -740,14 +740,14 @@ The name of the section to be removed. Removes the specified object from this object. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/CS/ConfigurationSectionCollection.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionCollection/VB/ConfigurationSectionCollection.vb" id="Snippet9"::: + ]]> diff --git a/xml/System.Configuration/ConfigurationSectionGroup.xml b/xml/System.Configuration/ConfigurationSectionGroup.xml index 359c63875cd..ff8a2a5fe03 100644 --- a/xml/System.Configuration/ConfigurationSectionGroup.xml +++ b/xml/System.Configuration/ConfigurationSectionGroup.xml @@ -320,9 +320,9 @@ property returns `true`. + If the section group is declared in the configuration file, the property returns `true`. - The property returns `false` if this section is inherited from Machine.config or a parent configuration file. + The property returns `false` if this section is inherited from Machine.config or a parent configuration file. @@ -374,7 +374,7 @@ property value is the name of the section group that does not contain the parent section groups. + The property value is the name of the section group that does not contain the parent section groups. @@ -426,7 +426,7 @@ property value is the full path name of the section group, including the parent section groups. + The property value is the full path name of the section group, including the parent section groups. @@ -478,7 +478,7 @@ property. This is part of a larger example provided in the overview for the class. + The following code example shows how to access the property. This is part of a larger example provided in the overview for the class. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroup/CS/ConfigurationSectionGroup.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroup/VB/ConfigurationSectionGroup.vb" id="Snippet8"::: @@ -525,7 +525,7 @@ property. This is part of a larger example provided in the overview for the class. + The following code example shows how to access the property. This is part of a larger example provided in the overview for the class. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroup/CS/ConfigurationSectionGroup.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroup/VB/ConfigurationSectionGroup.vb" id="Snippet7"::: @@ -624,12 +624,12 @@ class is a derived type, the property will return the name of the derived type that extends the class. + If this instance of the class is a derived type, the property will return the name of the derived type that extends the class. ## Examples - The following code example shows how to use the property. This is part of a larger example provided in the overview for the class. + The following code example shows how to use the property. This is part of a larger example provided in the overview for the class. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroup/CS/ConfigurationSectionGroup.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroup/VB/ConfigurationSectionGroup.vb" id="Snippet4"::: diff --git a/xml/System.Configuration/ConfigurationSectionGroupCollection.xml b/xml/System.Configuration/ConfigurationSectionGroupCollection.xml index b308982a03f..f1c83af1d44 100644 --- a/xml/System.Configuration/ConfigurationSectionGroupCollection.xml +++ b/xml/System.Configuration/ConfigurationSectionGroupCollection.xml @@ -40,37 +40,37 @@ Represents a collection of objects. - class to iterate through a collection of objects. You can access this collection of objects using the property or the property. - - The class is also used in the creation of custom types that extend the class. - - - -## Examples - The following code example shows how to use the class. - + class to iterate through a collection of objects. You can access this collection of objects using the property or the property. + + The class is also used in the creation of custom types that extend the class. + + + +## Examples + The following code example shows how to use the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/CS/ConfigurationSectionGroupCollection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet1"::: - - The following example is an excerpt of the configuration file used by the previous example. - -```xml - - - -
- /configSections> - - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet1"::: + + The following example is an excerpt of the configuration file used by the previous example. + +```xml + + + +
+ /configSections> + + + + +``` + ]]> @@ -115,11 +115,11 @@ The object to be added. Adds a object to this object. - object if it is not already contained within the collection. - + object if it is not already contained within the collection. + ]]> @@ -156,19 +156,19 @@ Clears the collection. - method. - - - -## Examples - The following code example shows how to use the method. - + method. + + + +## Examples + The following code example shows how to use the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/CS/ConfigurationSectionGroupCollection.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet3"::: + ]]> @@ -261,11 +261,11 @@ Gets a object from the collection. - method. - + method. + ]]> @@ -306,11 +306,11 @@ Gets the specified object contained in the collection. The object at the specified index. - method. - + method. + ]]> @@ -351,19 +351,19 @@ Gets the specified object from the collection. The object with the specified name. - method. - - - -## Examples - The following code example shows how to use the method. - + method. + + + +## Examples + The following code example shows how to use the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/CS/ConfigurationSectionGroupCollection.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet4"::: + ]]> @@ -421,14 +421,14 @@ Gets an enumerator that can iterate through the object. An that can be used to iterate through the object. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/CS/ConfigurationSectionGroupCollection.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet5"::: + ]]> @@ -472,14 +472,14 @@ Gets the key of the specified object contained in this object. The key of the object at the specified index. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/CS/ConfigurationSectionGroupCollection.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet6"::: + ]]> @@ -535,11 +535,11 @@ The applicable object. Used by the system during serialization. - method is used during serialization; that is, when persisting configuration data to a configuration file. - + method is used during serialization; that is, when persisting configuration data to a configuration file. + ]]> @@ -552,14 +552,14 @@ Gets or sets a object contained in this object. - property to iterate through a . - + property to iterate through a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/ConfigurationSectionGroupCollection/CS/sample.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/ConfigurationSectionGroupCollection/VB/sample.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/ConfigurationSectionGroupCollection/VB/sample.vb" id="Snippet9"::: + ]]> @@ -598,8 +598,8 @@ The index of the object to be returned. Gets the object whose index is specified from the collection. - The object at the specified index. - + The object at the specified index. + In C#, this property is the indexer for the class. To be added. @@ -638,18 +638,18 @@ The name of the object to be returned. Gets the object whose name is specified from the collection. - The object with the specified name. - + The object with the specified name. + In C#, this property is the indexer for the class. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/CS/ConfigurationSectionGroupCollection.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet8"::: + ]]> @@ -690,14 +690,14 @@ Gets the keys to all objects contained in this object. A object that contains the names of all section groups in this collection. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/CS/ConfigurationSectionGroupCollection.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet7"::: + ]]> @@ -740,14 +740,14 @@ The name of the section group to be removed. Removes the object whose name is specified from this object. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/CS/ConfigurationSectionGroupCollection.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationSectionGroupCollection/VB/ConfigurationSectionGroupCollection.vb" id="Snippet9"::: + ]]> diff --git a/xml/System.Configuration/ConnectionStringSettings.xml b/xml/System.Configuration/ConnectionStringSettings.xml index 6929fc040cc..1776c9dc814 100644 --- a/xml/System.Configuration/ConnectionStringSettings.xml +++ b/xml/System.Configuration/ConnectionStringSettings.xml @@ -34,19 +34,19 @@ Represents a single, named connection string in the connection strings configuration file section. - object represents a single entry in the `connectionStrings` configuration file section. - - - -## Examples - The following example shows how to access a object at a given index in a collection. - + object represents a single entry in the `connectionStrings` configuration file section. + + + +## Examples + The following example shows how to access a object at a given index in a collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/CS/ConfigurationStringSettings.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConfigurationStringSettings.vb" id="Snippet21"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConfigurationStringSettings.vb" id="Snippet21"::: + ]]> @@ -170,14 +170,14 @@ The name of the provider to use with the connection string. Initializes a new instance of the class. - object and add it to a collection. - + object and add it to a collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/CS/ConnectionStrings.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConnectionStrings.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConnectionStrings.vb" id="Snippet8"::: + ]]> @@ -222,14 +222,14 @@ Gets or sets the connection string. The string value assigned to the property. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/CS/ConnectionStrings.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConnectionStrings.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConnectionStrings.vb" id="Snippet4"::: + ]]> @@ -274,14 +274,14 @@ Gets or sets the name. The string value assigned to the property. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/CS/ConnectionStrings.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConnectionStrings.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConnectionStrings.vb" id="Snippet5"::: + ]]> @@ -363,14 +363,14 @@ Gets or sets the provider name property. The property. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/CS/ConnectionStrings.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConnectionStrings.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConnectionStrings.vb" id="Snippet6"::: + ]]> diff --git a/xml/System.Configuration/ConnectionStringsSection.xml b/xml/System.Configuration/ConnectionStringsSection.xml index f5d1ecdb3de..8394c443706 100644 --- a/xml/System.Configuration/ConnectionStringsSection.xml +++ b/xml/System.Configuration/ConnectionStringsSection.xml @@ -124,7 +124,7 @@ property of the object. + The following example shows how to use the property of the object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/CS/ConnectionStrings.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConnectionStrings/VB/ConnectionStrings.vb" id="Snippet2"::: diff --git a/xml/System.Configuration/ContextInformation.xml b/xml/System.Configuration/ContextInformation.xml index b65fbf75892..2f67816e99c 100644 --- a/xml/System.Configuration/ContextInformation.xml +++ b/xml/System.Configuration/ContextInformation.xml @@ -33,19 +33,19 @@ Encapsulates the context information that is associated with a object. This class cannot be inherited. - object provides environment details related to an element of the configuration. For instance, you can use the property to determine whether a was set in Machine.config, or you can determine which hierarchy a belongs to by using the property. - - - -## Examples - The following code example demonstrates how to use the type. - + object provides environment details related to an element of the configuration. For instance, you can use the property to determine whether a was set in Machine.config, or you can determine which hierarchy a belongs to by using the property. + + + +## Examples + The following code example demonstrates how to use the type. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ContextInformation/CS/ContextInformation.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ContextInformation/VB/ContextInformation.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ContextInformation/VB/ContextInformation.vb" id="Snippet1"::: + ]]> @@ -86,11 +86,11 @@ Provides an object containing configuration-section information based on the specified section name. An object containing the specified section within the configuration. - @@ -128,19 +128,19 @@ Gets the context of the environment where the configuration property is being evaluated. An object specifying the environment where the configuration property is being evaluated. - value is , , or `null`. - - - -## Examples - The following code example demonstrates how to use the property. - + value is , , or `null`. + + + +## Examples + The following code example demonstrates how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ContextInformation/CS/ContextInformation.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ContextInformation/VB/ContextInformation.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ContextInformation/VB/ContextInformation.vb" id="Snippet3"::: + ]]> @@ -180,19 +180,19 @@ if the configuration property is being evaluated at the machine configuration level; otherwise, . - is `false`, use the property to determine the level within the configuration hierarchy. - - - -## Examples - The following code example demonstrates how to use the property. - + is `false`, use the property to determine the level within the configuration hierarchy. + + + +## Examples + The following code example demonstrates how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ContextInformation/CS/ContextInformation.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ContextInformation/VB/ContextInformation.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ContextInformation/VB/ContextInformation.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.Configuration/DefaultSettingValueAttribute.xml b/xml/System.Configuration/DefaultSettingValueAttribute.xml index 7d6a1905278..d3ef490efd8 100644 --- a/xml/System.Configuration/DefaultSettingValueAttribute.xml +++ b/xml/System.Configuration/DefaultSettingValueAttribute.xml @@ -165,7 +165,7 @@ property is set in the constructor. + The property is set in the constructor. Setting providers may support multiple serialization schemes that can be specified with the . diff --git a/xml/System.Configuration/ElementInformation.xml b/xml/System.Configuration/ElementInformation.xml index 3d3dc7477c8..f0d3171a553 100644 --- a/xml/System.Configuration/ElementInformation.xml +++ b/xml/System.Configuration/ElementInformation.xml @@ -33,41 +33,41 @@ Contains meta-information about an individual element within the configuration. This class cannot be inherited. - object contains meta-information about an individual element within the configuration. This object can be used when validating and changing the properties of an individual element. - - - -## Examples - The following example shows how to get the associated with a object. - + object contains meta-information about an individual element within the configuration. This object can be used when validating and changing the properties of an individual element. + + + +## Examples + The following example shows how to get the associated with a object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet80"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet80"::: - - The following excerpt shows the configuration used by the previous code example. - -```xml - - - -
- - - - - - - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet80"::: + + The following excerpt shows the configuration used by the previous code example. + +```xml + + + +
+ + + + + + + + + +``` + ]]> @@ -105,14 +105,14 @@ Gets the errors for the associated element and subelements. The collection containing the errors for the associated element and subelements. - collection. - + collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet89"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet89"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet89"::: + ]]> @@ -150,14 +150,14 @@ if the associated object is a collection; otherwise, . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet81"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet81"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet81"::: + ]]> @@ -195,19 +195,19 @@ if the associated object cannot be modified; otherwise, . - property returns `true` when the related element is locked by the , , or property. - - - -## Examples - The following example shows how to use the property. - + property returns `true` when the related element is locked by the , , or property. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet82"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet82"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet82"::: + ]]> @@ -245,14 +245,14 @@ if the associated object is in the configuration file; otherwise, . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet83"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet83"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet83"::: + ]]> @@ -289,14 +289,14 @@ Gets the line number in the configuration file where the associated object is defined. The line number in the configuration file where the associated object is defined. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet84"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet84"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet84"::: + ]]> @@ -333,19 +333,19 @@ Gets a collection of the properties in the associated object. A collection of the properties in the associated object. - object are the attributes and subelements associated with that configuration element in the configuration file. - - - -## Examples - The following example shows how to get the collection. - + object are the attributes and subelements associated with that configuration element in the configuration file. + + + +## Examples + The following example shows how to get the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet85"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet85"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet85"::: + ]]> @@ -382,19 +382,19 @@ Gets the source file where the associated object originated. The source file where the associated object originated. - object may be created in a default state, in which case this property returns `null`. - - - -## Examples - The following example shows how to use the property. - + object may be created in a default state, in which case this property returns `null`. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet86"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet86"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet86"::: + ]]> @@ -431,14 +431,14 @@ Gets the type of the associated object. The type of the associated object. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet87"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet87"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet87"::: + ]]> @@ -475,19 +475,19 @@ Gets the object used to validate the associated object. The object used to validate the associated object. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ElementInformation.cs" id="Snippet88"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet88"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ElementInformation.vb" id="Snippet88"::: + ]]> diff --git a/xml/System.Configuration/IPersistComponentSettings.xml b/xml/System.Configuration/IPersistComponentSettings.xml index 2f5dcca1c4a..a8397ef37c0 100644 --- a/xml/System.Configuration/IPersistComponentSettings.xml +++ b/xml/System.Configuration/IPersistComponentSettings.xml @@ -81,7 +81,7 @@ - It causes each application settings instance contained by the control to refresh the values of its application settings properties, typically by calling their methods. -- As required, it updates those general properties that depend on these reloaded settings properties. For example, if the settings class contained a `location` settings property, should ensure that the control's property is updated to reflect this reloaded setting. +- As required, it updates those general properties that depend on these reloaded settings properties. For example, if the settings class contained a `location` settings property, should ensure that the control's property is updated to reflect this reloaded setting. ]]> @@ -171,7 +171,7 @@ The method writes the values of the control's application settings properties to the associated data store. The data store and serialization technique the method uses is determined by the settings provider associated with each settings class through the . You can override the choice of the settings provider by using the interface. > [!NOTE] -> If the property is `true`, the control should call in its own method so that the control's configuration data is stored automatically before the application ends. +> If the property is `true`, the control should call in its own method so that the control's configuration data is stored automatically before the application ends. ]]> @@ -220,14 +220,14 @@ method or sometimes implicitly when the control's method is invoked. The property determines whether a control automatically persists its configuration data when it is disposed. + If a control contains configuration data, it will typically persist this data in response to an explicit call to the method or sometimes implicitly when the control's method is invoked. The property determines whether a control automatically persists its configuration data when it is disposed. - The default value of depends on the implementation of the control. The documentation for the control should indicate whether it uses application settings, what data is persisted, and what the default value of the property is. + The default value of depends on the implementation of the control. The documentation for the control should indicate whether it uses application settings, what data is persisted, and what the default value of the property is. ## Examples - The following code example shows the proper way for a control to check the value of the property before it attempts to automatically persist its configuration data. + The following code example shows the proper way for a control to check the value of the property before it attempts to automatically persist its configuration data. `protected override void Dispose( bool disposing ) {` @@ -292,17 +292,17 @@ property to disambiguate groups of application settings properties when there are multiple instances of the same wrapper class. For example, if a control contains an associated wrapper class, then placing multiple instances of the same control in the same application will typically result in multiple instances of the wrapper class. A settings key is required only when the configuration data differs on a per-instance basis; for example, the location of dynamically positioned controls. + Use the property to disambiguate groups of application settings properties when there are multiple instances of the same wrapper class. For example, if a control contains an associated wrapper class, then placing multiple instances of the same control in the same application will typically result in multiple instances of the wrapper class. A settings key is required only when the configuration data differs on a per-instance basis; for example, the location of dynamically positioned controls. The following general rules apply to the use of : -- A control, like any class, may contain zero or more application settings classes, derived from . Each settings class contains its own property, which helps disambiguate multiple instances of that class. +- A control, like any class, may contain zero or more application settings classes, derived from . Each settings class contains its own property, which helps disambiguate multiple instances of that class. - A control should separate its per-instance data and its shared data into different settings classes. -- For a control with any per-instance configuration data, the `get` accessor of the property should default to the of the control. In most cases the name of the control will be unique within an application. If the control contains only shared configuration data, `get` should default to `null`. +- For a control with any per-instance configuration data, the `get` accessor of the property should default to the of the control. In most cases the name of the control will be unique within an application. If the control contains only shared configuration data, `get` should default to `null`. -- The `set` accessor for this property should be implemented to distinguish between settings classes containing per-instance and shared configuration data. For each settings class containing per-instance data, `set` should just pass-through to the property of the settings class. For settings classes containing shared data, `set` should perform no action for that settings class. +- The `set` accessor for this property should be implemented to distinguish between settings classes containing per-instance and shared configuration data. For each settings class containing per-instance data, `set` should just pass-through to the property of the settings class. For settings classes containing shared data, `set` should perform no action for that settings class. ]]> diff --git a/xml/System.Configuration/IntegerValidatorAttribute.xml b/xml/System.Configuration/IntegerValidatorAttribute.xml index 3fb5ad19e02..7129e4c63a8 100644 --- a/xml/System.Configuration/IntegerValidatorAttribute.xml +++ b/xml/System.Configuration/IntegerValidatorAttribute.xml @@ -39,19 +39,19 @@ Declaratively instructs .NET to perform integer validation on a configuration property. This class cannot be inherited. - attribute to decorate a configuration property, which will instruct .NET to validate the property using the object and pass to it the value of the decorating parameters. - + attribute to decorate a configuration property, which will instruct .NET to validate the property using the object and pass to it the value of the decorating parameters. + You can apply attributes to property types only. - -## Examples - The following example shows how to decorate the properties of a custom object using the attribute. - + +## Examples + The following example shows how to decorate the properties of a custom object using the attribute. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet6"::: + ]]> @@ -88,19 +88,19 @@ Creates a new instance of the class. - constructor. - + constructor. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet5"::: + ]]> @@ -138,19 +138,19 @@ if the value must be excluded; otherwise, . The default is . - and property values. When the property value is `true`, the allowed values are outside the range. - - - -## Examples - The following example shows how to use the property. - + and property values. When the property value is `true`, the allowed values are outside the range. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet6"::: + ]]> @@ -187,19 +187,19 @@ Gets or sets the maximum value allowed for the property. An integer that indicates the allowed maximum value. - property value is included in the allowed range. - - - -## Examples - The following example shows how to use the property. - + property value is included in the allowed range. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet6"::: + ]]> The selected value is less than . @@ -237,19 +237,19 @@ Gets or sets the minimum value allowed for the property. An integer that indicates the allowed minimum value. - property value is included in the allowed range. - - - -## Examples - The following example shows how to use the property. - + property value is included in the allowed range. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet6"::: + ]]> The selected value is greater than . @@ -287,19 +287,19 @@ Gets an instance of the class. The validator instance. - property to perform string validation by calling its method. - - - -## Examples - The following example shows how to use the property. - + property to perform string validation by calling its method. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet13"::: + ]]> diff --git a/xml/System.Configuration/KeyValueConfigurationCollection.xml b/xml/System.Configuration/KeyValueConfigurationCollection.xml index 455557489b9..3a39b83ed48 100644 --- a/xml/System.Configuration/KeyValueConfigurationCollection.xml +++ b/xml/System.Configuration/KeyValueConfigurationCollection.xml @@ -40,19 +40,19 @@ Contains a collection of objects. - type. - + type. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/CS/KeyValueConfigurationCollection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet1"::: + ]]> @@ -85,14 +85,14 @@ Initializes a new instance of the class. - constructor. This code example is part of a larger example provided for the class overview. - + constructor. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/CS/KeyValueConfigurationCollection.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet4"::: + ]]> @@ -141,19 +141,19 @@ A . Adds a object to the collection based on the supplied parameters. - method to add a new object to the collection. - - - -## Examples - The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class overview. - + method to add a new object to the collection. + + + +## Examples + The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/CS/KeyValueConfigurationCollection.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet6"::: + ]]> @@ -263,11 +263,11 @@ Clears the collection. - method is called, it removes all objects from the collection. - + method is called, it removes all objects from the collection. + ]]> @@ -305,11 +305,11 @@ When overridden in a derived class, the method creates a new object. A newly created . - method to create custom objects. When a collection is loaded from the configuration file, the method is called to create individual elements. The method must be overridden in classes that derive from the class. - + method to create custom objects. When a collection is loaded from the configuration file, the method is called to create individual elements. The method must be overridden in classes that derive from the class. + ]]> @@ -388,11 +388,11 @@ Gets the object based on the supplied parameter. A configuration element, or if the key does not exist in the collection. - property to get a object in the collection based on the `key` parameter. - + property to get a object in the collection based on the `key` parameter. + ]]> diff --git a/xml/System.Configuration/KeyValueConfigurationElement.xml b/xml/System.Configuration/KeyValueConfigurationElement.xml index c370844f737..7c1d80d4fc8 100644 --- a/xml/System.Configuration/KeyValueConfigurationElement.xml +++ b/xml/System.Configuration/KeyValueConfigurationElement.xml @@ -34,19 +34,19 @@ Represents a configuration element that contains a key/value pair. - object inherits from the base class. The object represents an element within a configuration file. The object can belong in a collection. - - - -## Examples - The following code example demonstrates how to use members of the class. - + object inherits from the base class. The object represents an element within a configuration file. The object can belong in a collection. + + + +## Examples + The following code example demonstrates how to use members of the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/CS/KeyValueConfigurationCollection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet1"::: + ]]> @@ -86,14 +86,14 @@ The value of the . Initializes a new instance of the class based on the supplied parameters. - constructor. This code example is part of a larger example provided for the class overview. - + constructor. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/CS/KeyValueConfigurationCollection.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet2"::: + ]]> @@ -175,14 +175,14 @@ Gets the key of the object. The key of the . - property. This code example is part of a larger example provided for the class overview. - + property. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/CS/KeyValueConfigurationCollection.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet5"::: + ]]> @@ -263,14 +263,14 @@ Gets or sets the value of the object. The value of the . - property. This code example is part of a larger example provided for the class overview. - + property. This code example is part of a larger example provided for the class overview. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/CS/KeyValueConfigurationCollection.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.KeyValueConfigurationCollection/VB/KeyValueConfigurationCollection.vb" id="Snippet5"::: + ]]> diff --git a/xml/System.Configuration/LocalFileSettingsProvider.xml b/xml/System.Configuration/LocalFileSettingsProvider.xml index 98210a94089..722e9e99ba4 100644 --- a/xml/System.Configuration/LocalFileSettingsProvider.xml +++ b/xml/System.Configuration/LocalFileSettingsProvider.xml @@ -92,7 +92,7 @@ property to . + The parameterless constructor sets the property to . ]]> diff --git a/xml/System.Configuration/LongValidatorAttribute.xml b/xml/System.Configuration/LongValidatorAttribute.xml index 8b22c2bec67..d2ff50c9d27 100644 --- a/xml/System.Configuration/LongValidatorAttribute.xml +++ b/xml/System.Configuration/LongValidatorAttribute.xml @@ -39,19 +39,19 @@ Declaratively instructs .NET to perform long-integer validation on a configuration property. This class cannot be inherited. - attribute to decorate a configuration property. This is to instruct .NET to validate the property using a object and pass to it the value of the decorating parameters. - + attribute to decorate a configuration property. This is to instruct .NET to validate the property using a object and pass to it the value of the decorating parameters. + You can apply the attribute to property types only. - -## Examples - The following example shows how to decorate the properties of a custom object using the attribute. - + +## Examples + The following example shows how to decorate the properties of a custom object using the attribute. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet7"::: + ]]> @@ -88,11 +88,11 @@ Initializes a new instance of the class. - @@ -130,19 +130,19 @@ if the value must be excluded; otherwise, . The default is . - and property values. When the property value is `false`, the allowed values are outside the range. - - - -## Examples - The following example shows how to use the property. - + and property values. When the property value is `false`, the allowed values are outside the range. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet7"::: + ]]> @@ -179,19 +179,19 @@ Gets or sets the maximum value allowed for the property. A long integer that indicates the allowed maximum value. - property value is included in the allowed range. - - - -## Examples - The following example shows how to use the property. - + property value is included in the allowed range. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet7"::: + ]]> The selected value is less than . @@ -229,19 +229,19 @@ Gets or sets the minimum value allowed for the property. An integer that indicates the allowed minimum value. - property value is included in the allowed range. - - - -## Examples - The following example shows how to use the property. - + property value is included in the allowed range. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet7"::: + ]]> The selected value is greater than . @@ -279,11 +279,11 @@ Gets an instance of the class. The validator instance. - property value to perform string validation by calling its method. - + property value to perform string validation by calling its method. + ]]> diff --git a/xml/System.Configuration/NameValueConfigurationCollection.xml b/xml/System.Configuration/NameValueConfigurationCollection.xml index e370e3c56ab..10a11ba9f08 100644 --- a/xml/System.Configuration/NameValueConfigurationCollection.xml +++ b/xml/System.Configuration/NameValueConfigurationCollection.xml @@ -40,19 +40,19 @@ Contains a collection of objects. This class cannot be inherited. - class allows you to programmatically access a collection of objects. - - - -## Examples - The following code example demonstrates how to use the type. - + class allows you to programmatically access a collection of objects. + + + +## Examples + The following code example demonstrates how to use the type. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/CS/NameValueConfigurationCollection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet1"::: + ]]> @@ -86,14 +86,14 @@ Initializes a new instance of the class. - constructor. This code example is part of a larger example provided for the class. - + constructor. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/CS/NameValueConfigurationCollection.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet2"::: + ]]> @@ -133,19 +133,19 @@ A object. Adds a object to the collection. - method to add a new object to the collection. - - - -## Examples - The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class. - + method to add a new object to the collection. + + + +## Examples + The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/CS/NameValueConfigurationCollection.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet3"::: + ]]> @@ -216,19 +216,19 @@ Clears the . - method is called, it removes all objects from the collection. - - - -## Examples - The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class. - + method is called, it removes all objects from the collection. + + + +## Examples + The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/CS/NameValueConfigurationCollection.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet7"::: + ]]> @@ -342,19 +342,19 @@ Gets or sets the object based on the supplied parameter. A object. - property to get or set a object based on the `name` parameter. - - - -## Examples - The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class. - + property to get or set a object based on the `name` parameter. + + + +## Examples + The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/CS/NameValueConfigurationCollection.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet5"::: + ]]> @@ -440,19 +440,19 @@ A object. Removes a object from the collection based on the provided parameter. - method to remove a from the collection. Override in a derived class if custom behavior is required when the element is removed. - - - -## Examples - The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class. - + method to remove a from the collection. Override in a derived class if custom behavior is required when the element is removed. + + + +## Examples + The following code example demonstrates how to use the method. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/CS/NameValueConfigurationCollection.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.NameValueConfigurationCollection/VB/NameValueConfigurationCollection.vb" id="Snippet6"::: + ]]> @@ -492,11 +492,11 @@ The name of the object. Removes a object from the collection based on the provided parameter. - method to remove a from the collection. Override in a derived class if custom behavior is required when the element is removed. - + method to remove a from the collection. Override in a derived class if custom behavior is required when the element is removed. + ]]> diff --git a/xml/System.Configuration/OverrideMode.xml b/xml/System.Configuration/OverrideMode.xml index 86f75fe3309..c8226bccc48 100644 --- a/xml/System.Configuration/OverrideMode.xml +++ b/xml/System.Configuration/OverrideMode.xml @@ -32,11 +32,11 @@ Specifies the override behavior of a configuration element for configuration elements in child directories. - enumeration values to set the property of the class. You set this property in order to programmatically specify override behavior of a configuration element or group. To declaratively set the override behavior for all configuration elements inside a `location` element, use the `allowOverride` attribute. The property gives you more granular control over the elements inside a `location` element. - + enumeration values to set the property of the class. You set this property in order to programmatically specify override behavior of a configuration element or group. To declaratively set the override behavior for all configuration elements inside a `location` element, use the `allowOverride` attribute. The property gives you more granular control over the elements inside a `location` element. + ]]> diff --git a/xml/System.Configuration/PositiveTimeSpanValidatorAttribute.xml b/xml/System.Configuration/PositiveTimeSpanValidatorAttribute.xml index f19eb625c39..e6c12a30c77 100644 --- a/xml/System.Configuration/PositiveTimeSpanValidatorAttribute.xml +++ b/xml/System.Configuration/PositiveTimeSpanValidatorAttribute.xml @@ -39,13 +39,13 @@ Declaratively instructs .NET to perform time validation on a configuration property. This class cannot be inherited. - attribute to decorate a configuration property. This instructs .NET to validate the property using a object and pass the value of the decorating parameters. - - You can apply objects only to property types. - + attribute to decorate a configuration property. This instructs .NET to validate the property using a object and pass the value of the decorating parameters. + + You can apply objects only to property types. + ]]> @@ -82,11 +82,11 @@ Initializes a new instance of the class. - object. - + object. + ]]> @@ -123,11 +123,11 @@ Gets an instance of the class. The validator instance. - property to perform positive object validation by calling the method. - + property to perform positive object validation by calling the method. + ]]> diff --git a/xml/System.Configuration/PropertyInformation.xml b/xml/System.Configuration/PropertyInformation.xml index c830f0b8afa..b98594c27bb 100644 --- a/xml/System.Configuration/PropertyInformation.xml +++ b/xml/System.Configuration/PropertyInformation.xml @@ -33,21 +33,21 @@ Contains meta-information on an individual property within the configuration. This type cannot be inherited. - object contains the meta-information of an individual property within the configuration. This object can be used when validating and changing the properties of an individual attribute. - - The object is derived from the associated object. The object is derived from the associated object. - - - -## Examples - The following code example demonstrates how to use the type. - + object contains the meta-information of an individual property within the configuration. This object can be used when validating and changing the properties of an individual attribute. + + The object is derived from the associated object. The object is derived from the associated object. + + + +## Examples + The following code example demonstrates how to use the type. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet1"::: + ]]> @@ -87,11 +87,11 @@ Gets the object related to the configuration attribute. A object. - object is used to guide how the value of an attribute can be modified. - + object is used to guide how the value of an attribute can be modified. + ]]> @@ -128,14 +128,14 @@ Gets an object containing the default value related to a configuration attribute. An object containing the default value of the configuration attribute. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet2"::: + ]]> @@ -207,14 +207,14 @@ if the configuration attribute is a key; otherwise, . - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet3"::: + ]]> @@ -252,19 +252,19 @@ if the object is locked; otherwise, . - property returns `true` when the related element is locked by the or property. - - - -## Examples - The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class. - + property returns `true` when the related element is locked by the or property. + + + +## Examples + The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet4"::: + ]]> @@ -302,14 +302,14 @@ if the object has been modified; otherwise, . - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet5"::: + ]]> @@ -347,14 +347,14 @@ if the object is required; otherwise, . - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet6"::: + ]]> @@ -391,19 +391,19 @@ Gets the line number in the configuration file related to the configuration attribute. A line number of the configuration file. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet7"::: + ]]> @@ -440,14 +440,14 @@ Gets the name of the object that corresponds to a configuration attribute. The name of the object. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet8"::: + ]]> @@ -484,14 +484,14 @@ Gets the source file that corresponds to a configuration attribute. The source file of the object. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet9"::: + ]]> @@ -528,14 +528,14 @@ Gets the of the object that corresponds to a configuration attribute. The of the object. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet10"::: + ]]> @@ -572,19 +572,19 @@ Gets a object related to the configuration attribute. A object. - object to validate the value configuration attribute. - - - -## Examples - The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class. - + object to validate the value configuration attribute. + + + +## Examples + The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet11"::: + ]]> @@ -621,14 +621,14 @@ Gets or sets an object containing the value related to a configuration attribute. An object containing the value for the object. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet12"::: + ]]> @@ -665,19 +665,19 @@ Gets a object related to the configuration attribute. A object. - object describes how the value of the configuration attribute was determined. - - - -## Examples - The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class. - + object describes how the value of the configuration attribute was determined. + + + +## Examples + The following code example demonstrates how to use the property. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.PropertyInformation/CS/PropertyInformation.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.PropertyInformation/VB/PropertyInformation.vb" id="Snippet13"::: + ]]> diff --git a/xml/System.Configuration/ProtectedConfiguration.xml b/xml/System.Configuration/ProtectedConfiguration.xml index a350cb93511..d758ae2c21d 100644 --- a/xml/System.Configuration/ProtectedConfiguration.xml +++ b/xml/System.Configuration/ProtectedConfiguration.xml @@ -234,7 +234,7 @@ property to retrieve the collection of installed objects. + The following example shows how to use the property to retrieve the collection of installed objects. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ProtectedConfiguration/CS/ProtectedConfiguration.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProtectedConfiguration/VB/ProtectedConfiguration.vb" id="Snippet3"::: diff --git a/xml/System.Configuration/ProtectedConfigurationProviderCollection.xml b/xml/System.Configuration/ProtectedConfigurationProviderCollection.xml index 7a9620fa8d7..2f7dd6c49f1 100644 --- a/xml/System.Configuration/ProtectedConfigurationProviderCollection.xml +++ b/xml/System.Configuration/ProtectedConfigurationProviderCollection.xml @@ -36,7 +36,7 @@ property of the class is a collection of all protected-configuration providers available to your application. + The property of the class is a collection of all protected-configuration providers available to your application. You can encrypt sections of a configuration file to protect sensitive information used by your application. This improves security by making unauthorized access difficult, even if an attacker gains access to your configuration file. @@ -84,7 +84,7 @@ constructor is not intended to be used directly from your code. It is called by the ASP.NET configuration system. You obtain an instance of the class by using the property of the class. + The constructor is not intended to be used directly from your code. It is called by the ASP.NET configuration system. You obtain an instance of the class by using the property of the class. ]]> diff --git a/xml/System.Configuration/ProtectedConfigurationSection.xml b/xml/System.Configuration/ProtectedConfigurationSection.xml index d9dee11b1d1..8adc6a39dbc 100644 --- a/xml/System.Configuration/ProtectedConfigurationSection.xml +++ b/xml/System.Configuration/ProtectedConfigurationSection.xml @@ -153,7 +153,7 @@ property. + The following code example shows how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ProtectedConfigurationSection/CS/ProtectedConfigurationSection.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProtectedConfigurationSection/VB/ProtectedConfigurationSection.vb" id="Snippet2"::: @@ -240,7 +240,7 @@ property. + The following code example shows how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ProtectedConfigurationSection/CS/ProtectedConfigurationSection.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProtectedConfigurationSection/VB/ProtectedConfigurationSection.vb" id="Snippet3"::: diff --git a/xml/System.Configuration/ProtectedProviderSettings.xml b/xml/System.Configuration/ProtectedProviderSettings.xml index 2fa2b06630f..d3836eb39c7 100644 --- a/xml/System.Configuration/ProtectedProviderSettings.xml +++ b/xml/System.Configuration/ProtectedProviderSettings.xml @@ -105,7 +105,7 @@ property to access the properties of the providers for protected configuration data. + Use the property to access the properties of the providers for protected configuration data. ]]> @@ -152,7 +152,7 @@ property. + Use this property to access the properties of the providers for protected configuration data instead of the property. ]]> diff --git a/xml/System.Configuration/ProviderSettings.xml b/xml/System.Configuration/ProviderSettings.xml index 4543a3fe3c5..95a4000e09d 100644 --- a/xml/System.Configuration/ProviderSettings.xml +++ b/xml/System.Configuration/ProviderSettings.xml @@ -33,45 +33,45 @@ Represents the configuration elements associated with a provider. - class represents a particular group of settings that are added to the `providers` element within a configuration section. Typically the configuration attributes specified by the `add` directive include a name, type, and other properties. - - - -## Examples - The following code example shows how to use the . - + class represents a particular group of settings that are added to the `providers` element within a configuration section. Typically the configuration attributes specified by the `add` directive include a name, type, and other properties. + + + +## Examples + The following code example shows how to use the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ProviderSettings/CS/ProviderSettings.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProviderSettings/VB/ProviderSettings.vb" id="Snippet1"::: - - The following is an excerpt of the configuration file used by the above example. - -```xml - - - - - - - - - - - - - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProviderSettings/VB/ProviderSettings.vb" id="Snippet1"::: + + The following is an excerpt of the configuration file used by the above example. + +```xml + + + + + + + + + + + + + + +``` + ]]> @@ -85,11 +85,11 @@ PublicKeyToken=79e01ae0f5cfc66f, processorArchitecture=MSIL" /> Initializes a new instance of the class. - instance. - + instance. + ]]> @@ -122,13 +122,13 @@ PublicKeyToken=79e01ae0f5cfc66f, processorArchitecture=MSIL" /> Initializes a new instance of the class. - class. - - Use this constructor to create a new instance. - + class. + + Use this constructor to create a new instance. + ]]> @@ -167,11 +167,11 @@ PublicKeyToken=79e01ae0f5cfc66f, processorArchitecture=MSIL" /> The type of the provider to configure settings for. Initializes a new instance of the class. - instance with the specified name and type. - + instance with the specified name and type. + ]]> @@ -253,19 +253,19 @@ PublicKeyToken=79e01ae0f5cfc66f, processorArchitecture=MSIL" /> Gets or sets the name of the provider configured by this class. The name of the provider. - property is the same as the value for the `name` attribute that appears in the configuration section for the provider that is configured by the class. - - - -## Examples - The following code example shows how to access the property. - + property is the same as the value for the `name` attribute that appears in the configuration section for the provider that is configured by the class. + + + +## Examples + The following code example shows how to access the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ProviderSettings/CS/ProviderSettings.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProviderSettings/VB/ProviderSettings.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProviderSettings/VB/ProviderSettings.vb" id="Snippet2"::: + ]]> @@ -342,19 +342,19 @@ PublicKeyToken=79e01ae0f5cfc66f, processorArchitecture=MSIL" /> Gets a collection of user-defined parameters for the provider. A of parameters for the provider. - property to access the parameters for this object. - - - -## Examples - The following code example shows how to access the property. - + property to access the parameters for this object. + + + +## Examples + The following code example shows how to access the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ProviderSettings/CS/ProviderSettings.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProviderSettings/VB/ProviderSettings.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProviderSettings/VB/ProviderSettings.vb" id="Snippet4"::: + ]]> @@ -475,19 +475,19 @@ PublicKeyToken=79e01ae0f5cfc66f, processorArchitecture=MSIL" /> Gets or sets the type of the provider configured by this class. The fully qualified namespace and class name for the type of provider configured by this instance. - property contains the fully qualified namespace and class name for the provider configured by the class. - - - -## Examples - The following code example shows how to access the property. - + property contains the fully qualified namespace and class name for the provider configured by the class. + + + +## Examples + The following code example shows how to access the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ProviderSettings/CS/ProviderSettings.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProviderSettings/VB/ProviderSettings.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProviderSettings/VB/ProviderSettings.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Configuration/ProviderSettingsCollection.xml b/xml/System.Configuration/ProviderSettingsCollection.xml index 6826ead22a7..d73daddd868 100644 --- a/xml/System.Configuration/ProviderSettingsCollection.xml +++ b/xml/System.Configuration/ProviderSettingsCollection.xml @@ -40,19 +40,19 @@ Represents a collection of objects. - class represents the `providers` element within a configuration file. - - - -## Examples - The following code example shows how to iterate through the property, which returns a . - + class represents the `providers` element within a configuration file. + + + +## Examples + The following code example shows how to iterate through the property, which returns a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ProviderSettings/CS/ProviderSettings.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProviderSettings/VB/ProviderSettings.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ProviderSettings/VB/ProviderSettings.vb" id="Snippet1"::: + ]]> @@ -123,11 +123,11 @@ The object to add. Adds a object to the collection. - method to add a object to the collection. - + method to add a object to the collection. + ]]> @@ -164,11 +164,11 @@ Clears the collection. - method to remove all objects from the collection. - + method to remove all objects from the collection. + ]]> @@ -254,11 +254,11 @@ Accesses an instance of the class. - object contained within this class. - + object contained within this class. + ]]> @@ -299,11 +299,11 @@ Gets or sets a value at the specified index in the collection. The specified . - property to get or set a specified object contained within this class. - + property to get or set a specified object contained within this class. + ]]> @@ -418,11 +418,11 @@ The name of the object to remove. Removes an element from the collection. - method to remove a specified object from the collection. - + method to remove a specified object from the collection. + ]]> diff --git a/xml/System.Configuration/RegexStringValidatorAttribute.xml b/xml/System.Configuration/RegexStringValidatorAttribute.xml index 0e0914c8659..a2a74be1b71 100644 --- a/xml/System.Configuration/RegexStringValidatorAttribute.xml +++ b/xml/System.Configuration/RegexStringValidatorAttribute.xml @@ -149,7 +149,7 @@ The following example shows how to use the property. +The following example shows how to use the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet16"::: @@ -194,7 +194,7 @@ The following example shows how to use the property to perform string validation by calling its method. +You use the property to perform string validation by calling its method. ## Examples diff --git a/xml/System.Configuration/SchemeSettingElement.xml b/xml/System.Configuration/SchemeSettingElement.xml index 42b2f37d7cd..67ceda446df 100644 --- a/xml/System.Configuration/SchemeSettingElement.xml +++ b/xml/System.Configuration/SchemeSettingElement.xml @@ -33,13 +33,13 @@ Represents an element in a class. - class represents the \ element under the Uri section within a configuration file. The class represents an instance of an element in the class. - - The class and the \ section in a configuration file looks generic, implying that an application can specify any enumeration value for any scheme. In fact, only the flag for HTTP and HTTPS schemes are supported. All other settings are ignored. - + class represents the \ element under the Uri section within a configuration file. The class represents an instance of an element in the class. + + The class and the \ section in a configuration file looks generic, implying that an application can specify any enumeration value for any scheme. In fact, only the flag for HTTP and HTTPS schemes are supported. All other settings are ignored. + ]]> @@ -127,11 +127,11 @@ Gets the value of the GenericUriParserOptions entry from a instance. The value of GenericUriParserOptions entry. - property returns a enumeration value for the instance. - + property returns a enumeration value for the instance. + ]]> @@ -179,13 +179,13 @@ Gets the value of the Name entry from a instance. The protocol used by this schema setting. - property returns a enumeration value for the instance. - - The element is currently restricted to HTTP and HTTPS. - + property returns a enumeration value for the instance. + + The element is currently restricted to HTTP and HTTPS. + ]]> diff --git a/xml/System.Configuration/SchemeSettingElementCollection.xml b/xml/System.Configuration/SchemeSettingElementCollection.xml index e1b50ac1ade..889219d90ea 100644 --- a/xml/System.Configuration/SchemeSettingElementCollection.xml +++ b/xml/System.Configuration/SchemeSettingElementCollection.xml @@ -42,27 +42,27 @@ Represents a collection of objects. - class represents the \ element under the Uri section within a configuration file. - - The class and the \ section in a configuration file looks generic, implying that an application can specify any enumeration value for any scheme. In fact, only the flag for HTTP and HTTPS schemes are supported. All other settings are ignored. - - By default, the class un-escapes percent encoded path delimiters before executing path compression. This was implemented as a security mechanism against attacks like the following: - - `http://www.contoso.com/..%2F..%2F/Windows/System32/cmd.exe?/c+dir+c:\` - - If this URI gets passed down to modules not handling percent encoded characters correctly, it could result in the following command being executed by the server: - - `c:\Windows\System32\cmd.exe /c dir c:\` - - For this reason, class first un-escapes path delimiters and then applies path compression. The result of passing the malicious URL above to class constructor results in the following URI: - - `http://www.microsoft.com/Windows/System32/cmd.exe?/c+dir+c:\` - - This default behavior can be modified to not un-escape percent encoded path delimiters using the class. - + class represents the \ element under the Uri section within a configuration file. + + The class and the \ section in a configuration file looks generic, implying that an application can specify any enumeration value for any scheme. In fact, only the flag for HTTP and HTTPS schemes are supported. All other settings are ignored. + + By default, the class un-escapes percent encoded path delimiters before executing path compression. This was implemented as a security mechanism against attacks like the following: + + `http://www.contoso.com/..%2F..%2F/Windows/System32/cmd.exe?/c+dir+c:\` + + If this URI gets passed down to modules not handling percent encoded characters correctly, it could result in the following command being executed by the server: + + `c:\Windows\System32\cmd.exe /c dir c:\` + + For this reason, class first un-escapes path delimiters and then applies path compression. The result of passing the malicious URL above to class constructor results in the following URI: + + `http://www.microsoft.com/Windows/System32/cmd.exe?/c+dir+c:\` + + This default behavior can be modified to not un-escape percent encoded path delimiters using the class. + ]]> @@ -136,11 +136,11 @@ Gets the default collection type of . The default collection type of . - @@ -306,17 +306,17 @@ Gets an item at the specified index in the collection. The specified . - property to get or set a specified object contained within this class. - + property to get or set a specified object contained within this class. + ]]> - The parameter is less than zero. - - -or- - + The parameter is less than zero. + + -or- + The item specified by the parameter is or has been removed. @@ -358,11 +358,11 @@ Gets an item from the collection. A object contained in the collection. - diff --git a/xml/System.Configuration/SectionInformation.xml b/xml/System.Configuration/SectionInformation.xml index aa74568f455..e5d11868b24 100644 --- a/xml/System.Configuration/SectionInformation.xml +++ b/xml/System.Configuration/SectionInformation.xml @@ -111,7 +111,7 @@ ## Examples - The examples in this section show how to get the property value after accessing the related section information in the configuration file. + The examples in this section show how to get the property value after accessing the related section information in the configuration file. The following example gets the object. @@ -169,7 +169,7 @@ ## Examples - The examples in this section show how to get the property value after accessing the related section information in the configuration file. + The examples in this section show how to get the property value after accessing the related section information in the configuration file. The following example gets the object. @@ -223,12 +223,12 @@ property indicates that the section is accessed by native-code readers. Therefore, the use of the `location` attribute is not allowed, because the native-code readers do not support the concept of `location`. + When set to `false`, the property indicates that the section is accessed by native-code readers. Therefore, the use of the `location` attribute is not allowed, because the native-code readers do not support the concept of `location`. ## Examples - The examples in this section show how to get the property value after accessing the related section information in the configuration file. + The examples in this section show how to get the property value after accessing the related section information in the configuration file. The following example gets the object. @@ -281,7 +281,7 @@ property value after accessing the related section information in the configuration file. + The examples in this section show how to get the property value after accessing the related section information in the configuration file. The following example gets the object. @@ -332,7 +332,7 @@ property represents the value of the `configSource` attribute that is specified for a object that is associated with the object. + The property represents the value of the `configSource` attribute that is specified for a object that is associated with the object. A implementation can optionally specify a separate file in which the configuration settings for that section are defined. This can be useful in multiple ways: @@ -346,9 +346,9 @@ `` - If any of the settings in a configuration include file require the application to restart when they are modified, set the property to `true`. + If any of the settings in a configuration include file require the application to restart when they are modified, set the property to `true`. - In ASP.NET applications, at run time you can assign to the property the name of an alternative configuration file. In that case, the contents of the file are overwritten by the default connection string information that is contained in the Web.config file. This occurs also when the alternative file does not exist and it is created at run time. If the Web.config file does not contain any connection string information, an empty section is added to the alternative file. + In ASP.NET applications, at run time you can assign to the property the name of an alternative configuration file. In that case, the contents of the file are overwritten by the default connection string information that is contained in the Web.config file. This occurs also when the alternative file does not exist and it is created at run time. If the Web.config file does not contain any connection string information, an empty section is added to the alternative file. ]]> @@ -538,7 +538,7 @@ Note: If the configuration file is saved (even if there are no modifications), A property of a object. + The following example shows how to use the property of a object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/ConfigurationElement.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/ConfigurationElement.vb" id="Snippet1"::: @@ -583,7 +583,7 @@ Note: If the configuration file is saved (even if there are no modifications), A object has no parent sections, the method returns the same value as the property. + If this object has no parent sections, the method returns the same value as the property. @@ -739,7 +739,7 @@ The following example shows how to get the property value after accessing the related section information in the configuration file. + The examples in this section show how to get the property value after accessing the related section information in the configuration file. The following example gets the object. @@ -792,7 +792,7 @@ The following example shows how to get the property value after accessing the related section information in the configuration file. + The examples in this section show how to get the property value after accessing the related section information in the configuration file. The following example gets the object. @@ -844,12 +844,12 @@ The following example shows how to get the property returns `true` when the related section is locked by the or the property. A section is locked if it cannot be overridden or defined in the current configuration file. + The property returns `true` when the related section is locked by the or the property. A section is locked if it cannot be overridden or defined in the current configuration file. ## Examples - The examples in this section show how to get the property value after accessing the related section information in the configuration file. + The examples in this section show how to get the property value after accessing the related section information in the configuration file. The following example gets the object. @@ -908,7 +908,7 @@ The following example shows how to get the property value after accessing the related section information in the configuration file. + The examples in this section show how to get the property value after accessing the related section information in the configuration file. The following example gets the object. @@ -1009,9 +1009,9 @@ The following example shows how to get the property gets or sets a value that indicates whether resources declared inside a `location` element can be overridden by child configuration files. The property gets or sets a value that specifies similar behavior, but does so for a specific configuration element or group, and uses one of the enumeration values. The property enables behavior to be inherited from a parent element. + The property gets or sets a value that indicates whether resources declared inside a `location` element can be overridden by child configuration files. The property gets or sets a value that specifies similar behavior, but does so for a specific configuration element or group, and uses one of the enumeration values. The property enables behavior to be inherited from a parent element. - You cannot programmatically set both the and property. Setting the property to `true` sets the property to . Setting the property to `false` sets the property to `false`. + You cannot programmatically set both the and property. Setting the property to `true` sets the property to . Setting the property to `false` sets the property to `false`. ]]> @@ -1054,7 +1054,7 @@ The following example shows how to get the property of a configuration section can only be set to the or value of the enumeration. Setting the property to is equivalent to setting the value to . + The property of a configuration section can only be set to the or value of the enumeration. Setting the property to is equivalent to setting the value to . ]]> @@ -1138,7 +1138,7 @@ The following example shows how to get the property is `null`. + For unprotected sections, the property is `null`. For more information about protected configuration sections, see [Encrypting Configuration Information Using Protected Configuration](https://learn.microsoft.com/previous-versions/aspnet/53tyfkaw(v=vs.100)). @@ -1275,7 +1275,7 @@ The following example shows how to get the property of the `appSettings` section is `true`. + The following example shows two possible trust levels for a Web application when the property of the `appSettings` section is `true`. ```xml @@ -1351,12 +1351,12 @@ Dim apSection As AppSettingsSection = _ property to `false` to prevent an application restart when configuration settings in the external include file are modified for this object. + Set the property to `false` to prevent an application restart when configuration settings in the external include file are modified for this object. ## Examples - The following example shows how to get the property value of a object. + The following example shows how to get the property value of a object. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/CS/SectionInforrmation.cs" id="Snippet109"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationElement/VB/SectionInforrmation.vb" id="Snippet109"::: @@ -1436,7 +1436,7 @@ Dim apSection As AppSettingsSection = _ property value is the complete section name, which includes the configuration inheritance hierarchy. + The property value is the complete section name, which includes the configuration inheritance hierarchy. @@ -1524,7 +1524,7 @@ Dim apSection As AppSettingsSection = _ property returns the name of the section class that handles this instance of the class. + The property returns the name of the section class that handles this instance of the class. diff --git a/xml/System.Configuration/SettingChangingEventArgs.xml b/xml/System.Configuration/SettingChangingEventArgs.xml index abb79853687..a80b6481867 100644 --- a/xml/System.Configuration/SettingChangingEventArgs.xml +++ b/xml/System.Configuration/SettingChangingEventArgs.xml @@ -33,13 +33,13 @@ Provides data for the event. - class provides data for the event, which signals that the value of an application settings property is about to change. The most common source for this event is the `get` accessor of the method in the class. - - Because is derived from , the handler has the option of canceling the write operation. - + class provides data for the event, which signals that the value of an application settings property is about to change. The most common source for this event is the `get` accessor of the method in the class. + + Because is derived from , the handler has the option of canceling the write operation. + ]]> @@ -93,11 +93,11 @@ to cancel the event; otherwise, . Initializes an instance of the class. - constructor just assigns the values of the parameters to the corresponding properties in the class. - + constructor just assigns the values of the parameters to the corresponding properties in the class. + ]]> @@ -145,11 +145,11 @@ Gets the new value being assigned to the application settings property. An that contains the new value to be assigned to the application settings property. - property should be compatible with the settings property being set. The latter is available though the property of the class. - + property should be compatible with the settings property being set. The latter is available though the property of the class. + ]]> @@ -194,11 +194,11 @@ Gets the application settings property category. A containing a category description of the setting. Typically, this parameter is set to the application settings group name. - ; otherwise, one is generated using the name of the settings wrapper class. - + ; otherwise, one is generated using the name of the settings wrapper class. + ]]> @@ -242,11 +242,11 @@ Gets the application settings key associated with the property. A containing the application settings key. - , has an associated settings key, which is a string that helps disambiguate different instances of the same wrapper in a single application. Because each wrapper class defines a set of properties that represent application settings, the settings key can similarly help disambiguate their use. - + , has an associated settings key, which is a string that helps disambiguate different instances of the same wrapper in a single application. Because each wrapper class defines a set of properties that represent application settings, the settings key can similarly help disambiguate their use. + ]]> @@ -291,11 +291,11 @@ Gets the name of the application setting associated with the application settings property. A containing the name of the application setting. - , will be constructed so that the name of the application settings property will be the same as its associated application setting. - + , will be constructed so that the name of the application settings property will be the same as its associated application setting. + ]]> diff --git a/xml/System.Configuration/SettingsBase.xml b/xml/System.Configuration/SettingsBase.xml index 868ce708dd8..20a87d49944 100644 --- a/xml/System.Configuration/SettingsBase.xml +++ b/xml/System.Configuration/SettingsBase.xml @@ -33,15 +33,15 @@ Provides the base class used to support user property settings. - base class, the class, the class, the class, the class, and the - - class. - - The Settings base classes provide only a common infrastructure for defining and persisting settings properties. Depending on how these base classes are derived and their run-time environment, the settings API can provide different levels of functionality. For example, ASP.NET Profile uses the settings base classes to provide per-user settings that are saved and loaded according to request semantics. - + base class, the class, the class, the class, the class, and the + + class. + + The Settings base classes provide only a common infrastructure for defining and persisting settings properties. Depending on how these base classes are derived and their run-time environment, the settings API can provide different levels of functionality. For example, ASP.NET Profile uses the settings base classes to provide per-user settings that are saved and loaded according to request semantics. + ]]> @@ -119,13 +119,13 @@ Gets the associated settings context. A associated with the settings instance. - is used by the application to provide contextual information that the provider can use to persist settings. - - Each settings class derived from has a context associated with it. The context is passed to the settings provider to identity additional information about the settings information. Context therefore acts as a hint to help the settings provider determine how to persist the associated settings values. - + is used by the application to provide contextual information that the provider can use to persist settings. + + Each settings class derived from has a context associated with it. The context is passed to the settings provider to identity additional information about the settings information. Context therefore acts as a hint to help the settings provider determine how to persist the associated settings values. + ]]> @@ -252,15 +252,15 @@ Gets or sets the value of the specified settings property. If found, the value of the named settings property. - property, also known as the indexer, is routinely used in the settings class derived from . The property binds the public property of the class to the corresponding settings property. - - The first time a property is accessed, the instance will find all other properties that share the same provider as the requested property. The instance will then call the provider, passing it the set of objects that represent the data the provider should retrieve. - - Note that the indexer will get and set property data in a thread-safe manner if is `true`. A instance by default is not thread safe. However, you can call , passing in a instance to make the indexer operate in a thread-safe manner. - + property, also known as the indexer, is routinely used in the settings class derived from . The property binds the public property of the class to the corresponding settings property. + + The first time a property is accessed, the instance will find all other properties that share the same provider as the requested property. The instance will then call the provider, passing it the set of objects that represent the data the provider should retrieve. + + Note that the indexer will get and set property data in a thread-safe manner if is `true`. A instance by default is not thread safe. However, you can call , passing in a instance to make the indexer operate in a thread-safe manner. + ]]> There are no properties associated with the current object, or the specified property could not be found. @@ -307,13 +307,13 @@ Gets the collection of settings properties. A collection containing all the objects. - property returns the collection of instances associated with the properties managed by the instance. - - The class natively recognizes certain characteristics of a setting, such as its name, property type, settings provider, default value, and read-only status and a serialization preference. These characteristics are mirrored as properties in the class. All other attributes of the class are just passed through to its associated settings provider as a . - + property returns the collection of instances associated with the properties managed by the instance. + + The class natively recognizes certain characteristics of a setting, such as its name, property type, settings provider, default value, and read-only status and a serialization preference. These characteristics are mirrored as properties in the class. All other attributes of the class are just passed through to its associated settings provider as a . + ]]> @@ -432,11 +432,11 @@ Stores the current values of the settings properties. - instance groups properties based on the provider that is associated with each property. Each provider is then called in sequence and is passed the set of properties that the provider should save. - + instance groups properties based on the provider that is associated with each property. Each provider is then called in sequence and is passed the set of properties that the provider should save. + ]]> @@ -477,11 +477,11 @@ Provides a class that is synchronized (thread safe). A class that is synchronized. - property is set to `true`. A instance by default is not thread-safe. However, you can call passing in a instance to make the indexer operate in a thread-safe manner. - + property is set to `true`. A instance by default is not thread-safe. However, you can call passing in a instance to make the indexer operate in a thread-safe manner. + ]]> diff --git a/xml/System.Configuration/SettingsDescriptionAttribute.xml b/xml/System.Configuration/SettingsDescriptionAttribute.xml index 50da2cba4be..eea8f87a3fa 100644 --- a/xml/System.Configuration/SettingsDescriptionAttribute.xml +++ b/xml/System.Configuration/SettingsDescriptionAttribute.xml @@ -144,7 +144,7 @@ property is set by the constructor. + The property is set by the constructor. ]]> diff --git a/xml/System.Configuration/SettingsGroupDescriptionAttribute.xml b/xml/System.Configuration/SettingsGroupDescriptionAttribute.xml index be00e9f38de..7c867de9aa1 100644 --- a/xml/System.Configuration/SettingsGroupDescriptionAttribute.xml +++ b/xml/System.Configuration/SettingsGroupDescriptionAttribute.xml @@ -39,14 +39,14 @@ Provides a string that describes an application settings property group. This class cannot be inherited. - , defines one or more properties that belong to the same application property group. is an optional attribute that you can use to provide descriptive text for a settings property group. This text is intended to assist both design-time tools and administrative run-time tools in identifying and describing the associated property group. - + , defines one or more properties that belong to the same application property group. is an optional attribute that you can use to provide descriptive text for a settings property group. This text is intended to assist both design-time tools and administrative run-time tools in identifying and describing the associated property group. + > [!NOTE] -> This attribute can only be applied at the wrapper class level. - +> This attribute can only be applied at the wrapper class level. + ]]> @@ -91,11 +91,11 @@ A containing the descriptive text for the application settings group. Initializes a new instance of the class. - , practical limits, determined by usability and quota limitations imposed by the settings provider, will be much smaller. - + , practical limits, determined by usability and quota limitations imposed by the settings provider, will be much smaller. + ]]> @@ -139,11 +139,11 @@ The descriptive text for the application settings properties group. A containing the descriptive text for the application settings group. - property value is set in the constructor. - + property value is set in the constructor. + ]]> diff --git a/xml/System.Configuration/SettingsGroupNameAttribute.xml b/xml/System.Configuration/SettingsGroupNameAttribute.xml index 1964fb1599f..6d7a1224491 100644 --- a/xml/System.Configuration/SettingsGroupNameAttribute.xml +++ b/xml/System.Configuration/SettingsGroupNameAttribute.xml @@ -39,13 +39,13 @@ Specifies a name for application settings property group. This class cannot be inherited. - , defines one or more properties that belong to the same application settings property group. By default, the group is assigned the name of the settings class. However, can be used to explicitly specify a name for the property group. This name can be helpful in organizing large sets of properties, for assistance in design-time programming tools and run-time administrative tools, and so on. The associated settings provider may even use this name to organize settings in the data store. - - The can only be applied at the class level. - + , defines one or more properties that belong to the same application settings property group. By default, the group is assigned the name of the settings class. However, can be used to explicitly specify a name for the property group. This name can be helpful in organizing large sets of properties, for assistance in design-time programming tools and run-time administrative tools, and so on. The associated settings provider may even use this name to organize settings in the data store. + + The can only be applied at the class level. + ]]> @@ -91,14 +91,14 @@ A containing the name of the application settings property group. Initializes a new instance of the class. - , practical limits, determined by usability and quota limitations imposed by the settings provider, will be much smaller. - + , practical limits, determined by usability and quota limitations imposed by the settings provider, will be much smaller. + > [!NOTE] -> The settings group name does not need to be unique. - +> The settings group name does not need to be unique. + ]]> @@ -142,11 +142,11 @@ Gets the name of the application settings property group. A containing the name of the application settings property group. - property value is set by the constructor. - + property value is set by the constructor. + ]]> diff --git a/xml/System.Configuration/SettingsPropertyValue.xml b/xml/System.Configuration/SettingsPropertyValue.xml index 831f57d8a88..48c40aa8f1b 100644 --- a/xml/System.Configuration/SettingsPropertyValue.xml +++ b/xml/System.Configuration/SettingsPropertyValue.xml @@ -33,11 +33,11 @@ Contains the value of a settings property that can be loaded and stored by an instance of . - instance describes a value stored within an instance of a object. - + instance describes a value stored within an instance of a object. + ]]> @@ -74,14 +74,14 @@ Specifies a object. Initializes a new instance of the class, based on supplied parameters. - object describes information about the value stored by the object. - + + The object describes information about the value stored by the object. + ]]> @@ -129,11 +129,11 @@ if the value of a object has been deserialized; otherwise, . - How to: Deserialize an Object @@ -182,15 +182,15 @@ if the value of a object has changed; otherwise, . - property indicates that the value stored by this class has changed. The default is `false`. The property is set to `true` under the following conditions: - -1. The value contained in the object is changed. - -2. The value contained in the object is accessed, and the value is not a string or a primitive type such as `int`, `float`, `real`, or `DateTime`. When the value managed by a object is a complex type (for example an ), there is no way for a object to detect when changes have been made. As a result, the object pessimistically assumes that a complex type is dirty once it has been accessed from the property. - + property indicates that the value stored by this class has changed. The default is `false`. The property is set to `true` under the following conditions: + +1. The value contained in the object is changed. + +2. The value contained in the object is accessed, and the value is not a string or a primitive type such as `int`, `float`, `real`, or `DateTime`. When the value managed by a object is a complex type (for example an ), there is no way for a object to detect when changes have been made. As a result, the object pessimistically assumes that a complex type is dirty once it has been accessed from the property. + ]]> @@ -299,12 +299,12 @@ Gets or sets the value of the object. - The value of the object. When this value is set, the property is set to and is set to . - - When a value is first accessed from the property, and if the value was initially stored into the object as a serialized representation using the property, the property will trigger deserialization of the underlying value. As a side effect, the property will be set to . - - If this chain of events occurs in ASP.NET, and if an error occurs during the deserialization process, the error is logged using the health-monitoring feature of ASP.NET. By default, this means that deserialization errors will show up in the Application Event Log when running under ASP.NET. If this process occurs outside of ASP.NET, and if an error occurs during deserialization, the error is suppressed, and the remainder of the logic during deserialization occurs. If there is no serialized value to deserialize when the deserialization is attempted, then object will instead attempt to return a default value if one was configured as defined on the associated instance. In this case, if the property was set to either , or to the string "[null]", then the object will initialize the property to either for reference types, or to the default value for the associated value type. On the other hand, if property holds a valid object reference or string value (other than "[null]"), then the property is returned instead. - + The value of the object. When this value is set, the property is set to and is set to . + + When a value is first accessed from the property, and if the value was initially stored into the object as a serialized representation using the property, the property will trigger deserialization of the underlying value. As a side effect, the property will be set to . + + If this chain of events occurs in ASP.NET, and if an error occurs during the deserialization process, the error is logged using the health-monitoring feature of ASP.NET. By default, this means that deserialization errors will show up in the Application Event Log when running under ASP.NET. If this process occurs outside of ASP.NET, and if an error occurs during deserialization, the error is suppressed, and the remainder of the logic during deserialization occurs. If there is no serialized value to deserialize when the deserialization is attempted, then object will instead attempt to return a default value if one was configured as defined on the associated instance. In this case, if the property was set to either , or to the string "[null]", then the object will initialize the property to either for reference types, or to the default value for the associated value type. On the other hand, if property holds a valid object reference or string value (other than "[null]"), then the property is returned instead. + If there is no serialized value to deserialize when the deserialization is attempted, and no default value was specified, then an empty string will be returned for string types. For all other types, a default instance will be returned by calling - for reference types this means an attempt will be made to create an object instance using the parameterless constructor. If this attempt fails, then is returned. To be added. While attempting to use the default value from the property, an error occurred. Either the attempt to convert property to a valid type failed, or the resulting value was not compatible with the type defined by . @@ -342,14 +342,14 @@ Gets or sets the serialized value of the object. The serialized value of a object. - instance detects that the property has changed since the last time the property was called, it will cause property to be converted to its serialized representation. The specific serialization mechanism to be used is defined by the property on the instance associated with the instance. The current supported serialization options are to convert the object to a string using a string type converter, serialize using the , or perform binary serialization. - + instance detects that the property has changed since the last time the property was called, it will cause property to be converted to its serialized representation. The specific serialization mechanism to be used is defined by the property on the instance associated with the instance. The current supported serialization options are to convert the object to a string using a string type converter, serialize using the , or perform binary serialization. + > [!NOTE] > The underlying serializers may throw exceptions during the serialization process. - + ]]> The serialization options for the property indicated the use of a string type converter, but a type converter was not available. diff --git a/xml/System.Configuration/SettingsProviderAttribute.xml b/xml/System.Configuration/SettingsProviderAttribute.xml index 83b7d9a1f8c..ee57ebf7562 100644 --- a/xml/System.Configuration/SettingsProviderAttribute.xml +++ b/xml/System.Configuration/SettingsProviderAttribute.xml @@ -185,7 +185,7 @@ property is set in the for the class. + The property is set in the for the class. ]]> diff --git a/xml/System.Configuration/SettingsProviderCollection.xml b/xml/System.Configuration/SettingsProviderCollection.xml index de20e7ca6fe..1848462313f 100644 --- a/xml/System.Configuration/SettingsProviderCollection.xml +++ b/xml/System.Configuration/SettingsProviderCollection.xml @@ -33,13 +33,13 @@ Represents a collection of application settings providers. - class is a straightforward extension of the class to provide for storage of objects. - - The class uses this collection to manage the settings providers associated with each of its application settings properties through the . - + class is a straightforward extension of the class to provide for storage of objects. + + The class uses this collection to manage the settings providers associated with each of its application settings properties through the . + ]]> @@ -82,11 +82,11 @@ Initializes a new instance of the class. - @@ -128,24 +128,24 @@ A to add to the collection. Adds a new settings provider to the collection. - property of the is used as the storage key. - + property of the is used as the storage key. + > [!CAUTION] -> Although the method has a single parameter to match the signature of this same method in the base class , this method will throw an exception if the `provider` parameter is not of type . - +> Although the method has a single parameter to match the signature of this same method in the base class , this method will throw an exception if the `provider` parameter is not of type . + ]]> - The parameter is not of type . - - -or- - - The property of the provider parameter is null or an empty string. - - -or- - + The parameter is not of type . + + -or- + + The property of the provider parameter is null or an empty string. + + -or- + A settings provider with the same already exists in the collection. The collection is read-only. The parameter is . @@ -190,11 +190,11 @@ Gets the settings provider in the collection that matches the specified name. If found, the whose name matches that specified by the name parameter; otherwise, . - read-only by using the method. However, it is invalid to methods such as , , and on such a collection. - + read-only by using the method. However, it is invalid to methods such as , , and on such a collection. + ]]> The parameter is . diff --git a/xml/System.Configuration/SpecialSettingAttribute.xml b/xml/System.Configuration/SpecialSettingAttribute.xml index f007a8fc2e4..2b3fe73e9bf 100644 --- a/xml/System.Configuration/SpecialSettingAttribute.xml +++ b/xml/System.Configuration/SpecialSettingAttribute.xml @@ -39,15 +39,15 @@ Indicates that an application settings property has a special significance. This class cannot be inherited. - is used to identify such properties. This class uses the enumeration to indicate what special category the property belongs to. - - can only be applied to the settings class or to the individual settings property. - - For an example of how a settings provider deals with the , see the method of the class. - + is used to identify such properties. This class uses the enumeration to indicate what special category the property belongs to. + + can only be applied to the settings class or to the individual settings property. + + For an example of how a settings provider deals with the , see the method of the class. + ]]> @@ -134,11 +134,11 @@ Gets the value describing the special setting category of the application settings property. A enumeration value defining the category of the application settings property. - property is set in the constructor of this class. - + property is set in the constructor of this class. + ]]> diff --git a/xml/System.Configuration/StringValidatorAttribute.xml b/xml/System.Configuration/StringValidatorAttribute.xml index 08bc56f0c23..7962063d74c 100644 --- a/xml/System.Configuration/StringValidatorAttribute.xml +++ b/xml/System.Configuration/StringValidatorAttribute.xml @@ -39,19 +39,19 @@ Declaratively instructs .NET to perform string validation on a configuration property. This class cannot be inherited. - to decorate a configuration property. This is to instruct .NET to validate the property using the and pass to it the value of the decorating parameters. - + to decorate a configuration property. This is to instruct .NET to validate the property using the and pass to it the value of the decorating parameters. + You can apply objects to property types only. - -## Examples - The following example shows how to decorate the properties of a custom object using the object. - + +## Examples + The following example shows how to decorate the properties of a custom object using the object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet2"::: + ]]> @@ -87,19 +87,19 @@ Initializes a new instance of the class. - constructor. - + constructor. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet3"::: + ]]> @@ -137,14 +137,14 @@ Gets or sets the invalid characters for the property. The string that contains the set of characters that are not allowed for the property. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet2"::: + ]]> @@ -181,14 +181,14 @@ Gets or sets the maximum length allowed for the string to assign to the property. An integer that indicates the maximum allowed length for the string to assign to the property. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet2"::: + ]]> The selected value is less than . @@ -226,14 +226,14 @@ Gets or sets the minimum allowed value for the string to assign to the property. An integer that indicates the allowed minimum length for the string to assign to the property. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet2"::: + ]]> The selected value is greater than . @@ -271,19 +271,19 @@ Gets an instance of the class. A current settings in a validator instance. - property to perform string validation by calling its method. - - - -## Examples - The following example shows how to use the property. - + property to perform string validation by calling its method. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet14"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet14"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet14"::: + ]]> diff --git a/xml/System.Configuration/TimeSpanValidatorAttribute.xml b/xml/System.Configuration/TimeSpanValidatorAttribute.xml index fef5d9c6f6f..84c9621a153 100644 --- a/xml/System.Configuration/TimeSpanValidatorAttribute.xml +++ b/xml/System.Configuration/TimeSpanValidatorAttribute.xml @@ -39,32 +39,32 @@ Declaratively instructs .NET to perform time validation on a configuration property. This class cannot be inherited. - attribute to decorate a configuration property. This is to instruct .NET to validate the property using the class and pass to it the value of the decorating parameters. - - You can apply objects to property types only. - - - -## Examples - The following example shows how to decorate the properties of a custom object using the attribute. - + attribute to decorate a configuration property. This is to instruct .NET to validate the property using the class and pass to it the value of the decorating parameters. + + You can apply objects to property types only. + + + +## Examples + The following example shows how to decorate the properties of a custom object using the attribute. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet8"::: - - The following example is an excerpt of the configuration file that contains the custom section used by the previous sample. - -```xml - - -
- - - -``` - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet8"::: + + The following example is an excerpt of the configuration file that contains the custom section used by the previous sample. + +```xml + + +
+ + + +``` + ]]> @@ -101,19 +101,19 @@ Initializes a new instance of the class. - object. - - - -## Examples - The following example shows how to use the constructor. - + object. + + + +## Examples + The following example shows how to use the constructor. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet12"::: + ]]> @@ -151,19 +151,19 @@ if the value must be excluded; otherwise, . The default is . - and properties. When the property is `false`, the allowed values are outside the range. - - - -## Examples - The following example shows how to use the property. - + and properties. When the property is `false`, the allowed values are outside the range. + + + +## Examples + The following example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet8"::: + ]]> @@ -200,11 +200,11 @@ Gets the absolute maximum value. The allowed maximum value. - field. - + field. + ]]> @@ -241,19 +241,19 @@ Gets or sets the relative maximum value. The allowed maximum value. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet8"::: + ]]> The selected value represents less than . @@ -291,11 +291,11 @@ Gets the absolute minimum value. The allowed minimum value. - field. - + field. + ]]> @@ -332,19 +332,19 @@ Gets or sets the relative minimum value. The minimum allowed value. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet8"::: + ]]> The selected value represents more than . @@ -381,19 +381,19 @@ Gets the absolute maximum value allowed. - field. - + field. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet10"::: + ]]> @@ -429,19 +429,19 @@ Gets the absolute minimum value allowed. - field. - + field. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/CS/ConfigurationValidatorAttributes.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/System.Configuration.ConfigurationValidatorAttributes/VB/ConfigurationValidatorAttributes.vb" id="Snippet11"::: + ]]> @@ -478,11 +478,11 @@ Gets an instance of the class. The validator instance. - property to perform string validation by calling its method. - + property to perform string validation by calling its method. + ]]> diff --git a/xml/System.Configuration/UriSection.xml b/xml/System.Configuration/UriSection.xml index dfcd3a80ad1..d34988aecb8 100644 --- a/xml/System.Configuration/UriSection.xml +++ b/xml/System.Configuration/UriSection.xml @@ -136,7 +136,7 @@ ## Remarks The existing class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Users upgrading from .NET Framework 2.0 won't see any change in behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. - The configuration settings for IRI and IDN can be retrieved using the class. The property returns the configuration setting for IDN processing in the class. + The configuration settings for IRI and IDN can be retrieved using the class. The property returns the configuration setting for IDN processing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. @@ -197,7 +197,7 @@ ## Remarks The existing class has been extended to provide support for International Resource Identifiers (IRI) and Internationalized Domain Names. Users upgrading from .NET Framework 2.0 won't see any change in behavior unless they specifically enable IRI and IDN. This ensures application compatibility with prior versions of the .NET Framework. - The configuration settings for IRI and IDN can be retrieved using the class. The property returns the configuration setting for IRI parsing in the class. + The configuration settings for IRI and IDN can be retrieved using the class. The property returns the configuration setting for IRI parsing in the class. IRI processing must be enabled for IDN processing to be possible. If IRI processing is disabled, then IDN processing will be set to the default setting where the .NET Framework 2.0 behavior is used for compatibility and IDN names are not used. @@ -298,7 +298,7 @@ property is not generic. Only the genericUriParserOptions="DontUnescapePathDotsAndSlashes" configuration setting for HTTP and HTTPS schemes are supported. All other settings are ignored. + The property is not generic. Only the genericUriParserOptions="DontUnescapePathDotsAndSlashes" configuration setting for HTTP and HTTPS schemes are supported. All other settings are ignored. ]]> diff --git a/xml/System.Data.Common.CommandTrees/DbAggregate.xml b/xml/System.Data.Common.CommandTrees/DbAggregate.xml index 659c8cf7084..ffb93f9fb53 100644 --- a/xml/System.Data.Common.CommandTrees/DbAggregate.xml +++ b/xml/System.Data.Common.CommandTrees/DbAggregate.xml @@ -17,11 +17,11 @@ Implements the basic functionality required by aggregates in a clause. - @@ -52,11 +52,11 @@ Gets the list of expressions that define the arguments to this . The list of expressions that define the arguments to this . - property of describes the arguments to the aggregate. - + property of describes the arguments to the aggregate. + ]]> @@ -87,11 +87,11 @@ Gets the result type of this . The result type of this . - property describes the result type of the aggregate. - + property describes the result type of the aggregate. + ]]> diff --git a/xml/System.Data.Common.CommandTrees/DbBinaryExpression.xml b/xml/System.Data.Common.CommandTrees/DbBinaryExpression.xml index b03b3f10633..0c3d5d83c90 100644 --- a/xml/System.Data.Common.CommandTrees/DbBinaryExpression.xml +++ b/xml/System.Data.Common.CommandTrees/DbBinaryExpression.xml @@ -45,16 +45,16 @@ Gets or sets the that defines the left argument. The that defines the left argument. - property is set. For example, requires that its left expression has a collection result type, while requires a Boolean result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. - + property is set. For example, requires that its left expression has a collection result type, while requires a Boolean result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. + ]]> The expression is . - The expression is not associated with the command tree of the , - + The expression is not associated with the command tree of the , + or its result type is not equal or promotable to the required type for the left argument. @@ -84,16 +84,16 @@ Gets or sets the that defines the right argument. The that defines the right argument. - property is set. For example, requires that its right expression has a collection result type, while requires a Boolean result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. - + property is set. For example, requires that its right expression has a collection result type, while requires a Boolean result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. + ]]> The expression is . - The expression is not associated with the command tree of the , - + The expression is not associated with the command tree of the , + or its result type is not equal or promotable to the required type for the right argument. diff --git a/xml/System.Data.Common.CommandTrees/DbFunctionAggregate.xml b/xml/System.Data.Common.CommandTrees/DbFunctionAggregate.xml index 1003675901f..7ff21929782 100644 --- a/xml/System.Data.Common.CommandTrees/DbFunctionAggregate.xml +++ b/xml/System.Data.Common.CommandTrees/DbFunctionAggregate.xml @@ -17,13 +17,13 @@ Supports standard aggregate functions, such as MIN, MAX, AVG, SUM, and so on. This class cannot be inherited. - @@ -55,11 +55,11 @@ if the aggregate is a distinct aggregate; otherwise, . - property of the indicates whether the aggregate is distinct. Therefore, duplicates in the input arguments must be eliminated before the aggregate is computed. - + property of the indicates whether the aggregate is distinct. Therefore, duplicates in the input arguments must be eliminated before the aggregate is computed. + ]]> diff --git a/xml/System.Data.Common.CommandTrees/DbInsertCommandTree.xml b/xml/System.Data.Common.CommandTrees/DbInsertCommandTree.xml index 140b777f8be..29d9278cb07 100644 --- a/xml/System.Data.Common.CommandTrees/DbInsertCommandTree.xml +++ b/xml/System.Data.Common.CommandTrees/DbInsertCommandTree.xml @@ -17,11 +17,11 @@ Represents a single row insert operation expressed as a command tree. This class cannot be inherited. - property is set, the command returns a reader; otherwise, it returns a scalar value indicating the number of rows affected. - + property is set, the command returns a reader; otherwise, it returns a scalar value indicating the number of rows affected. + ]]> diff --git a/xml/System.Data.Common.CommandTrees/DbLimitExpression.xml b/xml/System.Data.Common.CommandTrees/DbLimitExpression.xml index f1491b067b8..fe441ea52a0 100644 --- a/xml/System.Data.Common.CommandTrees/DbLimitExpression.xml +++ b/xml/System.Data.Common.CommandTrees/DbLimitExpression.xml @@ -17,11 +17,11 @@ Represents the restriction of the number of elements in the argument collection to the specified limit value. - can be applied to any with a collection result type, including . provides the equivalent of the Top operation. It does not require an ordering operation to have been performed on its input. It has two `Expression` properties, and , that specify the collection and the number of rows to return respectively. also has a `Boolean` property that controls whether rows equal in rank to the final row are returned. defaults to `false`. - + can be applied to any with a collection result type, including . provides the equivalent of the Top operation. It does not require an ordering operation to have been performed on its input. It has two `Expression` properties, and , that specify the collection and the number of rows to return respectively. also has a `Boolean` property that controls whether rows equal in rank to the final row are returned. defaults to `false`. + ]]> @@ -172,11 +172,11 @@ if the limit operation will include tied results; otherwise, . The default is . - property controls whether rows equal in rank to the final row are returned. - + property controls whether rows equal in rank to the final row are returned. + ]]> diff --git a/xml/System.Data.Common.CommandTrees/DbQueryCommandTree.xml b/xml/System.Data.Common.CommandTrees/DbQueryCommandTree.xml index e2ba97738e9..2d34366a114 100644 --- a/xml/System.Data.Common.CommandTrees/DbQueryCommandTree.xml +++ b/xml/System.Data.Common.CommandTrees/DbQueryCommandTree.xml @@ -17,11 +17,11 @@ Represents a query operation expressed as a command tree. This class cannot be inherited. - describes a query. - + describes a query. + ]]> @@ -52,11 +52,11 @@ Gets an that defines the logic of the query operation. An that defines the logic of the query operation. - property describes the root of the expression tree that defines the query. The is in an invalid state until the property is set to a valid value. - + property describes the root of the expression tree that defines the query. The is in an invalid state until the property is set to a valid value. + ]]> The expression is . diff --git a/xml/System.Data.Common.CommandTrees/DbSkipExpression.xml b/xml/System.Data.Common.CommandTrees/DbSkipExpression.xml index 6220050a7e1..e180e086a6e 100644 --- a/xml/System.Data.Common.CommandTrees/DbSkipExpression.xml +++ b/xml/System.Data.Common.CommandTrees/DbSkipExpression.xml @@ -17,11 +17,11 @@ Skips a specified number of elements in the input set. can only be used after the input collection has been sorted as specified by the sort keys. - requires its input collection to have already been sorted. The sort order is represented as the property. is a list of objects. - + requires its input collection to have already been sorted. The sort order is represented as the property. is a list of objects. + ]]> @@ -112,8 +112,8 @@ An expression that specifies the number of elements to skip from the input collection. To be added. The expression is . - The expression is not associated with the command tree of the ; the expression is not either a or a ; - + The expression is not associated with the command tree of the ; the expression is not either a or a ; + or the result type of the expression is not equal or promotable to a 64-bit integer type. @@ -171,11 +171,11 @@ Gets a list that defines the sort order. A list that defines the sort order. - requires its input collection to have already been sorted. The sort order is represented as the property. is a list of objects. - + requires its input collection to have already been sorted. The sort order is represented as the property. is a list of objects. + ]]> diff --git a/xml/System.Data.Common.CommandTrees/DbUnaryExpression.xml b/xml/System.Data.Common.CommandTrees/DbUnaryExpression.xml index 1e62a35dce9..8df42a29358 100644 --- a/xml/System.Data.Common.CommandTrees/DbUnaryExpression.xml +++ b/xml/System.Data.Common.CommandTrees/DbUnaryExpression.xml @@ -17,11 +17,11 @@ Implements the basic functionality required by expressions that accept a single expression argument. - @@ -52,11 +52,11 @@ Gets or sets the that defines the argument. The that defines the argument. - property is set. For example, requires that its argument expression has a collection result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. - + property is set. For example, requires that its argument expression has a collection result type. Typically, derived expression types will not allow to be set to an expression with a result type that is not equal or promotable to the result type of the current value. + ]]> The expression is . diff --git a/xml/System.Data.Common.CommandTrees/DbUpdateCommandTree.xml b/xml/System.Data.Common.CommandTrees/DbUpdateCommandTree.xml index 255a41908b2..fab9c059d5f 100644 --- a/xml/System.Data.Common.CommandTrees/DbUpdateCommandTree.xml +++ b/xml/System.Data.Common.CommandTrees/DbUpdateCommandTree.xml @@ -17,11 +17,11 @@ Represents a single-row update operation expressed as a command tree. This class cannot be inherited. - property is set, the command returns a reader; otherwise, it returns a scalar value indicating the number of rows affected. - + property is set, the command returns a reader; otherwise, it returns a scalar value indicating the number of rows affected. + ]]> @@ -52,11 +52,11 @@ Gets an that specifies the predicate used to determine which members of the target collection should be updated. An that specifies the predicate used to determine which members of the target collection should be updated. - representing equality; ; ; ; a that references the target; ; ; . - + representing equality; ; ; ; a that references the target; ; ; . + ]]> @@ -87,11 +87,11 @@ Gets an that specifies a projection of results to be returned, based on the modified rows. An that specifies a projection of results to be returned based, on the modified rows. indicates that no results should be returned from this command. - ; . - + ; . + ]]> diff --git a/xml/System.Data.Common/DBDataPermission.xml b/xml/System.Data.Common/DBDataPermission.xml index 9a93f429f46..6e1072ab919 100644 --- a/xml/System.Data.Common/DBDataPermission.xml +++ b/xml/System.Data.Common/DBDataPermission.xml @@ -272,7 +272,7 @@ enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. + The enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. ]]> @@ -376,7 +376,7 @@ enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. + The enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. ]]> diff --git a/xml/System.Data.Common/DBDataPermissionAttribute.xml b/xml/System.Data.Common/DBDataPermissionAttribute.xml index bf2069b149c..a2ec1cf7549 100644 --- a/xml/System.Data.Common/DBDataPermissionAttribute.xml +++ b/xml/System.Data.Common/DBDataPermissionAttribute.xml @@ -170,11 +170,11 @@ Gets or sets a permitted connection string. A permitted connection string. - ADO.NET Overview @@ -251,15 +251,15 @@ Gets or sets connection string parameters that are allowed or disallowed. One or more connection string parameters that are allowed or disallowed. - *=. Multiple parameters can be specified, delimited using a semicolon (;). The connection string parameters listed may be identified as either the only additional parameters allowed or additional parameters that are not allowed using the property. - - If no key restrictions are specified, and the property is set to `AllowOnly`, no additional connection string parameters are allowed. - - If no key restrictions are specified, and the property is set to `PreventUsage`, additional connection string parameters are allowed. If more than one rule is set for the same connection string, the more restrictive rule is selected during the permission check. - + *=. Multiple parameters can be specified, delimited using a semicolon (;). The connection string parameters listed may be identified as either the only additional parameters allowed or additional parameters that are not allowed using the property. + + If no key restrictions are specified, and the property is set to `AllowOnly`, no additional connection string parameters are allowed. + + If no key restrictions are specified, and the property is set to `PreventUsage`, additional connection string parameters are allowed. If more than one rule is set for the same connection string, the more restrictive rule is selected during the permission check. + ]]> ADO.NET Overview diff --git a/xml/System.Data.Common/DataAdapter.xml b/xml/System.Data.Common/DataAdapter.xml index 619d3003350..17801b681e1 100644 --- a/xml/System.Data.Common/DataAdapter.xml +++ b/xml/System.Data.Common/DataAdapter.xml @@ -310,10 +310,10 @@ being updated. By default, ADO.NET calls the `AcceptChanges` method of the `DataRow` after the update. However, if you want to merge the updated row back into another , you may want to preserver the original value of a primary key column. For example, a primary key column corresponding to an automatically incrementing column in the database, such as an identity column, can contain new values that are assigned by the database that do not match the original values assigned in the `DataRow`. By default, `AcceptChanges` is called implicitly after an update, and the original values in the row, which may have been values assigned by ADO.NET, are lost. You can preserve the original values in the `DataRow` by preventing `ADO.NET` from calling `AcceptChanges` after it performs an update on a row, by setting the property to `false`, which preserves the original values. + During a call to the `Update` method of a `DataAdapter`, the database can send data back to your ADO.NET application as output parameters or as the first returned record of a result set. ADO.NET can retrieve these values and update the corresponding columns in the being updated. By default, ADO.NET calls the `AcceptChanges` method of the `DataRow` after the update. However, if you want to merge the updated row back into another , you may want to preserver the original value of a primary key column. For example, a primary key column corresponding to an automatically incrementing column in the database, such as an identity column, can contain new values that are assigned by the database that do not match the original values assigned in the `DataRow`. By default, `AcceptChanges` is called implicitly after an update, and the original values in the row, which may have been values assigned by ADO.NET, are lost. You can preserve the original values in the `DataRow` by preventing `ADO.NET` from calling `AcceptChanges` after it performs an update on a row, by setting the property to `false`, which preserves the original values. > [!NOTE] -> Setting the `AcceptChangesDuringUpdate` property to `false` applies to all data modifications, not only inserts. If you want to edit or delete rows in the same update, and if you want to suppress the call to `AcceptChanges` only for inserts, then instead of setting `AcceptChangesDuringUpdate` to `false`, use an event handler for the `RowUpdated` event of the `DataAdapter`. In the event handler, you can check the to determine if the data modification is an insert, and if `true`, set the property of the to . For more information and an example, see [Retrieving Identity or Autonumber Values](/dotnet/framework/data/adonet/retrieving-identity-or-autonumber-values). +> Setting the `AcceptChangesDuringUpdate` property to `false` applies to all data modifications, not only inserts. If you want to edit or delete rows in the same update, and if you want to suppress the call to `AcceptChanges` only for inserts, then instead of setting `AcceptChangesDuringUpdate` to `false`, use an event handler for the `RowUpdated` event of the `DataAdapter`. In the event handler, you can check the to determine if the data modification is an insert, and if `true`, set the property of the to . For more information and an example, see [Retrieving Identity or Autonumber Values](/dotnet/framework/data/adonet/retrieving-identity-or-autonumber-values). @@ -459,7 +459,7 @@ property of the row in error. The continues to update subsequent rows. + If `ContinueUpdateOnError` is set to `true`, no exception is thrown when an error occurs during the update of a row. The update of the row is skipped and the error information is placed in the property of the row in error. The continues to update subsequent rows. If `ContinueUpdateOnError` is set to `false`, an exception is thrown when an error occurs during the update of a row. @@ -639,9 +639,9 @@ method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + The method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). @@ -1038,12 +1038,12 @@ - If one or more primary key columns are returned by the , they are used as the primary key columns for the . -- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. +- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. - If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the . > [!NOTE] -> The underlying data store may allow column attributes that are not supported in a , which causes some column attributes to not translate correctly. For example, SQL Server allows an identity column with a data type of tinyint whereas a only allows Int16, Int32, and Int64 to have the property set. `FillSchema` silently ignores cases where the cannot accurately mirror the data source and throws no exception. +> The underlying data store may allow column attributes that are not supported in a , which causes some column attributes to not translate correctly. For example, SQL Server allows an identity column with a data type of tinyint whereas a only allows Int16, Int32, and Int64 to have the property set. `FillSchema` silently ignores cases where the cannot accurately mirror the data source and throws no exception. Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. @@ -1340,7 +1340,7 @@ If a unique clustered index is defined on a column or columns in a SQL Server ta property provides the primary mapping between the returned records and the . + The property provides the primary mapping between the returned records and the . @@ -1899,13 +1899,13 @@ If a unique clustered index is defined on a column or columns in a SQL Server ta method determines the type of change that has been performed on it (Insert, Update or Delete). Depending on the type of change, the `Insert`, `Update,` or `Delete` command template executes to propagate the modified row to the data source. When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + The update is performed on a by-row basis. For every inserted, modified, and deleted row, the method determines the type of change that has been performed on it (Insert, Update or Delete). Depending on the type of change, the `Insert`, `Update,` or `Delete` command template executes to propagate the modified row to the data source. When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERT before UPDATE). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. @@ -1942,7 +1942,7 @@ If a unique clustered index is defined on a column or columns in a SQL Server ta Calling the method or method will commit all changes in the or . If either of these methods are called before the method is called, no changes will be committed when the method is called, unless further changes have been made since or was called. > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . > > For every column that you propagate to the data source on , a parameter should be added to the `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The `SourceColumn` property of the parameter should be set to the name of the column. This setting indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. diff --git a/xml/System.Data.Common/DbBatch.xml b/xml/System.Data.Common/DbBatch.xml index e5379532bc7..4e7ecdb3f26 100644 --- a/xml/System.Data.Common/DbBatch.xml +++ b/xml/System.Data.Common/DbBatch.xml @@ -805,7 +805,7 @@ The precise semantics of batch execution vary across ADO.NET providers, especial is generated if the assigned property value is less than 0. + An is generated if the assigned property value is less than 0. Note to implementers: it's recommended that 0 mean no timeout. diff --git a/xml/System.Data.Common/DbCommand.xml b/xml/System.Data.Common/DbCommand.xml index d54b1f24942..7324026bd38 100644 --- a/xml/System.Data.Common/DbCommand.xml +++ b/xml/System.Data.Common/DbCommand.xml @@ -239,7 +239,7 @@ to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the `Execute` methods. + When you set the to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the `Execute` methods. ]]> @@ -293,7 +293,7 @@ is generated if the assigned property value is less than 0. + An is generated if the assigned property value is less than 0. Note to implementers, it is recommended that 0 mean no timeout. @@ -359,7 +359,7 @@ to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the `Execute` methods. + When you set the to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the `Execute` methods. ]]> @@ -1805,7 +1805,7 @@ property is set to `TableDirect`, `Prepare` does nothing. If is set to `StoredProcedure`, the call to `Prepare` should succeed, although it may result in a no-op. + If the property is set to `TableDirect`, `Prepare` does nothing. If is set to `StoredProcedure`, the call to `Prepare` should succeed, although it may result in a no-op. ]]> @@ -1856,7 +1856,7 @@ Data providers that support [asynchronous programming](/dotnet/framework/data/adonet/asynchronous-programming) should override the default implementation using asynchronous I/O operations. - If the property is set to `TableDirect`, `PrepareAsync` does nothing. If is set to `StoredProcedure`, the call to `PrepareAsync` should succeed, although it may result in a no-op. + If the property is set to `TableDirect`, `PrepareAsync` does nothing. If is set to `StoredProcedure`, the call to `PrepareAsync` should succeed, although it may result in a no-op. 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 . diff --git a/xml/System.Data.Common/DbCommandBuilder.xml b/xml/System.Data.Common/DbCommandBuilder.xml index f05f2bdce9e..10df25ac81b 100644 --- a/xml/System.Data.Common/DbCommandBuilder.xml +++ b/xml/System.Data.Common/DbCommandBuilder.xml @@ -56,11 +56,11 @@ ## Remarks The class is provided for the convenience of provider writers creating their own command builders. By inheriting from this class, developers can implement provider specific behavior in their own code. - The does not automatically generate the SQL statements required to reconcile changes made to a with the associated data source. However, you can create a object to automatically generate SQL statements for single-table updates if you set the property of the . Then, any additional SQL statements that you do not set are generated by the . + The does not automatically generate the SQL statements required to reconcile changes made to a with the associated data source. However, you can create a object to automatically generate SQL statements for single-table updates if you set the property of the . Then, any additional SQL statements that you do not set are generated by the . - The registers itself as a listener for events whenever you set the property. You can only associate one or object with each other at one time. + The registers itself as a listener for events whenever you set the property. You can only associate one or object with each other at one time. - To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata has been retrieved (for example, after the first update), you should call the method to update the metadata. + To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata has been retrieved (for example, after the first update), you should call the method to update the metadata. The `SelectCommand` must also return at least one primary key or unique column. If none exist, an exception is generated, and the commands are not generated. @@ -1545,7 +1545,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel can include update information about all the columns, or it can include information only about those columns whose values have changed. Setting the property to `true` causes the generated UPDATE statement to include all the columns, whether their values have changed or not. + The UPDATE statement generated by a can include update information about all the columns, or it can include information only about those columns whose values have changed. Setting the property to `true` causes the generated UPDATE statement to include all the columns, whether their values have changed or not. ]]> diff --git a/xml/System.Data.Common/DbConnectionStringBuilder.xml b/xml/System.Data.Common/DbConnectionStringBuilder.xml index 7fab3e36520..0300d49fdaa 100644 --- a/xml/System.Data.Common/DbConnectionStringBuilder.xml +++ b/xml/System.Data.Common/DbConnectionStringBuilder.xml @@ -95,7 +95,7 @@ If you need to create connection strings as part of applications, use the class. The performs no checks for valid key/value pairs. Therefore, it's possible to create invalid connection strings when using this class. The supports only key/value pairs that are supported by SQL Server; trying to add invalid pairs will throw an exception. - Both the method and property handle cases where a bad actor tries to insert malicious entries. For example, the following code correctly escapes the nested key/value pair: + Both the method and property handle cases where a bad actor tries to insert malicious entries. For example, the following code correctly escapes the nested key/value pair: ```vb Dim builder As New System.Data.Common.DbConnectionStringBuilder @@ -119,7 +119,7 @@ initial catalog="AdventureWorks;NewValue=Bad" ``` ## Examples - The following console application builds two connection strings, one for a Microsoft Jet database, and one for a SQL Server database. In each case, the code uses a generic class to create the connection string, and then passes the property of the instance to the constructor of the strongly typed connection class. This is not required; the code could also have created individual strongly typed connection string builder instances. The example also parses an existing connection string, and demonstrates various ways of manipulating the connection string's contents. + The following console application builds two connection strings, one for a Microsoft Jet database, and one for a SQL Server database. In each case, the code uses a generic class to create the connection string, and then passes the property of the instance to the constructor of the strongly typed connection class. This is not required; the code could also have created individual strongly typed connection string builder instances. The example also parses an existing connection string, and demonstrates various ways of manipulating the connection string's contents. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DbConnectionStringBuilder/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbConnectionStringBuilder/Overview/source.vb" id="Snippet1"::: @@ -283,7 +283,7 @@ initial catalog="AdventureWorks;NewValue=Bad" property can also be used to add new elements by setting the value of a key that does not exist in the dictionary. For example: `myCollection["myNonexistentKey"] = myValue`. + The property can also be used to add new elements by setting the value of a key that does not exist in the dictionary. For example: `myCollection["myNonexistentKey"] = myValue`. Calling the method by passing a null (`Nothing` in Visual Basic) key throws an . However, calling the method by passing a null value removes the key/value pair. @@ -526,7 +526,7 @@ initial catalog="AdventureWorks;NewValue=Bad" class must be able to make the connection string visible or invisible within the designer's property grid. The property lets developers indicate that the property should be invisible by setting the property to `false`. + Developers creating designers that take advantage of the class must be able to make the connection string visible or invisible within the designer's property grid. The property lets developers indicate that the property should be invisible by setting the property to `false`. ]]> @@ -581,7 +581,7 @@ initial catalog="AdventureWorks;NewValue=Bad" method removes all key/value pairs from the and resets all corresponding properties. This includes setting the property to 0 and the property to an empty string. + The method removes all key/value pairs from the and resets all corresponding properties. This includes setting the property to 0 and the property to an empty string. ]]> @@ -697,20 +697,20 @@ initial catalog="AdventureWorks;NewValue=Bad" Data providers may expect specific keys and values for each connection string property. , These values are documented individually. The class does not validate the key/value pairs associated with its connection string, although classes that inherit from it can. - The property of the class acts generally as a mechanism for creating and parsing semicolon-delimited lists of key/value pairs separated with equal signs. It provides no validation or other support specific to connection strings. If you add items to the collection, the property will reflect the changes. If you assign a value to the property, the will try to parse the value, using the semicolon and equal-sign delimiters. + The property of the class acts generally as a mechanism for creating and parsing semicolon-delimited lists of key/value pairs separated with equal signs. It provides no validation or other support specific to connection strings. If you add items to the collection, the property will reflect the changes. If you assign a value to the property, the will try to parse the value, using the semicolon and equal-sign delimiters. ## Examples - The following example demonstrates possible behaviors of the property. The example: + The following example demonstrates possible behaviors of the property. The example: - Creates a connection string by adding key/value pairs, one at a time, to an empty . -- Assigns a complete connection string to the property of the instance, and modifies a single key/value pair within the string. +- Assigns a complete connection string to the property of the instance, and modifies a single key/value pair within the string. -- Assigns an arbitrary set of key/value pairs to the property (that is, a string that is not anything remotely like a connection string), and modifies one of the values. +- Assigns an arbitrary set of key/value pairs to the property (that is, a string that is not anything remotely like a connection string), and modifies one of the values. -- Assigns an invalid connection string to the property, demonstrating the exception that is thrown. +- Assigns an invalid connection string to the property, demonstrating the exception that is thrown. > [!NOTE] > This example includes a password to demonstrate how works with connection strings. In your applications, we recommend that you use Windows Authentication. If you must use a password, do not include a hard-coded password in your application. @@ -848,7 +848,7 @@ The collection contains the key "Data Source". property both before and after you modify the contents of the property. + The following example demonstrates the property both before and after you modify the contents of the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DbConnectionStringBuilder.Count/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbConnectionStringBuilder/Count/source.vb" id="Snippet1"::: @@ -1171,7 +1171,7 @@ builder2.EquivalentTo(builder3) = False ## Examples - The following console application creates a new and adds key/value pairs to its connection string, using the property. + The following console application creates a new and adds key/value pairs to its connection string, using the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DbConnectionStringBuilder.Item/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbConnectionStringBuilder/Item/source.vb" id="Snippet1"::: @@ -1244,14 +1244,14 @@ builder2.EquivalentTo(builder3) = False is unspecified, but it is the same order as the associated values in the returned by the property. + The order of the values in the is unspecified, but it is the same order as the associated values in the returned by the property. The returned is not a static copy; instead, the refers back to the keys in the original . Therefore, changes to the are reflected in the . ## Examples - The following console application example creates a new , and adds some keys. The code loops through the returned by the property displaying the key/value pairs, and then adds a new key. Because the property returns a dynamic , the second loop displays all the key/value pairs, including the newest item. + The following console application example creates a new , and adds some keys. The code loops through the returned by the property displaying the key/value pairs, and then adds a new key. Because the property returns a dynamic , the second loop displays all the key/value pairs, including the newest item. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DbConnectionStringBuilder.Keys/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbConnectionStringBuilder/Keys/source.vb" id="Snippet1"::: diff --git a/xml/System.Data.Common/DbDataAdapter.xml b/xml/System.Data.Common/DbDataAdapter.xml index 82e0b6c8930..f4418e56ad8 100644 --- a/xml/System.Data.Common/DbDataAdapter.xml +++ b/xml/System.Data.Common/DbDataAdapter.xml @@ -68,41 +68,41 @@ Aids implementation of the interface. Inheritors of implement a set of functions to provide strong typing, but inherit most of the functionality needed to fully implement a **DataAdapter**. - class inherits from the class and implements the interface. It helps a class implement a **DataAdapter** designed for use with a relational database. - - An application does not create an instance of the class directly, but creates an instance of a class that inherits from it. - - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the class defines the property, and the class defines eight overloads of the method. In turn, the class inherits the method, and also defines two additional overloads of that take an ADO Recordset object as a parameter. - + class inherits from the class and implements the interface. It helps a class implement a **DataAdapter** designed for use with a relational database. + + An application does not create an instance of the class directly, but creates an instance of a class that inherits from it. + + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the class defines the property, and the class defines eight overloads of the method. In turn, the class inherits the method, and also defines two additional overloads of that take an ADO Recordset object as a parameter. + ]]> - When you inherit from the class, we recommend that you implement the following constructors: - - Item - - Description - - *Prv*DataAdapter() - - Initializes a new instance of the *Prv*DataAdapter class. - - *Prv*DataAdapter(*Prv*Command *selectCommand*) - - Initializes a new instance of the *Prv*DataAdapter class with the specified SQL SELECT statement. - - *Prv*DataAdapter(string *selectCommandText*, string *selectConnectionString*) - - Initializes a new instance of the *Prv*DataAdapter class with an SQL SELECT statement and a connection string. - - *Prv*DataAdapter(string *selectCommandText*, *Prv*Connection *selectConnection*) - - Initializes a new instance of the *Prv*DataAdapter class with an SQL SELECT statement and a *Prv*Connection object. - - + When you inherit from the class, we recommend that you implement the following constructors: + + Item + + Description + + *Prv*DataAdapter() + + Initializes a new instance of the *Prv*DataAdapter class. + + *Prv*DataAdapter(*Prv*Command *selectCommand*) + + Initializes a new instance of the *Prv*DataAdapter class with the specified SQL SELECT statement. + + *Prv*DataAdapter(string *selectCommandText*, string *selectConnectionString*) + + Initializes a new instance of the *Prv*DataAdapter class with an SQL SELECT statement and a connection string. + + *Prv*DataAdapter(string *selectCommandText*, *Prv*Connection *selectConnection*) + + Initializes a new instance of the *Prv*DataAdapter class with an SQL SELECT statement and a *Prv*Connection object. + + To promote consistency among .NET Framework data providers, you should name the inheriting class in the form *Prv*DataAdapter, where *Prv* is the uniform prefix given to all classes in a specific .NET Framework data provider namespace. For example, "Sql" is the prefix of the class in the **System.Data.SqlClient** namespace. @@ -157,22 +157,22 @@ Initializes a new instance of a **DataAdapter** class. - , the following read/write properties are set to the following initial values. - -|Properties|Initial value| -|----------------|-------------------| -||A new .| -||A new .| -||A new .| -||A new .| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| - - You can change the value of any of these properties through a separate call to the property. - + , the following read/write properties are set to the following initial values. + +|Properties|Initial value| +|----------------|-------------------| +||A new .| +||A new .| +||A new .| +||A new .| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| + + You can change the value of any of these properties through a separate call to the property. + ]]> DbProviderFactories (ADO.NET) @@ -219,11 +219,11 @@ A object used to create the new . Initializes a new instance of the class from an existing object of the same type. - constructor is designed for use by a .NET Framework data provider when implementing a similar constructor for use in a clone implementation. - + constructor is designed for use by a .NET Framework data provider when implementing a similar constructor for use in a clone implementation. + ]]> DbProviderFactories (ADO.NET) @@ -273,17 +273,17 @@ Adds a to the current batch. The number of commands in the batch before adding the . - , this method throws . Classes that inherit from override this method to provide support for batches. - + , this method throws . Classes that inherit from override this method to provide support for batches. + ]]> The adapter does not support batches. - This method is protected and is designed for use by a .NET Framework data provider. - + This method is protected and is designed for use by a .NET Framework data provider. + If a class that inherits from supports batches, that class overrides this method to allow users to add a command to a batch. DbProviderFactories (ADO.NET) @@ -329,17 +329,17 @@ Removes all objects from the batch. - , this method throws . Classes that inherit from override this method to provide support for batches. - + , this method throws . Classes that inherit from override this method to provide support for batches. + ]]> The adapter does not support batches. - This method is protected and is designed for use by a .NET Framework data provider. - + This method is protected and is designed for use by a .NET Framework data provider. + If a class that inherits from supports batches, that class overrides this method to allow users to remove all commands from a batch. DbProviderFactories (ADO.NET) @@ -522,13 +522,13 @@ The default name used by the object for table mappings. - object for table mappings. - - is when an application adds a table mapping to be used with , but does not specify a name. - + object for table mappings. + + is when an application adds a table mapping to be used with , but does not specify a name. + ]]> DbProviderFactories (ADO.NET) @@ -589,19 +589,19 @@ Gets or sets a command for deleting records from the data set. An used during to delete records in the data source for deleted rows in the data set. - , if this property is not set and primary key information is present in the , the is automatically generated. - - - -## Examples - The following example creates the derived class and sets some of its properties. - + , if this property is not set and primary key information is present in the , the is automatically generated. + + + +## Examples + The following example creates the derived class and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.DeleteCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -697,16 +697,16 @@ Executes the current batch. The return value from the last command in the batch. - , this method throws . Classes that inherit from override this method to provide support for batches. - + , this method throws . Classes that inherit from override this method to provide support for batches. + ]]> - This method is protected and is designed for use by a .NET Framework data provider. - + This method is protected and is designed for use by a .NET Framework data provider. + If a class that inherits from supports batches, that class overrides this method to allow users to execute a batch. An implementation of this method combines the commands in the adapter into a batch, then executes the batch and returns the return value of the batch. Manipulating Data (ADO.NET) @@ -772,34 +772,34 @@ Adds or refreshes rows in the . The number of rows successfully added to or refreshed in the . This does not include rows affected by statements that do not return rows. - method retrieves the data from the data source using a SELECT statement. The object associated with the select command must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. - - If an error or an exception is encountered while populating the data tables, rows added prior to the occurrence of the error remain in the data tables. The remainder of the operation is aborted. - - If a command does not return any rows, no tables are added to the , and no exception is raised. - - If the object encounters duplicate columns while populating a , it generates names for the subsequent columns using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. - - When the query specified returns multiple results, the result set for each row returning query is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Because no table is created for a query that does not return rows, if you process an insert query followed by a select query, the table created for the select query is named "Table" because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - When the SELECT statement used to populate the returns multiple results, such as batch SQL statements, if one of the results contains an error, all subsequent results are skipped and are not added to the . - - When using subsequent calls to refresh the contents of the , two conditions must be met: - -1. The SQL statement should match the one initially used to populate the . - -2. The **Key** column information must be present. - - If primary key information is present, any duplicate rows are reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. - - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - + method retrieves the data from the data source using a SELECT statement. The object associated with the select command must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. + + If an error or an exception is encountered while populating the data tables, rows added prior to the occurrence of the error remain in the data tables. The remainder of the operation is aborted. + + If a command does not return any rows, no tables are added to the , and no exception is raised. + + If the object encounters duplicate columns while populating a , it generates names for the subsequent columns using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. + + When the query specified returns multiple results, the result set for each row returning query is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Because no table is created for a query that does not return rows, if you process an insert query followed by a select query, the table created for the select query is named "Table" because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + When the SELECT statement used to populate the returns multiple results, such as batch SQL statements, if one of the results contains an error, all subsequent results are skipped and are not added to the . + + When using subsequent calls to refresh the contents of the , two conditions must be met: + +1. The SQL statement should match the one initially used to populate the . + +2. The **Key** column information must be present. + + If primary key information is present, any duplicate rows are reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. + + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. + ]]> DbProviderFactories (ADO.NET) @@ -850,42 +850,42 @@ Adds or refreshes rows in a specified range in the to match those in the data source using the name. The number of rows successfully added to or refreshed in the . This does not include rows affected by statements that do not return rows. - method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - - The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - - If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. - - The overload of that takes `DataTable` as a parameter only obtains the first result. Use an overload of that takes `DataSet` as a parameter to obtain multiple results. - - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); - dataset.Tables.Add("aaa"); - dataset.Tables.Add("AAA"); - adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet. - adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". -``` - - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); - dataset.Tables.Add("aaa"); - adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. -``` - - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . - - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - + method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + + The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + + If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. + + The overload of that takes `DataTable` as a parameter only obtains the first result. Use an overload of that takes `DataSet` as a parameter to obtain multiple results. + + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); + dataset.Tables.Add("aaa"); + dataset.Tables.Add("AAA"); + adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet. + adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". +``` + + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); + dataset.Tables.Add("aaa"); + adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. +``` + + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . + + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of and for a .NET Framework data provider retrieves schema information for only the first result. - +> When handling batch SQL statements that return multiple results, the implementation of and for a .NET Framework data provider retrieves schema information for only the first result. + ]]> The source table is invalid. @@ -942,58 +942,58 @@ DataSet dataset = new DataSet(); Adds or refreshes rows in the to match those in the data source using the and names. The number of rows successfully added to or refreshed in the . This does not include rows affected by statements that do not return rows. - method retrieves the data from the data source using a SELECT statement. The object associated with the select command must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - - If a command does not return any rows, no tables are added to the , and no exception is raised. - - If the object encounters duplicate columns while populating a , it will generate names for the subsequent columns, using the pattern "columnname1", "columnname2", "columnname3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. - - When the query specified returns multiple results, each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Since no table is created for a query that does not return rows, if you were to process an insert query followed by a select query, the table created for the select query would be named "Table", because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -dataset.Tables.Add("AAA"); -adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet. -adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". -``` - - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. -``` - - If an error or an exception is encountered while populating the data tables, rows added prior to the occurrence of the error remain in the data tables. The remainder of the operation is aborted. - - When the SELECT statement used to populate the returns multiple results, such as a batch SQL statement, be aware of the following: - -- If one of the results contains an error, all subsequent results are skipped and not added to the . - - When using subsequent calls to refresh the contents of the , two conditions must be met: - -1. The SQL statement should match the one initially used to populate the . - -2. The **Key** column information must be present. If primary key information is present, any duplicate rows are reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. - - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - + method retrieves the data from the data source using a SELECT statement. The object associated with the select command must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + + If a command does not return any rows, no tables are added to the , and no exception is raised. + + If the object encounters duplicate columns while populating a , it will generate names for the subsequent columns, using the pattern "columnname1", "columnname2", "columnname3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. + + When the query specified returns multiple results, each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Since no table is created for a query that does not return rows, if you were to process an insert query followed by a select query, the table created for the select query would be named "Table", because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +dataset.Tables.Add("AAA"); +adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet. +adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". +``` + + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. +``` + + If an error or an exception is encountered while populating the data tables, rows added prior to the occurrence of the error remain in the data tables. The remainder of the operation is aborted. + + When the SELECT statement used to populate the returns multiple results, such as a batch SQL statement, be aware of the following: + +- If one of the results contains an error, all subsequent results are skipped and not added to the . + + When using subsequent calls to refresh the contents of the , two conditions must be met: + +1. The SQL statement should match the one initially used to populate the . + +2. The **Key** column information must be present. If primary key information is present, any duplicate rows are reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. + + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + > [!NOTE] > When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - -## Examples - The following example uses the derived class, , to fill a with rows from the categories table. This example assumes that you have created an and a . - + +## Examples + The following example uses the derived class, , to fill a with rows from the categories table. This example assumes that you have created an and a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.Fill2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Fill/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Fill/source.vb" id="Snippet1"::: + ]]> The source table is invalid. @@ -1085,24 +1085,24 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na Adds or refreshes rows in a to match those in the data source using the specified , and . The number of rows successfully added to or refreshed in the . This does not include rows affected by statements that do not return rows. - method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. - - The operation then adds the rows to the specified destination object in the , creating the object if it does not already exist. When creating a object, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - - If the object encounters duplicate columns while populating a , it will generate names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. - - The overload of that takes `DataTable` as a parameter only obtains the first result. Use an overload of that takes `DataSet` as a parameter to obtain multiple results. - - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . - - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - + method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. + + The operation then adds the rows to the specified destination object in the , creating the object if it does not already exist. When creating a object, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + + If the object encounters duplicate columns while populating a , it will generate names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. + + The overload of that takes `DataTable` as a parameter only obtains the first result. Use an overload of that takes `DataSet` as a parameter to obtain multiple results. + + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . + + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. + ]]> @@ -1166,27 +1166,27 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na Adds or refreshes rows in one or more objects to match those in the data source starting at the specified record and retrieving up to the specified maximum number of records. The number of rows successfully added to or refreshed in the objects. This value does not include rows affected by statements that do not return rows. - method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, and then it is closed. If the connection is open before is called, it remains open. - - The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - - If the data adapter encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "columnname1", "columnname2", "columnname3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the , each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - When the SELECT statement used to populate the returns multiple results, such as a batch SQL statements, if one of the results contains an error, all subsequent results are skipped and not added to the . - - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . - + The method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, and then it is closed. If the connection is open before is called, it remains open. + + The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + + If the data adapter encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "columnname1", "columnname2", "columnname3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the , each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + When the SELECT statement used to populate the returns multiple results, such as a batch SQL statements, if one of the results contains an error, all subsequent results are skipped and not added to the . + + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. + ]]> @@ -1251,83 +1251,83 @@ A `maxRecords` value of 0 gets all records found after the start record. If `max Adds or refreshes rows in a specified range in the to match those in the data source using the and names. The number of rows successfully added to or refreshed in the . This does not include rows affected by statements that do not return rows. - only applies `maxRecords` to the first result. - - The method retrieves the data from the data source using a SELECT statement. The object associated with the SELECT statement must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. - - If a command does not return any rows, no tables are added to the , but no exception is raised. - - If the object encounters duplicate columns while populating a , it will generate names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. - - When the query specified returns multiple results, each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Because no table is created for a query that does not return rows, if you process an insert query followed by a select query, the table created for the select query is named "Table", because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -dataset.Tables.Add("AAA"); -adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet. -adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". -``` - - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. -``` - - If an error or an exception is encountered while populating the data tables, rows added prior to the occurrence of the error remain in the data tables. The remainder of the operation is aborted. - - When the SELECT statement used to populate the returns multiple results, such as batch SQL statements, be aware of the following: - -- When processing multiple results from a batch SQL statement, `maxRecords` only applies to the first result. The same is true for rows containing chaptered results (.NET Framework Data Provider for OLE DB only). The top level result is limited by `maxRecords`, but all child rows are added. - -- If one of the results contains an error, all subsequent results are skipped and not added to the . - - When using subsequent calls to refresh the contents of the , two conditions must be met: - -1. The SQL statement should match the one initially used to populate the . - -2. The **Key** column information must be present. - - If primary key information is present, any duplicate rows will be reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. - - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - + + If the corresponding select command is a statement returning multiple results, only applies `maxRecords` to the first result. + + The method retrieves the data from the data source using a SELECT statement. The object associated with the SELECT statement must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data and then closed. If the connection is open before is called, it remains open. + + If a command does not return any rows, no tables are added to the , but no exception is raised. + + If the object encounters duplicate columns while populating a , it will generate names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. + + When the query specified returns multiple results, each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Because no table is created for a query that does not return rows, if you process an insert query followed by a select query, the table created for the select query is named "Table", because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +dataset.Tables.Add("AAA"); +adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet. +adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". +``` + + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. +``` + + If an error or an exception is encountered while populating the data tables, rows added prior to the occurrence of the error remain in the data tables. The remainder of the operation is aborted. + + When the SELECT statement used to populate the returns multiple results, such as batch SQL statements, be aware of the following: + +- When processing multiple results from a batch SQL statement, `maxRecords` only applies to the first result. The same is true for rows containing chaptered results (.NET Framework Data Provider for OLE DB only). The top level result is limited by `maxRecords`, but all child rows are added. + +- If one of the results contains an error, all subsequent results are skipped and not added to the . + + When using subsequent calls to refresh the contents of the , two conditions must be met: + +1. The SQL statement should match the one initially used to populate the . + +2. The **Key** column information must be present. + + If primary key information is present, any duplicate rows will be reconciled and only appear once in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. + + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. + > [!NOTE] > The `DataSet` will not contain more than the number of records indicated by `maxRecords`. However, the entire result set generated by the query is still returned from the server. - -## Examples - The following example uses the derived class, , to fill a with 15 rows, beginning at row 10, from the **Categories** table. This example assumes that you have created an and a . - + +## Examples + The following example uses the derived class, , to fill a with 15 rows, beginning at row 10, from the **Categories** table. This example assumes that you have created an and a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.Fill3 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Fill/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Fill/source1.vb" id="Snippet1"::: + ]]> The is invalid. - The source table is invalid. - - -or- - + The source table is invalid. + + -or- + The connection is invalid. The connection could not be found. - The parameter is less than 0. - - -or- - + The parameter is less than 0. + + -or- + The parameter is less than 0. When overriding in a derived class, be sure to call the base class's method. @@ -1432,62 +1432,62 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na Adds or refreshes rows in a specified range in the to match those in the data source using the and names. The number of rows added to or refreshed in the data tables. - method retrieves the data from the data source using a SELECT statement. The object associated with the SELECT statement must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - - If a command does not return any rows, no tables are added to the , but no exception is raised. - - If the object encounters duplicate columns while populating a , it will generate names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. - - When the query specified returns multiple results, each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Since no table is created for a query that does not return rows, if you were to process an insert query followed by a select query, the table created for the select query would be named "Table", because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -dataset.Tables.Add("AAA"); -adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet. -adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". -``` - - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. -``` - - If an error or an exception is encountered while populating the data tables, rows added prior to the occurrence of the error remain in the data tables. The remainder of the operation is aborted. - - When the SELECT statement used to populate the objects returns multiple results, such as a batch SQL statement, be aware of the following: - -- When processing multiple results from a batch SQL statement, `maxRecords` only applies to the first result. The same is true for rows containing chaptered results (.NET Framework Data Provider for OLE DB only). The top-level result is limited by `maxRecords`, but all child rows are added. - -- If one of the results contains an error, all subsequent results are skipped. - + + The method retrieves the data from the data source using a SELECT statement. The object associated with the SELECT statement must be valid, but it does not need to be open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + + If a command does not return any rows, no tables are added to the , but no exception is raised. + + If the object encounters duplicate columns while populating a , it will generate names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. + + When the query specified returns multiple results, each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). Since no table is created for a query that does not return rows, if you were to process an insert query followed by a select query, the table created for the select query would be named "Table", because it is the first table created. If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +dataset.Tables.Add("AAA"); +adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet. +adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". +``` + + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. +``` + + If an error or an exception is encountered while populating the data tables, rows added prior to the occurrence of the error remain in the data tables. The remainder of the operation is aborted. + + When the SELECT statement used to populate the objects returns multiple results, such as a batch SQL statement, be aware of the following: + +- When processing multiple results from a batch SQL statement, `maxRecords` only applies to the first result. The same is true for rows containing chaptered results (.NET Framework Data Provider for OLE DB only). The top-level result is limited by `maxRecords`, but all child rows are added. + +- If one of the results contains an error, all subsequent results are skipped. + > [!NOTE] -> The `DataSet` will not contain more than the number of records indicated by `maxRecords`. However, the entire resultset generated by the query is still returned from the server. - +> The `DataSet` will not contain more than the number of records indicated by `maxRecords`. However, the entire resultset generated by the query is still returned from the server. + ]]> The is invalid. - The source table is invalid. - - -or- - + The source table is invalid. + + -or- + The connection is invalid. The connection could not be found. - The parameter is less than 0. - - -or- - + The parameter is less than 0. + + -or- + The parameter is less than 0. When overriding in a derived class, be sure to call the base class's method. @@ -1550,50 +1550,50 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na Adds or refreshes rows in a specified range in the to match those in the data source using the and source table names, command string, and command behavior. The number of rows successfully added to or refreshed in the . This does not include rows affected by statements that do not return rows. - method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - - The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - - If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -dataset.Tables.Add("AAA"); -adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet. -adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". -``` - - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. -``` - - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . - - If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - + The method retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + + The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation normally creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + + If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on). If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +dataset.Tables.Add("AAA"); +adapter.Fill(dataset, "aaa"); // Fills "aaa", which already exists in the DataSet. +adapter.Fill(dataset, "Aaa"); // Adds a new table called "Aaa". +``` + + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly named table is in the DataSet. +``` + + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . + + If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of and for a .NET Framework data provider retrieves schema information for only the first result. - +> When handling batch SQL statements that return multiple results, the implementation of and for a .NET Framework data provider retrieves schema information for only the first result. + ]]> The source table is invalid. - The parameter is less than 0. - - -or- - + The parameter is less than 0. + + -or- + The parameter is less than 0. This overload of the method is protected and is designed for use by a .NET Framework data provider. @@ -1743,54 +1743,54 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na Adds a named "Table" to the specified and configures the schema to match that in the data source based on the specified . A reference to a collection of objects that were added to the . - . - - A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: - -- - -- . You must set and separately. - -- - -- - -- - - also configures the and properties according to the following rules: - -- If one or more primary key columns are returned by the , they are used as the primary key columns for the . - -- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. - -- If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the . - - Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. - - If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). - - Primary key information is used during to find and replace any rows whose key columns match. If this is not the desired behavior, use without requesting schema information. - - If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - The object associated with the select command must be valid, but it does not need to open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it is left open. - + . + + A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: + +- + +- . You must set and separately. + +- + +- + +- + + also configures the and properties according to the following rules: + +- If one or more primary key columns are returned by the , they are used as the primary key columns for the . + +- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. + +- If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the . + + Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. + + If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). + + Primary key information is used during to find and replace any rows whose key columns match. If this is not the desired behavior, use without requesting schema information. + + If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + The object associated with the select command must be valid, but it does not need to open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it is left open. + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. + When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. 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). - - - -## Examples - The following example uses the derived class, , to fill a with the schema, and returns a . - + + + +## Examples + The following example uses the derived class, , to fill a with the schema, and returns a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.FillSchema1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/FillSchema/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/FillSchema/source.vb" id="Snippet1"::: + ]]> DbProviderFactories @@ -1856,54 +1856,54 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na Configures the schema of the specified based on the specified . A that contains schema information returned from the data source. - method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - - A operation returns a . It then adds columns to the of the , and configures the following properties if they exist at the data source: - -- - -- . You must set and separately. - -- - -- - -- - - also configures the and properties according to the following rules: - -- If a has already been defined for the `DataTable`, or the `DataTable` contains data, the `PrimaryKey` property will not be set. - -- If one or more primary key columns are returned by the , they are used as the primary key columns for the `DataTable`. - -- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the `PrimaryKey` property is not set. - -- If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the `DataTable`. - - Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. This process may require several round-trips to the server. - - If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). - - If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - does not return any rows. Use the method to add rows to a . - + method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + + A operation returns a . It then adds columns to the of the , and configures the following properties if they exist at the data source: + +- + +- . You must set and separately. + +- + +- + +- + + also configures the and properties according to the following rules: + +- If a has already been defined for the `DataTable`, or the `DataTable` contains data, the `PrimaryKey` property will not be set. + +- If one or more primary key columns are returned by the , they are used as the primary key columns for the `DataTable`. + +- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the `PrimaryKey` property is not set. + +- If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the `DataTable`. + + Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. This process may require several round-trips to the server. + + If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). + + If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + does not return any rows. Use the method to add rows to a . + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. + When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. 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). - - - -## Examples - The following example uses the derived class, , to fill a with the schema, and returns a . - + + + +## Examples + The following example uses the derived class, , to fill a with the schema, and returns a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.FillSchema3/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/FillSchema/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/FillSchema/source2.vb" id="Snippet1"::: + ]]> DbProviderFactories @@ -1964,72 +1964,72 @@ adapter.Fill(dataset, "AAA"); // Fills table "aaa" because only one similarly na Adds a to the specified and configures the schema to match that in the data source based upon the specified and . A reference to a collection of objects that were added to the . - . - - A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: - -- - -- . You must set and separately. - -- - -- - -- - - also configures the and properties according to the following rules: - -- If one or more primary key columns are returned by the , they are used as the primary key columns for the . - -- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. - -- If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the . - - Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. - - If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). - - Primary key information is used during to find and replace any rows whose key columns match. If this is not the desired behavior, use without requesting schema information. - - If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -dataset.Tables.Add("AAA"); -adapter.FillSchema(dataset, "aaa"); // Fills the schema of "aaa", which already exists in the DataSet. -adapter.FillSchema(dataset, "Aaa"); // Adds a new table called "Aaa". -``` - - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because only one similarly named table is in the DataSet. -``` - - The object associated with the select command must be valid, but it does not need to open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it is left open. - + . + + A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: + +- + +- . You must set and separately. + +- + +- + +- + + also configures the and properties according to the following rules: + +- If one or more primary key columns are returned by the , they are used as the primary key columns for the . + +- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. + +- If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the . + + Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. + + If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). + + Primary key information is used during to find and replace any rows whose key columns match. If this is not the desired behavior, use without requesting schema information. + + If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +dataset.Tables.Add("AAA"); +adapter.FillSchema(dataset, "aaa"); // Fills the schema of "aaa", which already exists in the DataSet. +adapter.FillSchema(dataset, "Aaa"); // Adds a new table called "Aaa". +``` + + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because only one similarly named table is in the DataSet. +``` + + The object associated with the select command must be valid, but it does not need to open. If the is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it is left open. + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. + When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. 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). - - - -## Examples - The following example uses the derived class, , to fill a with the schema, and returns a . - + + + +## Examples + The following example uses the derived class, , to fill a with the schema, and returns a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.FillSchema2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/FillSchema/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/FillSchema/source1.vb" id="Snippet1"::: + ]]> A source table from which to get the schema could not be found. @@ -2100,44 +2100,44 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Configures the schema of the specified based on the specified , command string, and values. A of object that contains schema information returned from the data source. - method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - - A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: - -- - -- . You must set and separately. - -- - -- - -- - - also configures the and properties according to the following rules: - -- If one or more primary key columns are returned by the , they are used as the primary key columns for the . - -- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. - -- If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the . - - Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. - - If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). - - If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - does not return any rows. Use the method to add rows to a . - + method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + + A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: + +- + +- . You must set and separately. + +- + +- + +- + + also configures the and properties according to the following rules: + +- If one or more primary key columns are returned by the , they are used as the primary key columns for the . + +- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. + +- If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the . + + Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. + + If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). + + If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + does not return any rows. Use the method to add rows to a . + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. + When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. 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). - + ]]> @@ -2205,62 +2205,62 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Adds a to the specified and configures the schema to match that in the data source based on the specified . An array of objects that contain schema information returned from the data source. - method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - - A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: - -- - -- . You must set and separately. - -- - -- - -- - - also configures the and properties according to the following rules: - -- If one or more primary key columns are returned by the , they are used as the primary key columns for the . - -- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. - -- If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the . - - Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. - - If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). - - If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. - - The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -dataset.Tables.Add("AAA"); -adapter.FillSchema(dataset, "aaa"); // Fills the schema of "aaa", which already exists in the DataSet. -adapter.FillSchema(dataset, "Aaa"); // Adds a new table called "Aaa". -``` - - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); -dataset.Tables.Add("aaa"); -adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because only one similarly named table is in the DataSet. -``` - - does not return any rows. Use the method to add rows to a . - + method retrieves the schema from the data source using the . The connection object associated with the must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + + A operation adds a to the destination . It then adds columns to the of the , and configures the following properties if they exist at the data source: + +- + +- . You must set and separately. + +- + +- + +- + + also configures the and properties according to the following rules: + +- If one or more primary key columns are returned by the , they are used as the primary key columns for the . + +- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if, and only if, all the unique columns are nonnullable. If any of the columns are nullable, a is added to the , but the property is not set. + +- If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the . + + Note that primary keys and unique constraints are added to the according to the preceding rules, but other constraint types are not added. + + If a unique clustered index is defined on a column or columns in a SQL Server table and the primary key constraint is defined on a separate set of columns, then the names of the columns in the clustered index will be returned. To return the name or names of the primary key columns, use a query hint with the SELECT statement that specifies the name of the primary key index. For more information about specifying query hints, see [Hints (Transact-SQL) - Query](/sql/t-sql/queries/hints-transact-sql-query). + + If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). If your app uses column and table names, ensure there are no conflicts with these naming patterns. + + The method supports scenarios where the contains multiple objects whose names differ only by case. In such situations, performs a case-sensitive comparison to find the corresponding table, and creates a new table if no exact match exists. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +dataset.Tables.Add("AAA"); +adapter.FillSchema(dataset, "aaa"); // Fills the schema of "aaa", which already exists in the DataSet. +adapter.FillSchema(dataset, "Aaa"); // Adds a new table called "Aaa". +``` + + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); +dataset.Tables.Add("aaa"); +adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because only one similarly named table is in the DataSet. +``` + + does not return any rows. Use the method to add rows to a . + > [!NOTE] -> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. - +> When handling batch SQL statements that return multiple results, the implementation of for the .NET Framework Data Provider for OLE DB retrieves schema information for only the first result. To retrieve schema information for multiple results, use with the set to `AddWithKey`. + When using , the .NET Framework Data Provider for SQL Server appends a FOR BROWSE clause to the statement being executed. 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). - + ]]> @@ -2315,17 +2315,17 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Returns a from one of the commands in the current batch. The specified. - , this method throws . Classes that inherit from override this method to provide support for batches. - + , this method throws . Classes that inherit from override this method to provide support for batches. + ]]> The adapter does not support batches. - This method is protected and is designed for use by a .NET Framework data provider. - + This method is protected and is designed for use by a .NET Framework data provider. + If a class that inherits from supports batches, that class overrides this method to allow users to execute a batch. An implementation uses the provided to locate the requested command, then uses the provided to locate the requested parameter. For example, a of 0 and a of 0 returns the first parameter from the first command in the batch. DbProviderFactories (ADO.NET) @@ -2380,11 +2380,11 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Returns information about an individual update attempt within a larger batched update. Information about an individual update attempt within a larger batched update. - class. `GetBatchedRecordsAffected` represents one of those virtual methods. The `DbDataAdapter` class relies on `GetBatchedRecordsAffected` to determine the success or failure of individual update attempts within a batch so it can mark each corresponding accordingly. - + class. `GetBatchedRecordsAffected` represents one of those virtual methods. The `DbDataAdapter` class relies on `GetBatchedRecordsAffected` to determine the success or failure of individual update attempts within a batch so it can mark each corresponding accordingly. + ]]> ADO.NET Overview @@ -2482,17 +2482,17 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Initializes batching for the . - , this method throws . Classes that inherit from override this method to provide support for batches. - + , this method throws . Classes that inherit from override this method to provide support for batches. + ]]> The adapter does not support batches. - This method is protected and is designed for use by a .NET Framework data provider. - + This method is protected and is designed for use by a .NET Framework data provider. + If a class that inherits from supports batches, that class overrides this method. This method gives the class the opportunity to initialize any resources necessary to support batching. For example, a class may allocate a data structure to hold the set of commands in the batch. DbProviderFactories (ADO.NET) @@ -2553,19 +2553,19 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Gets or sets a command used to insert new records into the data source. A used during to insert records in the data source for new rows in the data set. - , if this property is not set and primary key information is present in the , the will be automatically generated. - - - -## Examples - The following example creates the derived class and sets some of its properties. - + , if this property is not set and primary key information is present in the , the will be automatically generated. + + + +## Examples + The following example creates the derived class and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.InsertCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/InsertCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/InsertCommand/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -2650,11 +2650,11 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o A that contains the event data. Raises the event of a .NET data provider. - @@ -2711,11 +2711,11 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o An that contains the event data. Raises the event of a .NET data provider. - @@ -2779,14 +2779,14 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Gets or sets a command used to select records in the data source. A that is used during to select records from data source for placement in the data set. - and sets some of its properties. - + and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.SelectCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/SelectCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/SelectCommand/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) @@ -2843,13 +2843,13 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Gets or sets an SQL statement for deleting records from the data set. An used during to delete records in the data source for deleted rows in the data set. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -2904,13 +2904,13 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Gets or sets an SQL statement used to insert new records into the data source. An used during to insert records in the data source for new rows in the data set. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -2965,13 +2965,13 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Gets or sets an SQL statement used to select records in the data source. An that is used during to select records from data source for placement in the data set. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -3026,13 +3026,13 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Gets or sets an SQL statement used to update records in the data source. An used during to update records in the data source for modified rows in the data set. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -3088,13 +3088,13 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Creates a new object that is a copy of the current instance. A new object that is a copy of this instance. - instance is cast to an interface. - - For more information, see . - + instance is cast to an interface. + + For more information, see . + ]]> ADO.NET Overview @@ -3139,17 +3139,17 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Ends batching for the . - , this method throws . Classes that inherit from override this method to provide support for batches. - + , this method throws . Classes that inherit from override this method to provide support for batches. + ]]> The adapter does not support batches. - This method is protected and is designed for use by a .NET Framework data provider. - + This method is protected and is designed for use by a .NET Framework data provider. + If a class that inherits from supports batches, that class overrides this method. This method gives the class the opportunity to dispose of any resources allocated to support batching. For example, the class may deallocate the data structure that holds the commands in the batch. DbProviderFactories (ADO.NET) @@ -3217,72 +3217,72 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Updates the values in the database by executing the respective INSERT, UPDATE, or DELETE statements for each inserted, updated, or deleted row in the specified array in the . The number of rows successfully updated from the . - method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - - When using , the order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. - - `SourceColumn` refers to the unmapped column name before any table mappings have been applied. If `SourceColumn` refers to a nonexistent column, the action taken depends on one of the following values. - -|Enumeration value|Action taken| -|-----------------------|------------------| -|`MissingMappingAction.Passthrough`|Use the source column names and table names in the if no mapping is present.| -|`MissingMappingAction.Ignore`|A is generated. When the mappings are explicitly set, a missing mapping for an input parameter is usually the result of an error.| -|`MissingMappingAction.Error`|A is generated.| - - The `SourceColumn` property is also used to map the value for output or input/output parameters back to the `DataSet`. An exception is generated if it refers to a nonexistent column. - - The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. - + method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + + When using , the order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. + + `SourceColumn` refers to the unmapped column name before any table mappings have been applied. If `SourceColumn` refers to a nonexistent column, the action taken depends on one of the following values. + +|Enumeration value|Action taken| +|-----------------------|------------------| +|`MissingMappingAction.Passthrough`|Use the source column names and table names in the if no mapping is present.| +|`MissingMappingAction.Ignore`|A is generated. When the mappings are explicitly set, a missing mapping for an input parameter is usually the result of an error.| +|`MissingMappingAction.Error`|A is generated.| + + The `SourceColumn` property is also used to map the value for output or input/output parameters back to the `DataSet`. An exception is generated if it refers to a nonexistent column. + + The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. + > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . - - - -## Examples - The following example uses the derived class, , to update the data source. - +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . + + + +## Examples + The following example uses the derived class, , to update the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.Update1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Update/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Update/source1.vb" id="Snippet1"::: + ]]> The is invalid. The source table is invalid. - No exists to update. - - -or- - - No exists to update. - - -or- - + No exists to update. + + -or- + + No exists to update. + + -or- + No exists to use as a source. An attempt to execute an INSERT, UPDATE, or DELETE statement resulted in zero records affected. Manipulating Data (ADO.NET) @@ -3343,60 +3343,60 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Updates the values in the database by executing the respective INSERT, UPDATE, or DELETE statements for each inserted, updated, or deleted row in the specified . The number of rows successfully updated from the . - method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - - When using , the order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, then the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. - - `SourceColumn` refers to the unmapped column name before any table mappings have been applied. If `SourceColumn` refers to a nonexistent column, the action taken depends on one of the following values. - -|Enumeration value|Action taken| -|-----------------------|------------------| -|`MissingMappingAction.Passthrough`|Use the source column names and table names in the if no mapping is present.| -|`MissingMappingAction.Ignore`|A is generated. When the mappings are explicitly set, a missing mapping for an input parameter is usually the result of an error.| -|`MissingMappingAction.Error`|A is generated.| - - The `SourceColumn` property is also used to map the value for output or input/output parameters back to the `DataSet`. An exception is generated if it refers to a nonexistent column. - - The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. - + method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + + When using , the order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, then the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. + + `SourceColumn` refers to the unmapped column name before any table mappings have been applied. If `SourceColumn` refers to a nonexistent column, the action taken depends on one of the following values. + +|Enumeration value|Action taken| +|-----------------------|------------------| +|`MissingMappingAction.Passthrough`|Use the source column names and table names in the if no mapping is present.| +|`MissingMappingAction.Ignore`|A is generated. When the mappings are explicitly set, a missing mapping for an input parameter is usually the result of an error.| +|`MissingMappingAction.Error`|A is generated.| + + The `SourceColumn` property is also used to map the value for output or input/output parameters back to the `DataSet`. An exception is generated if it refers to a nonexistent column. + + The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. + > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . - - - -## Examples - The following example uses the derived class, , to update the data source. - +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . + + + +## Examples + The following example uses the derived class, , to update the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.Update Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Update/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Update/source.vb" id="Snippet1"::: + ]]> The source table is invalid. @@ -3456,72 +3456,72 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Updates the values in the database by executing the respective INSERT, UPDATE, or DELETE statements for each inserted, updated, or deleted row in the specified . The number of rows successfully updated from the . - method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - - When using , the order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, then the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. - - `SourceColumn` refers to the unmapped column name before any table mappings have been applied. If `SourceColumn` refers to a nonexistent column, the action taken depends on one of the following values. - -|Enumeration value|Action taken| -|-----------------------|------------------| -|`MissingMappingAction.Passthrough`|Use the source column names and table names in the if no mapping is present.| -|`MissingMappingAction.Ignore`|A is generated. When the mappings are explicitly set, a missing mapping for an input parameter is usually the result of an error.| -|`MissingMappingAction.Error`|A is generated.| - - The `SourceColumn` property is also used to map the value for output or input/output parameters back to the `DataSet`. An exception is generated if it refers to a nonexistent column. - - The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. - + method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + + When using , the order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, then the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. + + `SourceColumn` refers to the unmapped column name before any table mappings have been applied. If `SourceColumn` refers to a nonexistent column, the action taken depends on one of the following values. + +|Enumeration value|Action taken| +|-----------------------|------------------| +|`MissingMappingAction.Passthrough`|Use the source column names and table names in the if no mapping is present.| +|`MissingMappingAction.Ignore`|A is generated. When the mappings are explicitly set, a missing mapping for an input parameter is usually the result of an error.| +|`MissingMappingAction.Error`|A is generated.| + + The `SourceColumn` property is also used to map the value for output or input/output parameters back to the `DataSet`. An exception is generated if it refers to a nonexistent column. + + The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. + > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . - - - -## Examples - The following example uses the derived class, , to update the data source. - +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . + + + +## Examples + The following example uses the derived class, , to update the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.Update2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Update/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Update/source2.vb" id="Snippet1"::: + ]]> The is invalid. The source table is invalid. - No exists to update. - - -or- - - No exists to update. - - -or- - + No exists to update. + + -or- + + No exists to update. + + -or- + No exists to use as a source. An attempt to execute an INSERT, UPDATE, or DELETE statement resulted in zero records affected. Manipulating Data (ADO.NET) @@ -3581,64 +3581,64 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Updates the values in the database by executing the respective INSERT, UPDATE, or DELETE statements for each inserted, updated, or deleted row in the specified array of objects. The number of rows successfully updated from the array of objects. - method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - - When using , the order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, then the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. - - `SourceColumn` refers to the unmapped column name before any table mappings have been applied. If `SourceColumn` refers to a nonexistent column, the action taken depends on one of the following values. - -|Enumeration value|Action taken| -|-----------------------|------------------| -|`MissingMappingAction.Passthrough`|Use the source column names and table names in the if no mapping is present.| -|`MissingMappingAction.Ignore`|A is generated. When the mappings are explicitly set, a missing mapping for an input parameter is usually the result of an error.| -|`MissingMappingAction.Error`|A is generated.| - - The `SourceColumn` property is also used to map the value for output or input/output parameters back to the `DataSet`. An exception is generated if it refers to a nonexistent column. - - The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. - + method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + + When using , the order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, then the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. + + `SourceColumn` refers to the unmapped column name before any table mappings have been applied. If `SourceColumn` refers to a nonexistent column, the action taken depends on one of the following values. + +|Enumeration value|Action taken| +|-----------------------|------------------| +|`MissingMappingAction.Passthrough`|Use the source column names and table names in the if no mapping is present.| +|`MissingMappingAction.Ignore`|A is generated. When the mappings are explicitly set, a missing mapping for an input parameter is usually the result of an error.| +|`MissingMappingAction.Error`|A is generated.| + + The `SourceColumn` property is also used to map the value for output or input/output parameters back to the `DataSet`. An exception is generated if it refers to a nonexistent column. + + The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. + > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . - +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . + ]]> The is invalid. The source table is invalid. - No exists to update. - - -or- - - No exists to update. - - -or- - + No exists to update. + + -or- + + No exists to update. + + -or- + No exists to use as a source. An attempt to execute an INSERT, UPDATE, or DELETE statement resulted in zero records affected. Manipulating Data (ADO.NET) @@ -3698,79 +3698,79 @@ adapter.FillSchema(dataset, "AAA"); // Fills the schema of table "aaa" because o Updates the values in the database by executing the respective INSERT, UPDATE, or DELETE statements for each inserted, updated, or deleted row in the with the specified name. The number of rows successfully updated from the . - method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . - - It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERT before UPDATE). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). - - If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - The method supports scenarios where the contains multiple objects whose names differ only by case. When multiple tables with the same name, but different case, exist in a `DataSet`, performs a case-sensitive comparison to find the corresponding table, and generates an exception if no exact match exists. The following C# code illustrates this behavior. - -``` -DataSet ds = new DataSet(); - ds.Tables.Add("aaa"); - ds.Tables.Add("AAA"); - adapter.Update(ds, "aaa"); // Updates "aaa", which already exists in the DataSet. - adapter.Update(ds, "AAA"); // Updates "AAA", which already exists in the DataSet. - adapter.Update(ds, "Aaa"); // Results in an exception. -``` - - If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. - -``` -DataSet dataset = new DataSet(); - dataset.Tables.Add("aaa"); - adapter.Update(dataset, "AAA"); // Updates table "aaa" because only one similarly named table is in the DataSet. -``` - - The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. - - After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. - - When using , the order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, then the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. - - `SourceColumn` refers to the unmapped column name before any table mappings have been applied. If `SourceColumn` refers to a nonexistent column, the action taken depends on one of the following values. - -|Enumeration value|Action taken| -|-----------------------|------------------| -|`MissingMappingAction.Passthrough`|Use the source column names and table names in the if no mapping is present.| -|`MissingMappingAction.Ignore`|A is generated. When the mappings are explicitly set, a missing mapping for an input parameter is usually the result of an error.| -|`MissingMappingAction.Error`|A is generated.| - - The `SourceColumn` property is also used to map the value for output or input/output parameters back to the `DataSet`. An exception is generated if it refers to a nonexistent column. - - The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. - + method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, due to the ordering of the rows in the . + + It should be noted that these statements are not performed as a batch process; each row is updated individually. An application can call the method in situations where you must control the sequence of statement types (for example, INSERT before UPDATE). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + + If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the **CommandBuilder**. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + The method supports scenarios where the contains multiple objects whose names differ only by case. When multiple tables with the same name, but different case, exist in a `DataSet`, performs a case-sensitive comparison to find the corresponding table, and generates an exception if no exact match exists. The following C# code illustrates this behavior. + +``` +DataSet ds = new DataSet(); + ds.Tables.Add("aaa"); + ds.Tables.Add("AAA"); + adapter.Update(ds, "aaa"); // Updates "aaa", which already exists in the DataSet. + adapter.Update(ds, "AAA"); // Updates "AAA", which already exists in the DataSet. + adapter.Update(ds, "Aaa"); // Results in an exception. +``` + + If is called and the contains only one whose name differs only by case, that is updated. In this scenario, the comparison is case insensitive. The following C# code illustrates this behavior. + +``` +DataSet dataset = new DataSet(); + dataset.Tables.Add("aaa"); + adapter.Update(dataset, "AAA"); // Updates table "aaa" because only one similarly named table is in the DataSet. +``` + + The method retrieves rows from the table listed in the first mapping before performing an update. The then refreshes the row using the value of the property. Any additional rows returned are ignored. + + After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. + + When using , the order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, then the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + Each command associated with the usually has a parameters collection associated with it. Parameters are mapped to the current row through the `SourceColumn` and `SourceVersion` properties of a .NET Framework data provider's `Parameter` class. `SourceColumn` refers to a column that the references to obtain parameter values for the current row. + + `SourceColumn` refers to the unmapped column name before any table mappings have been applied. If `SourceColumn` refers to a nonexistent column, the action taken depends on one of the following values. + +|Enumeration value|Action taken| +|-----------------------|------------------| +|`MissingMappingAction.Passthrough`|Use the source column names and table names in the if no mapping is present.| +|`MissingMappingAction.Ignore`|A is generated. When the mappings are explicitly set, a missing mapping for an input parameter is usually the result of an error.| +|`MissingMappingAction.Error`|A is generated.| + + The `SourceColumn` property is also used to map the value for output or input/output parameters back to the `DataSet`. An exception is generated if it refers to a nonexistent column. + + The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the Original, Current, or Proposed version of the column value. This capability is often used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. + > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . - - - -## Examples - The following example uses the derived class, , to update the data source. - +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . + + + +## Examples + The following example uses the derived class, , to update the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.Update3/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Update/source3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/Update/source3.vb" id="Snippet1"::: + ]]> The is invalid. @@ -3824,37 +3824,37 @@ DataSet dataset = new DataSet(); Gets or sets a value that enables or disables batch processing support, and specifies the number of commands that can be executed in a batch. - The number of rows to process per batch. - - Value is - - Effect - - 0 - - There is no limit on the batch size. - - 1 - - Disables batch updating. - - > 1 - - Changes are sent using batches of operations at a time. - - + The number of rows to process per batch. + + Value is + + Effect + + 0 + + There is no limit on the batch size. + + 1 + + Disables batch updating. + + > 1 + + Changes are sent using batches of operations at a time. + + When setting this to a value other than 1, all the commands associated with the must have their property set to **None** or **OutputParameters**. An exception will be thrown otherwise. - property to update a data source with changes from a . If the data provider supports batch processing, this can increase application performance by reducing the number of round-trips to the server. In ADO.NET 2.0, this property is supported for the .NET data providers for SQL Server (SqlClient) and Oracle (OracleClient). - - Executing an extremely large batch could decrease performance. Therefore, you should test for the optimum batch size setting before implementing your application. - - An will be thrown if the value is set to a number less than zero. - + property to update a data source with changes from a . If the data provider supports batch processing, this can increase application performance by reducing the number of round-trips to the server. In ADO.NET 2.0, this property is supported for the .NET data providers for SQL Server (SqlClient) and Oracle (OracleClient). + + Executing an extremely large batch could decrease performance. Therefore, you should test for the optimum batch size setting before implementing your application. + + An will be thrown if the value is set to a number less than zero. + ]]> Manipulating Data (ADO.NET) @@ -3916,19 +3916,19 @@ DataSet dataset = new DataSet(); Gets or sets a command used to update records in the data source. A used during to update records in the data source for modified rows in the data set. - , if this property is not set and primary key information is present in the , the will be automatically generated. - - - -## Examples - The following example creates the derived class and sets some of its properties. - + , if this property is not set and primary key information is present in the , the will be automatically generated. + + + +## Examples + The following example creates the derived class and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.UpdateCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Common/DbDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: + ]]> Manipulating Data (ADO.NET) diff --git a/xml/System.Data.Common/DbParameter.xml b/xml/System.Data.Common/DbParameter.xml index 4b4e46004a1..9db12d34045 100644 --- a/xml/System.Data.Common/DbParameter.xml +++ b/xml/System.Data.Common/DbParameter.xml @@ -546,9 +546,9 @@ property is used for binary and string types. + The property is used for binary and string types. - For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. + For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first one hundred characters. @@ -622,7 +622,7 @@ ## Remarks When is set to anything other than an empty string, the value of the parameter is retrieved from the column with the name. If is set to `Input`, the value is taken from the . If is set to `Output`, the value is taken from the data source. A of `InputOutput` is a combination of both. - For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). ]]> @@ -989,9 +989,9 @@ This member is an explicit interface member implementation. It can be used only If the application specifies the database type, the bound value is converted to that type when the provider sends the data to the server. The provider tries to convert any type of value if it supports the interface. Conversion errors may result if the specified type is not compatible with the value. - The property can be inferred by setting the Value. + The property can be inferred by setting the Value. - The property is overwritten by `DbDataAdapter.Update`. + The property is overwritten by `DbDataAdapter.Update`. ]]> diff --git a/xml/System.Data.Common/DbProviderSpecificTypePropertyAttribute.xml b/xml/System.Data.Common/DbProviderSpecificTypePropertyAttribute.xml index 69dd0f92d4f..6b9f350770b 100644 --- a/xml/System.Data.Common/DbProviderSpecificTypePropertyAttribute.xml +++ b/xml/System.Data.Common/DbProviderSpecificTypePropertyAttribute.xml @@ -56,13 +56,13 @@ Identifies which provider-specific property in the strongly typed parameter classes is to be used when setting a provider-specific type. - is used by a provider writer to designate a provider-specific type parameter property which is not inherited from the base class. The property of a is an example of a provider-specific type property not found in `DbParameter`. - - A provider writer can apply `DbProviderSpecificTypePropertyAttribute(true)` to indicate a provider-specific data type parameter property. This allows for its discovery using reflection, which enables code generation tools, such as those used in Visual Studio, to generate code geared to a specific provider. The property returns `true` if the property has been set, otherwise `false`. - + is used by a provider writer to designate a provider-specific type parameter property which is not inherited from the base class. The property of a is an example of a provider-specific type property not found in `DbParameter`. + + A provider writer can apply `DbProviderSpecificTypePropertyAttribute(true)` to indicate a provider-specific data type parameter property. This allows for its discovery using reflection, which enables code generation tools, such as those used in Visual Studio, to generate code geared to a specific provider. The property returns `true` if the property has been set, otherwise `false`. + ]]> Extending Metadata Using Attributes diff --git a/xml/System.Data.Design/TypedDataSetGeneratorException.xml b/xml/System.Data.Design/TypedDataSetGeneratorException.xml index 26b983bb7a2..d0c162ed95f 100644 --- a/xml/System.Data.Design/TypedDataSetGeneratorException.xml +++ b/xml/System.Data.Design/TypedDataSetGeneratorException.xml @@ -23,11 +23,11 @@ The exception that is thrown when a name conflict occurs while a strongly typed is being generated. - class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. - + class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. + ]]> @@ -40,11 +40,11 @@ Initializes a new instance of the class. - class indicates that a conflict occurred an attempt is being made to generate a typed dataset class. - + class indicates that a conflict occurred an attempt is being made to generate a typed dataset class. + ]]> @@ -65,20 +65,20 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - - The class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + + The class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. + ]]> @@ -103,11 +103,11 @@ An of errors. Initializes a new instance of the class by passing in a collection of errors. - class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. - + class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. + ]]> @@ -132,18 +132,18 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - - The class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + + The class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. + ]]> @@ -170,11 +170,11 @@ A structure. Initializes a new instance of the class, using the specified serialization information and streaming context. - class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. - + class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. + ]]> @@ -201,20 +201,20 @@ 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 the specified string and inner 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| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - - The class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. - + 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| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + + The class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. + ]]> @@ -245,11 +245,11 @@ Gets a dynamic list of generated errors. The error list. - class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. - + class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. + ]]> @@ -279,11 +279,11 @@ A structure. Implements the interface and returns the data that you must have to serialize the object. - class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. - + class indicates that a conflict occurred while an attempt is being made to generate a typed dataset class. + ]]> diff --git a/xml/System.Data.EntityClient/EntityConnection.xml b/xml/System.Data.EntityClient/EntityConnection.xml index 5ae90d0fc23..4e6f7af2290 100644 --- a/xml/System.Data.EntityClient/EntityConnection.xml +++ b/xml/System.Data.EntityClient/EntityConnection.xml @@ -402,13 +402,13 @@ |`Metadata`|Required if the `Name` keyword is not specified. A pipe-delimited list of directories, files, and resource locations in which to look for model and mapping information. The following is an example:

`Metadata=`

`c:\model | c:\model\sql\mapping.msl;`

Blank spaces on each side of the pipe separator are ignored.

This keyword is mutually exclusive with the `Name` keyword.| |`Name`|The application can optionally specify the connection name in an application configuration file that provides the required keyword/value connection string values. In this case, you cannot supply them directly in the connection string. The `Name` keyword is not allowed in a configuration file.

When the `Name` keyword is not included in the connection string, a non-empty values for Provider keyword is required.

This keyword is mutually exclusive with all the other connection string keywords.| - The application can supply the keyword/values directly in the property, or it can specify a value for the `Name` keyword. If the `Name` keyword is specified, the connection string keyword/values are retrieved from an application configuration file, as follows: + The application can supply the keyword/values directly in the property, or it can specify a value for the `Name` keyword. If the `Name` keyword is specified, the connection string keyword/values are retrieved from an application configuration file, as follows: `Name=AdventureWorksEntities;` - If the `Name` keyword is used in the property, other keywords are not allowed. The `Name` keyword refers to a named connection string that is stored in the `connectionStrings` section in an application configuration file, as shown in the following example. The `Provider`, `Metadata`, and `Provider Connection String` values are retrieved from the configuration file at run time. + If the `Name` keyword is used in the property, other keywords are not allowed. The `Name` keyword refers to a named connection string that is stored in the `connectionStrings` section in an application configuration file, as shown in the following example. The `Provider`, `Metadata`, and `Provider Connection String` values are retrieved from the configuration file at run time. - The keyword/value pairs can also be supplied directly in the property, as shown in the following example. In this case, the `Name` keyword is not used. + The keyword/value pairs can also be supplied directly in the property, as shown in the following example. In this case, the `Name` keyword is not used. ```txt "Provider=System.Data.SqlClient; @@ -553,7 +553,7 @@ Provider Connection String= 'Data Source=localhost; property, see the documentation for the underlying data provider. For SQL Server equivalent keywords, see the documentation for the property. + For the specific keyword value, such as `Database`, that maps to the property, see the documentation for the underlying data provider. For SQL Server equivalent keywords, see the documentation for the property. ]]> @@ -583,7 +583,7 @@ Provider Connection String= 'Data Source=localhost; property, see the documentation for the underlying data provider. For SQL Server equivalent keywords, see the documentation for the property. + For the specific keyword value, such as `DataSource`, that maps to the property, see the documentation for the underlying data provider. For SQL Server equivalent keywords, see the documentation for the property. ]]> @@ -839,7 +839,7 @@ Provider Connection String= 'Data Source=localhost; ## Remarks If the object is closed, the returned data source connection will be closed. If it is open, an open data source connection will be returned. If the data source connection information was set, the returned value is always non-null. If there is no data source connection information (for example, if the parameterless constructor was used and no connection string was set afterwards), then a null reference is returned. - The same data source connection used by the Entity Framework can be shared with other parts of an application. The data source connection is returned as a object from the property of , or from the property of . + The same data source connection used by the Entity Framework can be shared with other parts of an application. The data source connection is returned as a object from the property of , or from the property of . ]]>
diff --git a/xml/System.Data.EntityClient/EntityConnectionStringBuilder.xml b/xml/System.Data.EntityClient/EntityConnectionStringBuilder.xml index fec11ab1fbc..747a7a5759b 100644 --- a/xml/System.Data.EntityClient/EntityConnectionStringBuilder.xml +++ b/xml/System.Data.EntityClient/EntityConnectionStringBuilder.xml @@ -25,7 +25,7 @@ The performs checks for valid keyword/value pairs, each of which is exposed as a property value. > [!NOTE] -> The connection string for the underlying data source is supplied by the property. The supplied provider connection string is not checked for valid keyword/value pairs. +> The connection string for the underlying data source is supplied by the property. The supplied provider connection string is not checked for valid keyword/value pairs. diff --git a/xml/System.Data.Linq.Mapping/ColumnAttribute.xml b/xml/System.Data.Linq.Mapping/ColumnAttribute.xml index 3961b243134..560e134b7c9 100644 --- a/xml/System.Data.Linq.Mapping/ColumnAttribute.xml +++ b/xml/System.Data.Linq.Mapping/ColumnAttribute.xml @@ -180,7 +180,7 @@ public class Employees If you set this value to `false`, the data in the corresponding column is assumed to be non-null. > [!NOTE] -> This property is duplicated from the property for convenience. The method uses only the property. For this reason, you must specify whether a column can contain null values in the property also. +> This property is duplicated from the property for convenience. The method uses only the property. For this reason, you must specify whether a column can contain null values in the property also. @@ -225,7 +225,7 @@ public class Employees property only if you plan to use to create an instance of the database. + Use this property to specify the exact text that defines the column in a Transact-SQL table declaration. Specify the property only if you plan to use to create an instance of the database. The default value of is inferred from the member type. For more information, see [SQL-CLR Type Mapping](/dotnet/framework/data/adonet/sql/linq/sql-clr-type-mapping). @@ -325,7 +325,7 @@ public class Employees members are synchronized immediately after the row of data is inserted, and the members are available after is completed. > [!NOTE] -> If the column holds primary key values and you designate as `true`, you should also add the property by using the `IDENTITY` modifier. +> If the column holds primary key values and you designate as `true`, you should also add the property by using the `IDENTITY` modifier. diff --git a/xml/System.Data.Linq.Mapping/DatabaseAttribute.xml b/xml/System.Data.Linq.Mapping/DatabaseAttribute.xml index b4c9ebde2ce..9efabe196b2 100644 --- a/xml/System.Data.Linq.Mapping/DatabaseAttribute.xml +++ b/xml/System.Data.Linq.Mapping/DatabaseAttribute.xml @@ -23,15 +23,15 @@ Specifies certain attributes of a class that represents a database. - attribute to any strongly typed declaration. - - The attribute is optional. If you use it, you must use the property to supply a name. - - If you do not apply this attribute and the connection does not specify a name, the database is assumed to have the same name as the class. - + attribute to any strongly typed declaration. + + The attribute is optional. If you use it, you must use the property to supply a name. + + If you do not apply this attribute and the connection does not specify a name, the database is assumed to have the same name as the class. + ]]> @@ -90,33 +90,33 @@ Gets or sets the name of the database. The name. - attribute. - - The information is used only if the connection itself does not specify the database name. - - - -## Examples - -```vb - _ -Public Class Database5 - Inherits DataContext - … -End Class -``` - -```csharp -[Database(Name="Database#5")] -public class Database5 : DataContext -{ - … -} -``` - + attribute. + + The information is used only if the connection itself does not specify the database name. + + + +## Examples + +```vb + _ +Public Class Database5 + Inherits DataContext + … +End Class +``` + +```csharp +[Database(Name="Database#5")] +public class Database5 : DataContext +{ + … +} +``` + ]]> diff --git a/xml/System.Data.Linq.Mapping/MetaDataMember.xml b/xml/System.Data.Linq.Mapping/MetaDataMember.xml index 5f230181444..49aaea21cd5 100644 --- a/xml/System.Data.Linq.Mapping/MetaDataMember.xml +++ b/xml/System.Data.Linq.Mapping/MetaDataMember.xml @@ -63,11 +63,11 @@ When overridden in a derived class, gets the that corresponds to this member. The corresponding if one exists; otherwise, . - @@ -115,11 +115,11 @@ if this member can be assigned the value; otherwise, . - property, and is provided for convenience. - + property, and is provided for convenience. + ]]> @@ -144,11 +144,11 @@ When overridden in a derived class, gets the type of the corresponding database column. The type of the database column as a string. - @@ -285,11 +285,11 @@ if this member is automatically generated by the database; otherwise, . - @@ -365,11 +365,11 @@ if this member represents the inheritance discriminator; otherwise, . - @@ -395,11 +395,11 @@ if this member is mapped to a column (or constraint); otherwise, . - @@ -425,13 +425,13 @@ if this member is part of the type's identity; otherwise, . - are not required to be the primary key. They simply denote a set that uniquely identifies the entity. Common alternatives include clustering index columns or other unique key columns. - + are not required to be the primary key. They simply denote a set that uniquely identifies the entity. Common alternatives include clustering index columns or other unique key columns. + ]]> @@ -457,11 +457,11 @@ if this member represents the row version or timestamp; otherwise, . - @@ -684,13 +684,13 @@ When overridden in a derived class, gets the optimistic concurrency check policy for this member. One of the enumeration values that indicates the optimistic concurrency check policy for this member. - set to `true`), detection is done by comparing original member values with the current database state. - - The property determines how LINQ to SQL implements conflict detection under optimistic concurrency. Only those members with this property set to or are considered during conflict detection. - + set to `true`), detection is done by comparing original member values with the current database state. + + The property determines how LINQ to SQL implements conflict detection under optimistic concurrency. Only those members with this property set to or are considered during conflict detection. + ]]> diff --git a/xml/System.Data.Linq/DataContext.xml b/xml/System.Data.Linq/DataContext.xml index 752bd4f6597..fa6b0105948 100644 --- a/xml/System.Data.Linq/DataContext.xml +++ b/xml/System.Data.Linq/DataContext.xml @@ -274,7 +274,7 @@ The name of the database is derived by using the following algorithm: 1. If a database is identified in the connection string, its name is used. -1. If a attribute is present, its property is used as the name of the database. +1. If a attribute is present, its property is used as the name of the database. 1. If there is no database tag in the connection string and a strongly typed is used, a database that has the same name as the inheriting class is created. 1. If a weakly typed is used, an exception is thrown. 1. If the has been created by using a file name, the database corresponding to that file name is created. @@ -365,7 +365,7 @@ property to attempt to open the associated database. + This method uses the connection in the property to attempt to open the associated database. @@ -403,7 +403,7 @@ property. + When the code accesses one of these relationships, null is returned if the relationship is one-to-one, and an empty collection is returned if it is one-to-many. The relationships can still be filled by setting the property. The main scenario for this property is to enable you to extract a piece of the object model and send it out (for example, to a Web service). @@ -448,7 +448,7 @@ property to identify the database to be deleted. + This method uses the connection in the property to identify the database to be deleted. diff --git a/xml/System.Data.Linq/ForeignKeyReferenceAlreadyHasValueException.xml b/xml/System.Data.Linq/ForeignKeyReferenceAlreadyHasValueException.xml index 4c7e336385b..59b78ee9852 100644 --- a/xml/System.Data.Linq/ForeignKeyReferenceAlreadyHasValueException.xml +++ b/xml/System.Data.Linq/ForeignKeyReferenceAlreadyHasValueException.xml @@ -50,18 +50,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply". This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply". This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -93,16 +93,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -136,18 +136,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 the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + 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| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions diff --git a/xml/System.Data.Linq/Link`1.xml b/xml/System.Data.Linq/Link`1.xml index e7ef71db030..528e2ee7974 100644 --- a/xml/System.Data.Linq/Link`1.xml +++ b/xml/System.Data.Linq/Link`1.xml @@ -21,11 +21,11 @@ The type of the elements in the deferred source. Used to enable deferred loading of individual properties (similar to ). - ) to , loads the value by enumerating the source the first time the property is accessed. - + ) to , loads the value by enumerating the source the first time the property is accessed. + ]]> @@ -61,11 +61,11 @@ The source collection. Initializes a new instance of the structure by referencing the source. - with a deferred value loader (implements ) - + with a deferred value loader (implements ) + ]]> @@ -112,11 +112,11 @@ The value for the property. Initializes a new instance of the structure by referencing the value of the property. - @@ -142,13 +142,13 @@ if the has either loaded or assigned a value; otherwise, . - has a value, so that accessing it will not trigger deferred loading. - + has a value, so that accessing it will not trigger deferred loading. + ]]> diff --git a/xml/System.Data.Metadata.Edm/MetadataProperty.xml b/xml/System.Data.Metadata.Edm/MetadataProperty.xml index 8768042a779..6091b8b59b9 100644 --- a/xml/System.Data.Metadata.Edm/MetadataProperty.xml +++ b/xml/System.Data.Metadata.Edm/MetadataProperty.xml @@ -17,11 +17,11 @@ Represents a metadata attribute for an item in the ADO.NET metadata hierarchy. - class provides properties called , , and so on. The class also inherits a property, which is a collection of objects. When the application creates an instance of the class, the property automatically contains a collection of objects for property, property, and so on. - + class provides properties called , , and so on. The class also inherits a property, which is a collection of objects. When the application creates an instance of the class, the property automatically contains a collection of objects for property, property, and so on. + ]]> diff --git a/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml b/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml index 1ae9ef31b82..2c6068d1de7 100644 --- a/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml +++ b/xml/System.Data.Objects.DataClasses/EntityCollection`1.xml @@ -432,7 +432,7 @@ property gets the number of entities currently in the local collection and does not reflect the size of the collection in the data source. A count of zero does not necessarily indicate that the related collection is empty. To determine the collection size in the data source, call the method or include the related object in the query path. For more information, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). + The property gets the number of entities currently in the local collection and does not reflect the size of the collection in the data source. A count of zero does not necessarily indicate that the related collection is empty. To determine the collection size in the data source, call the method or include the related object in the query path. For more information, see [Loading Related Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896272(v=vs.100)). ]]> diff --git a/xml/System.Data.Objects.DataClasses/EntityObject.xml b/xml/System.Data.Objects.DataClasses/EntityObject.xml index 5d334716364..91686b1fcff 100644 --- a/xml/System.Data.Objects.DataClasses/EntityObject.xml +++ b/xml/System.Data.Objects.DataClasses/EntityObject.xml @@ -98,9 +98,9 @@ property to manage objects in the object context. + Object Services uses the property to manage objects in the object context. - You cannot set the property after an object is attached to an . + You cannot set the property after an object is attached to an . ]]> diff --git a/xml/System.Data.Objects.DataClasses/EntityReference`1.xml b/xml/System.Data.Objects.DataClasses/EntityReference`1.xml index 0468e381b26..0a7d463f984 100644 --- a/xml/System.Data.Objects.DataClasses/EntityReference`1.xml +++ b/xml/System.Data.Objects.DataClasses/EntityReference`1.xml @@ -104,7 +104,7 @@ method is used to define a relationship between an object and a related object when both objects are already attached to an object context. Set the related object to the property if the related object is not already attached to the object context. When both objects are detached, you can also define the relationship by setting the related object to the property and then attaching the root object in the object graph. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). + The method is used to define a relationship between an object and a related object when both objects are already attached to an object context. Set the related object to the property if the related object is not already attached to the object context. When both objects are detached, you can also define the relationship by setting the related object to the property and then attaching the root object in the object graph. For more information, see [Attaching and Detaching Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738470(v=vs.100)). The object associated with this and all objects being attached to it must be in an or state. @@ -180,7 +180,7 @@ ## Remarks This method is used to load the related object. - When loaded, the related object is accessed from the property. + When loaded, the related object is accessed from the property. To explicitly load related objects, you must call the `Load` method on the related end returned by the navigation property. For a one-to-many relationship, call the method on , and for a one-to-one relationship, call the on . This loads the related object data into the object context. When a query returns results, you can enumerate through the collection of objects using a `foreach` loop (`For Each...Next` in Visual Basic) and conditionally call the `Load` method on and properties for each entity in the results. diff --git a/xml/System.Data.Objects.DataClasses/IEntityWithKey.xml b/xml/System.Data.Objects.DataClasses/IEntityWithKey.xml index d7b05dacf30..017ab6a206c 100644 --- a/xml/System.Data.Objects.DataClasses/IEntityWithKey.xml +++ b/xml/System.Data.Objects.DataClasses/IEntityWithKey.xml @@ -19,7 +19,7 @@ ## Remarks This interface is used to expose the entity key to Object Services. - Object Services uses the property to manage objects in the object context. + Object Services uses the property to manage objects in the object context. For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)) and [Tracking Changes in POCO Entities](https://msdn.microsoft.com/library/52d2fc77-5c87-4082-a8e2-a2952ceb8461). @@ -50,7 +50,7 @@ property to manage objects in the object context. + Object Services uses the property to manage objects in the object context. For more information, see [Identity Resolution, State Management, and Change Tracking](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896269(v=vs.100)) and [Tracking Changes in POCO Entities](https://msdn.microsoft.com/library/52d2fc77-5c87-4082-a8e2-a2952ceb8461). diff --git a/xml/System.Data.Objects.DataClasses/IRelatedEnd.xml b/xml/System.Data.Objects.DataClasses/IRelatedEnd.xml index 7728a5a0ae7..4dcaca8486c 100644 --- a/xml/System.Data.Objects.DataClasses/IRelatedEnd.xml +++ b/xml/System.Data.Objects.DataClasses/IRelatedEnd.xml @@ -70,7 +70,7 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti The class explicitly implements the method. The class uses this implementation. For more information, see . - If the related end is an and the property of the reference is not `null`, this method throws an exception. + If the related end is an and the property of the reference is not `null`, this method throws an exception. ]]> @@ -107,7 +107,7 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti The class explicitly implements the method. The class uses this implementation. For more information, see . - If the related end is an and the property of the reference is not `null`, this method throws an exception. + If the related end is an and the property of the reference is not `null`, this method throws an exception. ]]> @@ -526,7 +526,7 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti class implements the property. For more information, see . + The class implements the property. For more information, see . The role name is specified by the `Role` attribute of the `End` element in the association that defines this relationship in the conceptual model. For more information, see [Association Element (CSDL)](https://msdn.microsoft.com/library/c305169a-8af7-432f-9ba7-800a163aed41). @@ -557,7 +557,7 @@ The following example adds new `SalesOrderHeader` entities to the `Contact` enti class implements the property. For more information, see . + The class implements the property. For more information, see . The role name is specified by the `Role` attribute of the `End` element in the association that defines this relationship in the conceptual model. For more information, see [Association Element (CSDL)](https://msdn.microsoft.com/library/c305169a-8af7-432f-9ba7-800a163aed41). diff --git a/xml/System.Data.Objects/ObjectContext.xml b/xml/System.Data.Objects/ObjectContext.xml index a7b7d4e48c8..3daadf26cd6 100644 --- a/xml/System.Data.Objects/ObjectContext.xml +++ b/xml/System.Data.Objects/ObjectContext.xml @@ -261,7 +261,7 @@ - Call the method on the and specify the related object. Do this for a one-to-many or many-to-many relationship. -- Set the property of the to the related object. Do this for a one-to-one or many-to-one relationship. +- Set the property of the to the related object. Do this for a one-to-one or many-to-one relationship. For more information, see [Creating, Adding, Modifying, and Deleting Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738695(v=vs.100)). @@ -269,7 +269,7 @@ The rules for the `entitySetName` format are as follows: -- If the property is `null`, then the `entitySetName` has to be fully qualified as in *\*.*\*. +- If the property is `null`, then the `entitySetName` has to be fully qualified as in *\*.*\*. - If is not `null`, then the `entitySetName` can be either *\*.*\* or *\*. @@ -465,7 +465,7 @@ The original object must exist in the and must be in the or state. The original object is only modified if there are modified properties in the `changed` object. - The property of the supplied object must be set to a valid . + The property of the supplied object must be set to a valid . does not affect navigation properties or related objects. @@ -580,7 +580,7 @@ The rules for the `entitySetName` format are as follows: -- If the property is `null`, then the `entitySetName` has to be fully qualified as in *\*.*\*. +- If the property is `null`, then the `entitySetName` has to be fully qualified as in *\*.*\*. - If the is not `null`, then the `entitySetName` can be either *\*.*\* or *\*. @@ -653,7 +653,7 @@ operation is defined by the underlying connection provider. However, you can override this default timeout value by using the property on . Do this when you have a complex query or when other performance issues cause queries or calls to to time out frequently. + The default timeout for object queries and the operation is defined by the underlying connection provider. However, you can override this default timeout value by using the property on . Do this when you have a complex query or when other performance issues cause queries or calls to to time out frequently. ## Examples [Object queries](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896241(v=vs.100)) @@ -1850,7 +1850,7 @@ This example constructs an with a specific ProductI or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> @@ -1887,7 +1887,7 @@ This example constructs an with a specific ProductI After calling , the related object can be accessed through the navigation properties of the source entity. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . When the method is called, objects are loaded into the by using the default value of . @@ -1933,7 +1933,7 @@ This example constructs an with a specific ProductI After calling , the related object can be accessed through the navigation properties of the source entity. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> @@ -1981,7 +1981,7 @@ This example constructs an with a specific ProductI The property to load is specified by a LINQ expression, which must be in the form of a simple property member access, as in `(entity) => entity.PropertyName`, where *PropertyName* is the navigation property that returns the related objects to be loaded. An exception will occur if other forms of the LINQ expression are used. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> @@ -2035,7 +2035,7 @@ This example constructs an with a specific ProductI The property to load is specified by a LINQ expression, which must be in the form of a simple property member access, as in `(entity) => entity.PropertyName` where *PropertyName* is the navigation property that returns the related objects to be loaded. An exception will occur if other forms of the LINQ expression are used. - When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . + When using POCO custom data classes, related objects cannot be explicitly loaded like instances of entity types that are generated by the Entity Data Model tools. This is because the tools generate the navigation properties that return an or of related objects when is called on a . POCO entities can still be loaded by using lazy loading by setting the property to `true` on the instance of that is returned by the property, or by using eager loading with the method on the . ]]> diff --git a/xml/System.Data.Objects/ObjectParameter.xml b/xml/System.Data.Objects/ObjectParameter.xml index 25c88775ebe..fd798a12c48 100644 --- a/xml/System.Data.Objects/ObjectParameter.xml +++ b/xml/System.Data.Objects/ObjectParameter.xml @@ -74,7 +74,7 @@ ## Remarks This constructor creates a parameter from the specified name and value. The type of the parameter is inferred from the value. - When added to the , the parameter name cannot be changed. The parameter value can be changed through the property. After the query has been compiled, the value cannot be changed. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). + When added to the , the parameter name cannot be changed. The parameter value can be changed through the property. After the query has been compiled, the value cannot be changed. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). @@ -115,7 +115,7 @@ property. After the query has been compiled, the value cannot be changed. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). + When instantiated, the parameter name cannot be changed. The parameter value can be set or changed through the property. After the query has been compiled, the value cannot be changed. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). ]]> @@ -152,7 +152,7 @@ property. After the query has been compiled, the value cannot be changed. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). + When instantiated, the parameter name cannot be changed. The parameter value can be set or changed through the property. After the query has been compiled, the value cannot be changed. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). diff --git a/xml/System.Data.Objects/ObjectParameterCollection.xml b/xml/System.Data.Objects/ObjectParameterCollection.xml index 1a6411a577d..90482098eee 100644 --- a/xml/System.Data.Objects/ObjectParameterCollection.xml +++ b/xml/System.Data.Objects/ObjectParameterCollection.xml @@ -37,7 +37,7 @@ This class cannot be inherited. - The parameters that are passed to query builder methods are aggregated by successive instances of an in the sequence. They can be accessed by using the property, which returns the . After parameters have been added, they can be removed from the collection and the collection can be cleared, as long as the query has not been compiled or executed. Parameter names cannot be changed, but values can be changed at any time. + The parameters that are passed to query builder methods are aggregated by successive instances of an in the sequence. They can be accessed by using the property, which returns the . After parameters have been added, they can be removed from the collection and the collection can be cleared, as long as the query has not been compiled or executed. Parameter names cannot be changed, but values can be changed at any time. Parameters must be unique in the . There cannot be two parameters in the collection with the same name. diff --git a/xml/System.Data.Objects/ObjectQuery.xml b/xml/System.Data.Objects/ObjectQuery.xml index 999e8173e64..7c1f0cc55f2 100644 --- a/xml/System.Data.Objects/ObjectQuery.xml +++ b/xml/System.Data.Objects/ObjectQuery.xml @@ -302,7 +302,7 @@ executes the query with the merge option that is specified by the property. + Calling executes the query with the merge option that is specified by the property. The `foreach` statement of the C# language (`For Each` in Visual Basic) hides the complexity of the enumerators. Therefore, using `foreach` is recommended, instead of directly manipulating the enumerator. diff --git a/xml/System.Data.Objects/ObjectQuery`1.xml b/xml/System.Data.Objects/ObjectQuery`1.xml index 1f81b9792e2..f07c6eeedef 100644 --- a/xml/System.Data.Objects/ObjectQuery`1.xml +++ b/xml/System.Data.Objects/ObjectQuery`1.xml @@ -484,9 +484,9 @@ This example creates a new object tha ## Remarks The name of the object query identifies the current object query in the sequence by name when constructing query builder methods. By default, the query name is `it`. This can be useful when referring to the current sequence in joins inside the method or in the method. For more information, see [Query Builder Methods](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb896238(v=vs.100)). - When you set the property of an , that value becomes the alias in successive methods. + When you set the property of an , that value becomes the alias in successive methods. - The value of the property must start with a letter and can contain letters, digits, and underscores. + The value of the property must start with a letter and can contain letters, digits, and underscores. ## Examples diff --git a/xml/System.Data.Objects/ObjectStateManager.xml b/xml/System.Data.Objects/ObjectStateManager.xml index 4b6a165ce5c..5ed8d057aa7 100644 --- a/xml/System.Data.Objects/ObjectStateManager.xml +++ b/xml/System.Data.Objects/ObjectStateManager.xml @@ -632,7 +632,7 @@ The following example attempts to retrieve the corresponding method is used to obtain the for objects that are persistence ignorant. When objects implement or inherit from , the is accessed from the property. + The method is used to obtain the for objects that are persistence ignorant. When objects implement or inherit from , the is accessed from the property. The cannot be returned when the object is in a state. diff --git a/xml/System.Data.Odbc/OdbcCommand.xml b/xml/System.Data.Odbc/OdbcCommand.xml index 26a98c38284..4a34a6f34ab 100644 --- a/xml/System.Data.Odbc/OdbcCommand.xml +++ b/xml/System.Data.Odbc/OdbcCommand.xml @@ -89,7 +89,7 @@ ||Executes commands such as SQL INSERT, DELETE, UPDATE, and SET statements.| ||Retrieves a single value, for example, an aggregate value, from a database.| - You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. + You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. If execution of the command causes a fatal such as a SQL Server severity level of 20 or more, may close. However, the user can reopen the connection and continue. @@ -372,7 +372,7 @@ property is set to `StoredProcedure`, the property should be set using standard ODBC stored procedure escape sequences. Setting the to the name of the stored procedure does not function as it does for other .NET Framework data providers. + When the property is set to `StoredProcedure`, the property should be set using standard ODBC stored procedure escape sequences. Setting the to the name of the stored procedure does not function as it does for other .NET Framework data providers. Many language features, such as outer joins and scalar function calls, are generally implemented by data sources. Even the syntax for these features is generally data source-specific. Therefore, ODBC defines escape sequences that contain standard syntax for the following language features: @@ -420,7 +420,7 @@ SELECT * FROM Customers WHERE CustomerID = ? {1, null, 2} ``` - passed into the property: + passed into the property: ``` {call sp(?, ?, ?)} @@ -432,7 +432,7 @@ SELECT * FROM Customers WHERE CustomerID = ? {1, 2} ``` - and set the property to the following: + and set the property to the following: ``` {call sp(?, null, ?)} @@ -540,7 +540,7 @@ SELECT * FROM Customers WHERE CustomerID = ? property is set to `StoredProcedure`, you should set the property to the full ODBC call syntax. The command then executes this stored procedure when you call one of the Execute methods (for example, or ). + When the property is set to `StoredProcedure`, you should set the property to the full ODBC call syntax. The command then executes this stored procedure when you call one of the Execute methods (for example, or ). The , and properties cannot be set if the current connection is performing an execute or fetch operation. @@ -612,7 +612,7 @@ SELECT * FROM Customers WHERE CustomerID = ? ## Remarks You cannot set the , , and properties if the current connection is performing an execute or fetch operation. - If you set while a transaction is in progress and the property is not null, an is generated. If you set after the transaction has been committed or rolled back, and the property is not null, the property is then set to a null value. + If you set while a transaction is in progress and the property is not null, an is generated. If you set after the transaction has been committed or rolled back, and the property is not null, the property is then set to a null value. ]]> @@ -980,7 +980,7 @@ SELECT * FROM Customers WHERE CustomerID = ? property to the full ODBC call syntax for stored procedures. The command executes this stored procedure when you call . + You should set the property to the full ODBC call syntax for stored procedures. The command executes this stored procedure when you call . While the is used, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until the method of the is called. @@ -1024,7 +1024,7 @@ SELECT * FROM Customers WHERE CustomerID = ? ## Remarks If you expect your SQL statement to return only a single row, specifying `SingleRow` as the value may improve application performance. - You should set the property to the full ODBC call syntax for stored procedures. The command executes this stored procedure when you call . + You should set the property to the full ODBC call syntax for stored procedures. The command executes this stored procedure when you call . The supports a special mode that enables large binary values to be read efficiently. For more information, see the `SequentialAccess` setting for . @@ -1176,7 +1176,7 @@ SELECT * FROM Customers WHERE CustomerID = ? ## Remarks The method calls the ODBC `SQLPrepare` function. Depending on the capabilities of the underlying ODBC driver and data source, parameter information such as data types may be checked when the statement is prepared, if all parameters have been bound, or when it is executed if not all parameters have been bound. For maximum interoperability, an application should unbind all parameters that applied to a previous SQL statement before preparing a new SQL statement on the same . This prevents errors that are caused by previous parameter information being applied to the new SQL statement. - If you call an Execute method after you call , any parameter value that is larger than the value specified by the property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. + If you call an Execute method after you call , any parameter value that is larger than the value specified by the property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type, you must also specify the maximum . @@ -1401,7 +1401,7 @@ This member is an explicit interface member implementation. It can be used only property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to an object that is not connected to the same as the object, an exception will be thrown the next time that you try to execute a statement. + You cannot set the property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to an object that is not connected to the same as the object, an exception will be thrown the next time that you try to execute a statement. ]]> @@ -1449,7 +1449,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks The default value is **Both** unless the command is automatically generated, as with the , in which case the default is **None**. - For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). + For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). ]]> diff --git a/xml/System.Data.Odbc/OdbcCommandBuilder.xml b/xml/System.Data.Odbc/OdbcCommandBuilder.xml index 177be39e81f..6e5d4619494 100644 --- a/xml/System.Data.Odbc/OdbcCommandBuilder.xml +++ b/xml/System.Data.Odbc/OdbcCommandBuilder.xml @@ -45,16 +45,16 @@ does not automatically generate the SQL statements required to reconcile changes made to a associated with the data source. However, you can create an object that generates SQL statements for single-table updates by setting the property of the . The then generates any additional SQL statements that you do not set. + The does not automatically generate the SQL statements required to reconcile changes made to a associated with the data source. However, you can create an object that generates SQL statements for single-table updates by setting the property of the . The then generates any additional SQL statements that you do not set. The relationship between an and its corresponding is always one-to-one. To create this correspondence, you set the property of the object. This causes the to register itself as a listener, which produces the output of events that affect the . - To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata. If you change the value of after the metadata has been retrieved, such as after the first update, you should then call the method to update the metadata. + To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata. If you change the value of after the metadata has been retrieved, such as after the first update, you should then call the method to update the metadata. > [!NOTE] -> If the SELECT statement assigned to the property uses aliased column names, the resulting INSERT, UPDATE, and DELETE statements may be inaccurate or fail. If the underlying ODBC driver cannot provide the appropriate base column name for the alias column name (using the SQL_DESC_BASE_COLUMN_NAME value of `SQLColAttribute`), the alias name could be used in the generated INSERT, UPDATE, and DELETE statements. For example, the Microsoft ODBC Driver for Oracle returns the alias name as the base column name. Therefore, the generated INSERT, UPDATE, and DELETE statements would cause errors. +> If the SELECT statement assigned to the property uses aliased column names, the resulting INSERT, UPDATE, and DELETE statements may be inaccurate or fail. If the underlying ODBC driver cannot provide the appropriate base column name for the alias column name (using the SQL_DESC_BASE_COLUMN_NAME value of `SQLColAttribute`), the alias name could be used in the generated INSERT, UPDATE, and DELETE statements. For example, the Microsoft ODBC Driver for Oracle returns the alias name as the base column name. Therefore, the generated INSERT, UPDATE, and DELETE statements would cause errors. - The also uses the , , and properties referenced by the . The user should call if one or more of these properties are modified, or if the value of the property itself is changed. Otherwise the , , and properties retain their previous values. + The also uses the , , and properties referenced by the . The user should call if one or more of these properties are modified, or if the value of the property itself is changed. Otherwise the , , and properties retain their previous values. If you call , the is disassociated from the , and the generated commands are no longer used. diff --git a/xml/System.Data.Odbc/OdbcConnection.xml b/xml/System.Data.Odbc/OdbcConnection.xml index 93cf6db0513..0bdfd7dd1dc 100644 --- a/xml/System.Data.Odbc/OdbcConnection.xml +++ b/xml/System.Data.Odbc/OdbcConnection.xml @@ -77,7 +77,7 @@ ## Examples - The following example creates an and an . The is opened and set as the property. The example then calls , and closes the connection. To accomplish this, the is passed a connection string and a query string that is an SQL INSERT statement. + The following example creates an and an . The is opened and set as the property. The example then calls , and closes the connection. To accomplish this, the is passed a connection string and a query string that is an SQL INSERT statement. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcConnection/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnection/Overview/source.vb" id="Snippet1"::: @@ -121,7 +121,7 @@ is created, the write-only and read-only properties are set to the following initial values unless they are specifically set using their associated keywords in the property. + When a new instance of is created, the write-only and read-only properties are set to the following initial values unless they are specifically set using their associated keywords in the property. |Properties|Initial value| |----------------|-------------------| @@ -129,7 +129,7 @@ ||15| ||empty string ("")| - You can change the value for these properties only by using the property. + You can change the value for these properties only by using the property. @@ -173,7 +173,7 @@ is created, the write-only and read-only properties are set to the following initial values unless they are specifically set using their associated keywords in the property. + When a new instance of is created, the write-only and read-only properties are set to the following initial values unless they are specifically set using their associated keywords in the property. |Properties|Initial value| |----------------|-------------------| @@ -181,7 +181,7 @@ ||15| ||empty string ("")| - You can change the value for these properties only by using the property. + You can change the value for these properties only by using the property. @@ -518,9 +518,9 @@ property is designed to match ODBC connection string format as closely as possible. The can be set only when the connection is closed, and as soon as it is set it is passed, unchanged, to the Driver Manager and the underlying driver. Therefore, the syntax for the must exactly match what the Driver Manager and underlying driver support. + The property is designed to match ODBC connection string format as closely as possible. The can be set only when the connection is closed, and as soon as it is set it is passed, unchanged, to the Driver Manager and the underlying driver. Therefore, the syntax for the must exactly match what the Driver Manager and underlying driver support. - You can use the property to connect to a variety of data sources. This includes an ODBC data source name (DSN). The following example illustrates several possible connection strings. + You can use the property to connect to a variety of data sources. This includes an ODBC data source name (DSN). The following example illustrates several possible connection strings. ```txt "Driver={SQL Server};Server=(local);Trusted_Connection=Yes;Database=AdventureWorks;" @@ -537,11 +537,11 @@ ``` > [!NOTE] -> The .NET Framework Data Provider for ODBC does not support the `Persist Security Info` keyword that is supported by other .NET Framework data providers. However, the property behaves as if `Persist Security Info` were set to `false`. This means that you cannot retrieve the password from the property if the connection has been opened. When the property is read from an object that has been opened, the connection string is returned minus the password. You cannot change this behavior; therefore, if the application requires the password, store it separately before calling . +> The .NET Framework Data Provider for ODBC does not support the `Persist Security Info` keyword that is supported by other .NET Framework data providers. However, the property behaves as if `Persist Security Info` were set to `false`. This means that you cannot retrieve the password from the property if the connection has been opened. When the property is read from an object that has been opened, the connection string is returned minus the password. You cannot change this behavior; therefore, if the application requires the password, store it separately before calling . - Many of the settings specified in the string have corresponding read-only properties (for example, `Server=(local)`, which corresponds to the property). These properties are updated after the connection is opened, except when an error is detected. In this case, none of the properties are updated. properties (such as ) return only default settings or those settings specified in the . + Many of the settings specified in the string have corresponding read-only properties (for example, `Server=(local)`, which corresponds to the property). These properties are updated after the connection is opened, except when an error is detected. In this case, none of the properties are updated. properties (such as ) return only default settings or those settings specified in the . -Some basic validation of the connection string occurs as soon as you set the property. At that time, the data provider verifies that the connection string meets the "keyword=value;..." format, but it does not verify whether keywords or values are valid. The remaining verification is performed by the underlying ODBC driver when the application calls the method. +Some basic validation of the connection string occurs as soon as you set the property. At that time, the data provider verifies that the connection string meets the "keyword=value;..." format, but it does not verify whether keywords or values are valid. The remaining verification is performed by the underlying ODBC driver when the application calls the method. An ODBC connection string has the following syntax: @@ -613,7 +613,7 @@ driver-defined-attribute-keyword ::= identifier property before calling . This is equivalent to setting the ODBC `SQLSetConnectAttr` SQL_ATTR_LOGIN_TIMOUT attribute. + Unlike the .NET Framework data providers for SQL Server and OLE DB, the .NET Framework Data Provider for ODBC does not support setting this property as a connection string value, because it is not a valid ODBC connection keyword. To specify a connection time-out, set the property before calling . This is equivalent to setting the ODBC `SQLSetConnectAttr` SQL_ATTR_LOGIN_TIMOUT attribute. ]]> @@ -718,9 +718,9 @@ driver-defined-attribute-keyword ::= identifier property is set in the connection string. The property can be updated by using the method. If you change the current database using an SQL statement or the method, an informational message is sent and then the property is updated. + At first, the property is set in the connection string. The property can be updated by using the method. If you change the current database using an SQL statement or the method, an informational message is sent and then the property is updated. - Retrieving the property is equivalent to calling the ODBC function `SQLGetInfo` with the `Attribute` parameter set to SQL_ATTR_CURRENT_CATALOG. + Retrieving the property is equivalent to calling the ODBC function `SQLGetInfo` with the `Attribute` parameter set to SQL_ATTR_CURRENT_CATALOG. @@ -776,7 +776,7 @@ driver-defined-attribute-keyword ::= identifier property is equivalent to calling the ODBC function `SQLGetInfo` with the `InfoType` parameter set to SQL_SERVER_NAME. + Retrieving the property is equivalent to calling the ODBC function `SQLGetInfo` with the `InfoType` parameter set to SQL_SERVER_NAME. @@ -859,7 +859,7 @@ driver-defined-attribute-keyword ::= identifier property is equivalent to calling the ODBC function `SQLGetInfo` with the `InfoType` parameter set to SQL_DRIVER_NAME. + Retrieving the property is equivalent to calling the ODBC function `SQLGetInfo` with the `InfoType` parameter set to SQL_DRIVER_NAME. ]]> @@ -1255,7 +1255,7 @@ driver-defined-attribute-keyword ::= identifier ## Remarks If is not supported by the underlying ODBC driver, an empty string ("") is returned. - The property takes the form '*##.##.####*,' where the first two digits are the major version, the next two digits are the minor version, and the last four digits are the release version. The driver must render the product version in this form but can also append the product-specific version as a string (for example, "04.01.0000 Rdb 4.1"). This string takes the form '*major.minor.build*' where *major* and *minor* are exactly two digits and *build* is exactly four digits. + The property takes the form '*##.##.####*,' where the first two digits are the major version, the next two digits are the minor version, and the last four digits are the release version. The driver must render the product version in this form but can also append the product-specific version as a string (for example, "04.01.0000 Rdb 4.1"). This string takes the form '*major.minor.build*' where *major* and *minor* are exactly two digits and *build* is exactly four digits. ]]> @@ -1314,7 +1314,7 @@ driver-defined-attribute-keyword ::= identifier - From `Open` to `Closed`, using either the or **Dispose** method. > [!NOTE] -> Calling the property on an open connection increases application overhead because each such call causes a SQL_ATTR_CONNECTION_DEAD call to the underlying ODBC driver to determine whether the connection is still valid. +> Calling the property on an open connection increases application overhead because each such call causes a SQL_ATTR_CONNECTION_DEAD call to the underlying ODBC driver to determine whether the connection is still valid. ]]> diff --git a/xml/System.Data.Odbc/OdbcConnectionStringBuilder.xml b/xml/System.Data.Odbc/OdbcConnectionStringBuilder.xml index 639df67a144..7167c36dead 100644 --- a/xml/System.Data.Odbc/OdbcConnectionStringBuilder.xml +++ b/xml/System.Data.Odbc/OdbcConnectionStringBuilder.xml @@ -55,12 +55,12 @@ |Key|Property|Comment|Default value| |---------|--------------|-------------|-------------------| -|Driver||Developers should not include the braces surrounding the driver name when they set the property. The instance adds braces as needed.|Empty string| +|Driver||Developers should not include the braces surrounding the driver name when they set the property. The instance adds braces as needed.|Empty string| |DSN|||Empty string| If any value (other than the value) within the connection string contains a semicolon (;), the surrounds the value with quotation marks in the connection string. In order to avoid this issue with the value that frequently contains a semicolon, the class always surrounds this value with braces. The ODBC specification indicates that driver values that contain semicolons must be surrounded with braces, and this class handles this for you. - The property handles attempts to insert malicious code. For example, the following code, using the default property (the indexer, in C#) correctly escapes the nested key/value pair. + The property handles attempts to insert malicious code. For example, the following code, using the default property (the indexer, in C#) correctly escapes the nested key/value pair. ```vb Dim builder As _ @@ -160,7 +160,7 @@ Driver={SQL Server};Server="MyServer;NewValue=Bad" property explicitly. The behavior is the same either way. +You can pass a connection string in the constructor, or you can set the property explicitly. The behavior is the same either way. ]]> @@ -196,7 +196,7 @@ You can pass a connection string in the constructor, or you can set the method removes all key/value pairs from the and resets the and properties to their default values. The method also sets the property to 0 and the property to an empty string. + The method removes all key/value pairs from the and resets the and properties to their default values. The method also sets the property to 0 and the property to an empty string. @@ -292,7 +292,7 @@ You can pass a connection string in the constructor, or you can set the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is `String.Empty`. This property corresponds to the "Driver" key within the connection string. + If the value passed in is null when you try to set the property, the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is `String.Empty`. This property corresponds to the "Driver" key within the connection string. ]]> @@ -337,7 +337,7 @@ You can pass a connection string in the constructor, or you can set the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is `String.Empty`. This property corresponds to the "Dsn" key within the connection string. + If the value passed in is null when you try to set the property, the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is `String.Empty`. This property corresponds to the "Dsn" key within the connection string. ]]> @@ -381,7 +381,7 @@ You can pass a connection string in the constructor, or you can set the and adds key/value pairs to its connection string, using the property. + The following code, in a console application, creates a new and adds key/value pairs to its connection string, using the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OdbcConnectionStringBuilder.Item/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcConnectionStringBuilder/Item/source.vb" id="Snippet1"::: @@ -423,7 +423,7 @@ You can pass a connection string in the constructor, or you can set the is the same order as the associated values in the returned by the property. +The order of the values in the is the same order as the associated values in the returned by the property. ]]> diff --git a/xml/System.Data.Odbc/OdbcDataAdapter.xml b/xml/System.Data.Odbc/OdbcDataAdapter.xml index 604a15e2a36..6e0d9bc8cf0 100644 --- a/xml/System.Data.Odbc/OdbcDataAdapter.xml +++ b/xml/System.Data.Odbc/OdbcDataAdapter.xml @@ -87,29 +87,29 @@ Represents a set of data commands and a connection to a data source that are used to fill the and update the data source. This class cannot be inherited. - serves as a bridge between a `DataSet` and data source for retrieving and saving data. The provides this bridge by using to load data from the data source into the , and using to send changes made in the back to the data source. - - When the fills a , it creates the required tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). - + serves as a bridge between a `DataSet` and data source for retrieving and saving data. The provides this bridge by using to load data from the data source into the , and using to send changes made in the back to the data source. + + When the fills a , it creates the required tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). + > [!NOTE] -> When you call the `Fill` method on a data source that does not have a primary key column, the tries to promote the unique constraint column to the primary key. In the process, the marks the unique constraint as not nullable. This behavior works unless there is a null value in the unique constraint column. If there is a null value, the `Fill` method fails with a constraint violation. To avoid this situation, do not allow null values in the unique constraint column. - +> When you call the `Fill` method on a data source that does not have a primary key column, the tries to promote the unique constraint column to the primary key. In the process, the marks the unique constraint as not nullable. This behavior works unless there is a null value in the unique constraint column. If there is a null value, the `Fill` method fails with a constraint violation. To avoid this situation, do not allow null values in the unique constraint column. + > [!NOTE] -> Due to the limitations of native ODBC drivers, only one is ever returned when you call . This is true even when executing SQL batch statements from which multiple objects would be expected. - - The also includes the , , , , and `TableMappings` properties to facilitate loading and updating of data. - - - -## Examples - The following example uses , , and to select records and populate a `DataSet` with the selected rows. - +> Due to the limitations of native ODBC drivers, only one is ever returned when you call . This is true even when executing SQL batch statements from which multiple objects would be expected. + + The also includes the , , , , and `TableMappings` properties to facilitate loading and updating of data. + + + +## Examples + The following example uses , , and to select records and populate a `DataSet` with the selected rows. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/Overview/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -146,26 +146,26 @@ Initializes a new instance of the class. - , the following write-only and read-only properties are set to their default values, as shown in the table. - -|Properties|Default value| -|----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| - - You can change the value of any of these properties through a separate call to the property. - - - -## Examples - The following example creates an and sets some of its properties. - + , the following write-only and read-only properties are set to their default values, as shown in the table. + +|Properties|Default value| +|----------------|-------------------| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| + + You can change the value of any of these properties through a separate call to the property. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.OdbcDataAdapter/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/.ctor/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/.ctor/source2.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -197,28 +197,28 @@ An that is an SQL SELECT statement or stored procedure, and is set as the property of the . Initializes a new instance of the class with the specified SQL SELECT statement. - constructor sets the property to the value specified in the `selectCommand` parameter. - - When you create an instance of , the following write-only and read-only properties are set to their default values, as shown in the table. - -|Properties|Initial value| -|----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| - - You can change the value of any of these properties through a separate call to the property. - - - -## Examples - The following example creates an and sets some of its properties. - + constructor sets the property to the value specified in the `selectCommand` parameter. + + When you create an instance of , the following write-only and read-only properties are set to their default values, as shown in the table. + +|Properties|Initial value| +|----------------|-------------------| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| + + You can change the value of any of these properties through a separate call to the property. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.OdbcDataAdapter1/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/.ctor/source3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/.ctor/source3.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -252,19 +252,19 @@ An that represents the connection. Initializes a new instance of the class with an SQL SELECT statement and an . - can be useful in an application that must call the `Fill` method for two or more objects. - - - -## Examples - The following example creates an and sets some of its properties. - + can be useful in an application that must call the `Fill` method for two or more objects. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.OdbcDataAdapter3/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/InsertCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/InsertCommand/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -298,19 +298,19 @@ The connection string. Initializes a new instance of the class with an SQL SELECT statement and a connection string. - constructor uses the `selectConnectionString` parameter to set the property. However, it does not open the connection. You still must explicitly open the connection. - - - -## Examples - The following example creates an and sets some of its properties. - + constructor uses the `selectConnectionString` parameter to set the property. However, it does not open the connection. You still must explicitly open the connection. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.OdbcDataAdapter2/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -450,21 +450,21 @@ Gets or sets an SQL statement or stored procedure used to delete records in the data source. An used during an update operation to delete records in the data source that correspond to deleted rows in the . - property is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created . - - During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate the , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - - -## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. - + property is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created . + + During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate the , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + + +## Examples + The following example creates an and sets the and properties. It assumes that you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.DeleteCommand/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/.ctor/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -541,24 +541,24 @@ Gets or sets an SQL statement or stored procedure used to insert new records into the data source. An used during an update operation to insert records in the data source that correspond to new rows in the . - property is assigned to a previously created object, the is not cloned. Instead, maintains a reference to the previously created . - - During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - + property is assigned to a previously created object, the is not cloned. Instead, maintains a reference to the previously created . + + During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + > [!NOTE] -> If execution of this command returns rows, these rows may be added to the depending upon how you set the property of the object. - - - -## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. - +> If execution of this command returns rows, these rows may be added to the depending upon how you set the property of the object. + + + +## Examples + The following example creates an and sets the and properties. It assumes that you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.InsertCommand/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/.ctor/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/.ctor/source1.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -649,25 +649,25 @@ Occurs during an update operation after a command is executed against the data source. - , there are two events that occur per data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - + , there are two events that occur per data row updated. The order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + ]]> DataAdapters and DataReaders @@ -698,25 +698,25 @@ Occurs during before a command is executed against the data source. - , there are two events that occur per data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - + , there are two events that occur per data row updated. The order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + ]]> DataAdapters and DataReaders @@ -766,21 +766,21 @@ Gets or sets an SQL statement or stored procedure used to select records in the data source. An that is used during a fill operation to select records from data source for placement in the . - is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. - - If returns no rows, no tables are added to the , and no exception is raised. - - - -## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. - + is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. + + If returns no rows, no tables are added to the , and no exception is raised. + + + +## Examples + The following example creates an and sets the and properties. It assumes that you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.SelectCommand/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/SelectCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/SelectCommand/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -814,11 +814,11 @@ For a description of this member, see . An used during an update to delete records in the data source for deleted rows in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -851,11 +851,11 @@ For a description of this member, see . An that is used during an update to insert records from a data source for placement in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -888,11 +888,11 @@ For a description of this member, see . An that is used during an update to select records from a data source for placement in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -925,11 +925,11 @@ For a description of this member, see . An used during an update to update records in the data source for modified rows in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -964,11 +964,11 @@ For a description of this member, see . A new that is a copy of this instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1017,24 +1017,24 @@ Gets or sets an SQL statement or stored procedure used to update records in the data source. An used during an update operation to update records in the data source that correspond to modified rows in the . - is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. - - During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - + is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. + + During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the data source. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + > [!NOTE] -> If execution of this command returns rows, these rows may be merged with the depending upon how you set the property of the object. - - - -## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. - +> If execution of this command returns rows, these rows may be merged with the depending upon how you set the property of the object. + + + +## Examples + The following example creates an and sets the and properties. It assumes that you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataAdapter.UpdateCommand/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data.Odbc/OdbcDataReader.xml b/xml/System.Data.Odbc/OdbcDataReader.xml index 20f5d753e14..202a8fee631 100644 --- a/xml/System.Data.Odbc/OdbcDataReader.xml +++ b/xml/System.Data.Odbc/OdbcDataReader.xml @@ -55,25 +55,25 @@ Provides a way of reading a forward-only stream of data rows from a data source. This class cannot be inherited. - , you must call the method of the object, instead of directly using a constructor. - - While the is being used, the associated is busy serving the , and no other operations can be performed on the other than closing it. This is the case until the method of the is called. For example, you cannot retrieve output parameters until after you call . - - Changes made to a result set by another process or thread while data is being read may be visible to the user of the . However, the precise behavior is both driver and timing dependent. - - and are the only properties that you can call after the is closed. Sometimes, you must call before you can call . - - - -## Examples - The following example creates an , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , and then the . - + , you must call the method of the object, instead of directly using a constructor. + + While the is being used, the associated is busy serving the , and no other operations can be performed on the other than closing it. This is the case until the method of the is called. For example, you cannot retrieve output parameters until after you call . + + Changes made to a result set by another process or thread while data is being read may be visible to the user of the . However, the precise behavior is both driver and timing dependent. + + and are the only properties that you can call after the is closed. Sometimes, you must call before you can call . + + + +## Examples + The following example creates an , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , and then the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataReader/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataReader/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataReader/Overview/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -112,22 +112,22 @@ Closes the object. - method when you are finished using the to use the associated for any other purpose. - + method when you are finished using the to use the associated for any other purpose. + > [!CAUTION] -> Do not call `Close` or `Dispose` on a Connection, a DataReader, or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). - - - -## Examples - The following example creates an , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , and then the . - +> Do not call `Close` or `Dispose` on a Connection, a DataReader, or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). + + + +## Examples + The following example creates an , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , and then the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDataReader.Read Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataReader/Read/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataReader/Read/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -164,11 +164,11 @@ Gets a value that indicates the depth of nesting for the current row. The depth of nesting for the current row. - DataAdapters and DataReaders @@ -234,13 +234,13 @@ Gets the number of columns in the current row. When not positioned in a valid record set, 0; otherwise the number of columns in the current record. The default is -1. - to exclude hidden fields. - - After you execute a query that does not return rows, returns 0. - + to exclude hidden fields. + + After you execute a query that does not return rows, returns 0. + ]]> There is no current connection to a data source. @@ -308,13 +308,13 @@ Gets the value of the specified column as a Boolean. A Boolean that is the value of the column. - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -358,13 +358,13 @@ Gets the value of the specified column as a byte. The value of the specified column as a byte. - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -417,18 +417,18 @@ Reads a stream of bytes from the specified column offset into the buffer as an array, starting at the particular buffer offset. The actual number of bytes read. - returns the number of available bytes in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if has already been used to obtain bytes from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . - - If you pass a buffer that is a null value, returns the length of the field in bytes. - - Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported then the method call will fail. - + returns the number of available bytes in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if has already been used to obtain bytes from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . + + If you pass a buffer that is a null value, returns the length of the field in bytes. + + Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported then the method call will fail. + > [!NOTE] -> No exception will be thrown if the value of `bufferIndex` is outside the array. No data will be read and the method will return 0. - +> No exception will be thrown if the value of `bufferIndex` is outside the array. No data will be read and the method will return 0. + ]]> DataAdapters and DataReaders @@ -471,13 +471,13 @@ Gets the value of the specified column as a character. The value of the specified column as a character. - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -530,18 +530,18 @@ Reads a stream of characters from the specified column offset into the buffer as an array, starting at the particular buffer offset. The actual number of characters read. - returns the number of available characters in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if has already been used to obtain characters from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . - - If you pass a buffer that is a null value, returns the length of the field in characters. - - Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported then the method call will fail. - + returns the number of available characters in the field. Most of the time this is the exact length of the field. However, the number returned may be less than the true length of the field if has already been used to obtain characters from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting for . + + If you pass a buffer that is a null value, returns the length of the field in characters. + + Conversions are performed based on the underlying capabilities of the ODBC driver. If the conversion is not supported then the method call will fail. + > [!NOTE] -> No exception will be thrown if the value of `bufferIndex` is outside the array. No data will be read and the method will return 0. - +> No exception will be thrown if the value of `bufferIndex` is outside the array. No data will be read and the method will return 0. + ]]> DataAdapters and DataReaders @@ -693,13 +693,13 @@ Gets the value of the specified column as a object. The value of the specified column as a object. - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -743,15 +743,15 @@ Gets the value of the specified column as a object. The value of the specified column as a object. - to look for null values before calling this method. - - has a maximum precision of 28. Attempting to retrieve decimal data with a larger precision will cause an exception. One solution would be to change the query to cast the decimal type to either a smaller datatype or convert to string or binary. - + to look for null values before calling this method. + + has a maximum precision of 28. Attempting to retrieve decimal data with a larger precision will cause an exception. One solution would be to change the query to cast the decimal type to either a smaller datatype or convert to string or binary. + ]]> The specified cast is not valid. @@ -795,13 +795,13 @@ Gets the value of the specified column as a double-precision floating-point number. The value of the specified column as a double-precision floating-point number. - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -833,11 +833,11 @@ Returns an that can be used to iterate through the rows in the data reader. An that can be used to iterate through the rows in the data reader. - DataAdapters and DataReaders @@ -920,13 +920,13 @@ Gets the value of the specified column as a single-precision floating-point number. The value of the specified column as a single-precision floating-point number. - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -970,13 +970,13 @@ Gets the value of the specified column as a globally unique identifier (GUID). The value of the specified column as a GUID. - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -1020,13 +1020,13 @@ Gets the value of the specified column as a 16-bit signed integer. The value of the specified column as a 16-bit signed integer. - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -1070,13 +1070,13 @@ Gets the value of the specified column as a 32-bit signed integer. The value of the specified column as a 32-bit signed integer. - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -1120,13 +1120,13 @@ Gets the value of the specified column as a 64-bit signed integer. The value of the specified column as a 64-bit signed integer. - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -1211,23 +1211,23 @@ Gets the column ordinal, given the name of the column. The zero-based column ordinal. - performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. The method throws an `IndexOutOfRange` exception if the zero-based column ordinal is not found. - - is kana-width insensitive. - - Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call within a loop. Instead, call one time and then assign the results to an integer variable for use within the loop. - - - -## Examples - The following example demonstrates how to use the method. - + performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. The method throws an `IndexOutOfRange` exception if the zero-based column ordinal is not found. + + is kana-width insensitive. + + Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call within a loop. Instead, call one time and then assign the results to an integer variable for use within the loop. + + + +## Examples + The following example demonstrates how to use the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcDataReader.GetOrdinal/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataRecord/GetOrdinal/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataRecord/GetOrdinal/source.vb" id="Snippet1"::: + ]]> @@ -1269,47 +1269,47 @@ Returns a that describes the column metadata of the . A that describes the column metadata. - method returns metadata about each column in the following order: - -|DataReader column|Description| -|-----------------------|-----------------| -|ColumnName|The name of the column; this might not be unique. If the column name cannot be determined, a null value is returned. This name always reflects the most recent naming of the column in the current view or command text.| -|ColumnOrdinal|The zero-based ordinal of the column. This column cannot contain a null value.| -|ColumnSize|The maximum possible length of a value in the column. For columns that use a fixed-length data type, this is the size of the data type.| -|NumericPrecision|If is a numeric data type, this is the maximum precision of the column. The precision depends on the definition of the column. If is not a numeric data type, do not use the data in this column. If the underlying ODBC driver returns a precision value for a non-numeric data type, this value is used in the schema table.| -|NumericScale|If is , the number of digits to the right of the decimal point. Otherwise, this is a null value. If the underlying ODBC driver returns a precision value for a non-numeric data type, this value is used in the schema table.| -|DataType|Maps to the common language runtime type of .| -|ProviderType|The underlying driver type.| -|IsLong|`true` if the column contains a Binary Long Object (BLOB) that contains very long data. The definition of very long data is driver-specific.| -|AllowDBNull|`true` if the consumer can set the column to a null value or if the driver cannot determine whether the consumer can set the column to a null value. Otherwise, `false`. A column may contain null values, even if it cannot be set to a null value.| -|IsReadOnly|`true` if the column cannot be modified; otherwise `false`.| -|IsRowVersion|Set if the column contains a persistent row identifier that cannot be written to, and has no meaningful value except to identity the row.| -|IsUnique|`true`: No two rows in the base table (the table returned in BaseTableName) can have the same value in this column. IsUnique is guaranteed to be `true` if the column represents a key by itself or if there is a constraint of type UNIQUE that applies only to this column.

`false`: The column can contain duplicate values in the base table. The default for this column is `false`.| -|IsKey|`true`: The column is one of a set of columns in the rowset that, taken together, uniquely identify the row. The set of columns with IsKey set to `true` must uniquely identify a row in the rowset. There is no requirement that this set of columns is a minimal set of columns. This set of columns may be generated from a base table primary key, a unique constraint, or a unique index.

`false`: The column is not required to uniquely identify the row.| -|IsAutoIncrement|`true` if the column assigns values to new rows in fixed increments; otherwise `false`. The default for this column is `false`.| -|BaseSchemaName|The name of the schema in the data source that contains the column. NULL if the base catalog name cannot be determined. The default for this column is a null value.| -|BaseCatalogName|The name of the catalog in the data store that contains the column. NULL if the base catalog name cannot be determined. The default for this column is a null value.| -|BaseTableName|The name of the table or view in the data store that contains the column. A null value if the base table name cannot be determined. The default of this column is a null value.| -|BaseColumnName|The name of the column in the data store. This might be different from the column name returned in the ColumnName column if an alias was used. A null value if the base column name cannot be determined or if the rowset column is derived, but not identical to, a column in the data store. The default for this column is a null value.| - - A row is returned for every column in the results set. - - The .NET Framework Data Provider for ODBC assumes that metadata information is available from an ODBC driver after one of **SQLPrepare**, **SQLExecute**, or **SQLExecuteDirect** functions are called. For "SchemaOnly" command behavior to work correctly, **SQLPrepare** must return the required metadata information. Not all ODBC drivers support this function or return metadata information. In these cases, part or all of the information in the SchemaTable will be missing. After calling **SQLPrepare**, The data provider calls the ODBC **SQLColAttribute** function to find the metadata information related to each column in the query results (for example, IsLong, IsUnique, AllowDBNull, BaseTableName, BaseColumnName). If the underlying driver does not return some of this information, the corresponding values in the SchemaTable will not be set correctly. - - The .NET Framework Data Provider for ODBC also calls **SQLPrimaryKeys** to retrieve the key information for every table. If the underlying ODBC driver does not support this function, the data provider calls **SQLStatistics** and chooses one of the unique indexes as the primary key for the table. This may not always give the results that you want. - - needs the correct identification of the primary keys of the table in order to work correctly. If the BaseTableName is not returned for every column in the query results, the .NET Framework Data Provider for ODBC tries to parse the SQL statement to find the table names involved in the query. This works with UPDATE, INSERT, DELETE and simple SELECT statements, but not with stored procedures or SELECT statements based on joins. If some or all the schema information is missing from this table, the will not work correctly, because it has insufficient schema information to automatically generate the correct INSERT, UPDATE, or DELETE statements. - - To make sure that metadata columns return the correct information, you must call with the behavior parameter set to KeyInfo. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. - - When you use ODBC.NET to Oracle via the ODBC driver, aliased key columns are not recognized as keys. This affects the IsKey and IsUnique columns in the schema table of the OdbcDataReader. It also affects the OdbcCommandBuilder's ability to generate updating logic. Consider not using an alias for a primary key column. - + method returns metadata about each column in the following order: + +|DataReader column|Description| +|-----------------------|-----------------| +|ColumnName|The name of the column; this might not be unique. If the column name cannot be determined, a null value is returned. This name always reflects the most recent naming of the column in the current view or command text.| +|ColumnOrdinal|The zero-based ordinal of the column. This column cannot contain a null value.| +|ColumnSize|The maximum possible length of a value in the column. For columns that use a fixed-length data type, this is the size of the data type.| +|NumericPrecision|If is a numeric data type, this is the maximum precision of the column. The precision depends on the definition of the column. If is not a numeric data type, do not use the data in this column. If the underlying ODBC driver returns a precision value for a non-numeric data type, this value is used in the schema table.| +|NumericScale|If is , the number of digits to the right of the decimal point. Otherwise, this is a null value. If the underlying ODBC driver returns a precision value for a non-numeric data type, this value is used in the schema table.| +|DataType|Maps to the common language runtime type of .| +|ProviderType|The underlying driver type.| +|IsLong|`true` if the column contains a Binary Long Object (BLOB) that contains very long data. The definition of very long data is driver-specific.| +|AllowDBNull|`true` if the consumer can set the column to a null value or if the driver cannot determine whether the consumer can set the column to a null value. Otherwise, `false`. A column may contain null values, even if it cannot be set to a null value.| +|IsReadOnly|`true` if the column cannot be modified; otherwise `false`.| +|IsRowVersion|Set if the column contains a persistent row identifier that cannot be written to, and has no meaningful value except to identity the row.| +|IsUnique|`true`: No two rows in the base table (the table returned in BaseTableName) can have the same value in this column. IsUnique is guaranteed to be `true` if the column represents a key by itself or if there is a constraint of type UNIQUE that applies only to this column.

`false`: The column can contain duplicate values in the base table. The default for this column is `false`.| +|IsKey|`true`: The column is one of a set of columns in the rowset that, taken together, uniquely identify the row. The set of columns with IsKey set to `true` must uniquely identify a row in the rowset. There is no requirement that this set of columns is a minimal set of columns. This set of columns may be generated from a base table primary key, a unique constraint, or a unique index.

`false`: The column is not required to uniquely identify the row.| +|IsAutoIncrement|`true` if the column assigns values to new rows in fixed increments; otherwise `false`. The default for this column is `false`.| +|BaseSchemaName|The name of the schema in the data source that contains the column. NULL if the base catalog name cannot be determined. The default for this column is a null value.| +|BaseCatalogName|The name of the catalog in the data store that contains the column. NULL if the base catalog name cannot be determined. The default for this column is a null value.| +|BaseTableName|The name of the table or view in the data store that contains the column. A null value if the base table name cannot be determined. The default of this column is a null value.| +|BaseColumnName|The name of the column in the data store. This might be different from the column name returned in the ColumnName column if an alias was used. A null value if the base column name cannot be determined or if the rowset column is derived, but not identical to, a column in the data store. The default for this column is a null value.| + + A row is returned for every column in the results set. + + The .NET Framework Data Provider for ODBC assumes that metadata information is available from an ODBC driver after one of **SQLPrepare**, **SQLExecute**, or **SQLExecuteDirect** functions are called. For "SchemaOnly" command behavior to work correctly, **SQLPrepare** must return the required metadata information. Not all ODBC drivers support this function or return metadata information. In these cases, part or all of the information in the SchemaTable will be missing. After calling **SQLPrepare**, The data provider calls the ODBC **SQLColAttribute** function to find the metadata information related to each column in the query results (for example, IsLong, IsUnique, AllowDBNull, BaseTableName, BaseColumnName). If the underlying driver does not return some of this information, the corresponding values in the SchemaTable will not be set correctly. + + The .NET Framework Data Provider for ODBC also calls **SQLPrimaryKeys** to retrieve the key information for every table. If the underlying ODBC driver does not support this function, the data provider calls **SQLStatistics** and chooses one of the unique indexes as the primary key for the table. This may not always give the results that you want. + + needs the correct identification of the primary keys of the table in order to work correctly. If the BaseTableName is not returned for every column in the query results, the .NET Framework Data Provider for ODBC tries to parse the SQL statement to find the table names involved in the query. This works with UPDATE, INSERT, DELETE and simple SELECT statements, but not with stored procedures or SELECT statements based on joins. If some or all the schema information is missing from this table, the will not work correctly, because it has insufficient schema information to automatically generate the correct INSERT, UPDATE, or DELETE statements. + + To make sure that metadata columns return the correct information, you must call with the behavior parameter set to KeyInfo. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. + + When you use ODBC.NET to Oracle via the ODBC driver, aliased key columns are not recognized as keys. This affects the IsKey and IsUnique columns in the schema table of the OdbcDataReader. It also affects the OdbcCommandBuilder's ability to generate updating logic. Consider not using an alias for a primary key column. + > [!NOTE] -> The Microsoft Jet ODBC driver always returns unique index and primary key columns as nullable regardless of whether they are nullable or not. The driver also does not return primary key information; it only returns a list of unique indexes and their columns, including primary key columns, without differentiating among them. - +> The Microsoft Jet ODBC driver always returns unique index and primary key columns as nullable regardless of whether they are nullable or not. The driver also does not return primary key information; it only returns a list of unique indexes and their columns, including primary key columns, without differentiating among them. + ]]>
The is closed. @@ -1353,13 +1353,13 @@ Gets the value of the specified column as a . The value of the specified column as a . - to look for null values before calling this method. - + to look for null values before calling this method. + ]]> The specified cast is not valid. @@ -1435,11 +1435,11 @@ Gets the value of the column at the specified ordinal in its native format. The value to return. - for null database columns. - + for null database columns. + ]]> DataAdapters and DataReaders @@ -1482,21 +1482,21 @@ Populates an array of objects with the column values of the current row. The number of instances of in the array. - method provides an efficient means for retrieving all columns, instead of retrieving each column individually. - - You can pass an array that contains fewer than the number of columns that are contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns that are contained in the resulting row. - - This method returns for null database columns. - - - -## Examples + method provides an efficient means for retrieving all columns, instead of retrieving each column individually. + + You can pass an array that contains fewer than the number of columns that are contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns that are contained in the resulting row. + + This method returns for null database columns. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/odbcdatareader_getvalues/cs/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataReader/GetValues/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcDataReader/GetValues/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -1566,11 +1566,11 @@ if the is closed; otherwise . - and are the only properties that you can call after the is closed. - + and are the only properties that you can call after the is closed. + ]]> DataAdapters and DataReaders @@ -1614,11 +1614,11 @@ if the specified column value is equivalent to ; otherwise . - , , and so on). - + , , and so on). + ]]> DataAdapters and DataReaders @@ -1708,13 +1708,13 @@ Gets the value of the specified column in its native format given the column name. The value of the specified column in its native format. - No column with the specified name was found. @@ -1756,13 +1756,13 @@ if there are more result sets; otherwise . - is positioned on the first result. - + is positioned on the first result. + ]]> DataAdapters and DataReaders @@ -1803,21 +1803,21 @@ if there are more rows; otherwise . - is before the first record. Therefore, you must call to start accessing any data. - - While the is being used, the associated is busy serving it until you call . - - - -## Examples - The following example creates an , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , and then the . - + is before the first record. Therefore, you must call to start accessing any data. + + While the is being used, the associated is busy serving it until you call . + + + +## Examples + The following example creates an , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , and then the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDataReader.Read Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataReader/Read/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataReader/Read/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -1854,15 +1854,15 @@ Gets the number of rows changed, inserted, or deleted by execution of the SQL statement. The number of rows changed, inserted, or deleted. -1 for SELECT statements; 0 if no rows were affected, or the statement failed. - property is not set until all rows are read and you close the . - - The value of this property is cumulative. For example, if two records are inserted in batch mode, the value of will be 2. - - and are the only properties that you can call after the is closed. - + property is not set until all rows are read and you close the . + + The value of this property is cumulative. For example, if two records are inserted in batch mode, the value of will be 2. + + and are the only properties that you can call after the is closed. + ]]> DataAdapters and DataReaders diff --git a/xml/System.Data.Odbc/OdbcException.xml b/xml/System.Data.Odbc/OdbcException.xml index 1d2484355f5..a1943c05e5b 100644 --- a/xml/System.Data.Odbc/OdbcException.xml +++ b/xml/System.Data.Odbc/OdbcException.xml @@ -49,23 +49,23 @@ The exception that is generated when a warning or error is returned by an ODBC data source. This class cannot be inherited. - encounters an error generated by the server (Client-side errors are raised as standard common language runtime exceptions.). It always contains at least one instance of . - - If the severity of the error is too great, the server may close the . However, the user can reopen the connection and continue. - - For general information about handling exceptions for a .NET Framework data provider, see . - - - -## Examples - The following example generates an because of a missing data source, and then displays the exception. - + encounters an error generated by the server (Client-side errors are raised as standard common language runtime exceptions.). It always contains at least one instance of . + + If the severity of the error is too great, the server may close the . However, the user can reopen the connection and continue. + + For general information about handling exceptions for a .NET Framework data provider, see . + + + +## Examples + The following example generates an because of a missing data source, and then displays the exception. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcException/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcException/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcException/Overview/source.vb" id="Snippet1"::: + ]]> @@ -97,19 +97,19 @@ Gets a collection of one or more objects that give detailed information about exceptions generated by the .NET Framework Data Provider for ODBC. The collected instances of the class. - . - - - -## Examples - The following example displays each within an collection. - + . + + + +## Examples + The following example displays each within an collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcError.Message/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcErrorCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcErrorCollection/Overview/source.vb" id="Snippet1"::: + ]]> Handling and throwing exceptions in .NET @@ -155,11 +155,11 @@ The that contains contextual information about the source or destination. This member overrides . - sets a with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the transmitted over the stream. - + sets a with all the exception object data targeted for serialization. During deserialization, the exception is reconstituted from the transmitted over the stream. + ]]> The parameter is a null reference ( in Visual Basic). @@ -214,19 +214,19 @@ Gets the name of the ODBC driver that generated the error. The name of the ODBC driver that generated the error. - property of the first in the collection. - - - -## Examples - The following example displays the , , and properties of the first within the collection. - + property of the first in the collection. + + + +## Examples + The following example displays the , , and properties of the first within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OdbcException.Source/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcException/Source/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Odbc/OdbcException/Source/source.vb" id="Snippet1"::: + ]]> Handling and throwing exceptions in .NET diff --git a/xml/System.Data.Odbc/OdbcInfoMessageEventArgs.xml b/xml/System.Data.Odbc/OdbcInfoMessageEventArgs.xml index f00f0ecb632..f23676f1eaa 100644 --- a/xml/System.Data.Odbc/OdbcInfoMessageEventArgs.xml +++ b/xml/System.Data.Odbc/OdbcInfoMessageEventArgs.xml @@ -36,11 +36,11 @@ Provides data for the event. - event contains an collection with warnings sent from the data source. - + event contains an collection with warnings sent from the data source. + ]]> @@ -97,11 +97,11 @@ Gets the full text of the error sent from the database. The full text of the error. - property of the first in the collection. - + property of the first in the collection. + ]]> diff --git a/xml/System.Data.Odbc/OdbcParameter.xml b/xml/System.Data.Odbc/OdbcParameter.xml index 6bf35fcde68..32a6ee84bb0 100644 --- a/xml/System.Data.Odbc/OdbcParameter.xml +++ b/xml/System.Data.Odbc/OdbcParameter.xml @@ -871,7 +871,7 @@ public void CreateMyProc(OdbcConnection connection) ## Remarks Setting this property to a value other than the value in the database depends on the implementation of the data provider and may return an error code, truncate, or round data. - The property only affects parameters whose is `Decimal` or `Numeric`. For other data types, is ignored. + The property only affects parameters whose is `Decimal` or `Numeric`. For other data types, is ignored. > [!NOTE] > Use of this property to coerce data passed to the database is not supported. To round, truncate, or otherwise coerce data before passing it to the database, use the class that is part of the `System` namespace prior to assigning a value to the parameter's `Value` property. @@ -1012,11 +1012,11 @@ public void CreateOdbcParameter() property is used only for decimal and numeric input parameters. + The property is used only for decimal and numeric input parameters. The effect of setting this property to a value other than the value in the database depends on the implementation of the data provider and may return an error code, or truncate or round data. - The property only affects parameters whose is `Decimal` or `Numeric`. For other data types, is ignored. + The property only affects parameters whose is `Decimal` or `Numeric`. For other data types, is ignored. When using SQL Server Native Client 10 (or later) to bind a parameter whose type is Decimal, Numeric, VarNumeric, DBDate, or DBTimeStamp, you must manually specify an appropriate Scale value. @@ -1095,9 +1095,9 @@ public void CreateOdbcParameter() property is used for binary and string types. + The property is used for binary and string types. - For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. + For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. For variable-length data types, `Size` describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, `Size` could be used to limit the amount of data sent to the server to the first one hundred characters. @@ -1183,7 +1183,7 @@ public void CreateOdbcParameter() ## Remarks When is set to anything other than an empty string, the value of the parameter is retrieved from the column with the `SourceColumn` name. If is set to `Input`, the value is taken from the . If `Direction` is set to `Output`, the value is taken from the data source. A `Direction` of `InputOutput` is a combination of both. - For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). @@ -1460,7 +1460,7 @@ public void CreateOdbcParameter() Both the and properties can be inferred by setting . If applicable, the size, precision, and scale is also inferred from when the parameterized statement is executed. However, inferred values are not exposed to the user. - The property is overwritten by the `Update` method. + The property is overwritten by the `Update` method. diff --git a/xml/System.Data.Odbc/OdbcPermission.xml b/xml/System.Data.Odbc/OdbcPermission.xml index 32f66716121..c71c99e14ae 100644 --- a/xml/System.Data.Odbc/OdbcPermission.xml +++ b/xml/System.Data.Odbc/OdbcPermission.xml @@ -197,7 +197,7 @@ enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. + The enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. ]]> diff --git a/xml/System.Data.OleDb/OleDbCommand.xml b/xml/System.Data.OleDb/OleDbCommand.xml index cd2c23f0e9a..f6fa89bf179 100644 --- a/xml/System.Data.OleDb/OleDbCommand.xml +++ b/xml/System.Data.OleDb/OleDbCommand.xml @@ -85,31 +85,31 @@ Represents an SQL statement or stored procedure to execute against a data source. - is created, the read/write properties are set to their initial values. For a list of these values, see the constructor. - - features the following methods executing commands at a data source: - -|Item|Description| -|----------|-----------------| -||Executes commands that return rows. may not have the effect that you want if used to execute commands such as SQL SET statements.| -||Executes commands such as SQL INSERT, DELETE, UPDATE, and SET statements.| -||Retrieves a single value, for example, an aggregate value from a database.| - - You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. - - If a fatal (for example, a SQL Server severity level of 20 or greater) is generated by the method executing an , the , the connection may be closed. However, the user can reopen the connection and continue. - - - -## Examples - The following example uses the , along and , to select rows from an Access database. The filled is then returned. The example is passed an initialized , a connection string, a query string that is an SQL SELECT statement, and a string that is the name of the source database table. - + is created, the read/write properties are set to their initial values. For a list of these values, see the constructor. + + features the following methods executing commands at a data source: + +|Item|Description| +|----------|-----------------| +||Executes commands that return rows. may not have the effect that you want if used to execute commands such as SQL SET statements.| +||Executes commands such as SQL INSERT, DELETE, UPDATE, and SET statements.| +||Retrieves a single value, for example, an aggregate value from a database.| + + You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. + + If a fatal (for example, a SQL Server severity level of 20 or greater) is generated by the method executing an , the , the connection may be closed. However, the user can reopen the connection and continue. + + + +## Examples + The following example uses the , along and , to select rows from an Access database. The filled is then returned. The example is passed an initialized , a connection string, a query string that is an SQL SELECT statement, and a string that is the name of the source database table. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/Overview/source.vb" id="Snippet1"::: + ]]> @@ -148,26 +148,26 @@ Initializes a new instance of the class. - . - -|Properties|Initial Value| -|----------------|-------------------| -||empty string ("")| -||30| -||`Text`| -||null| - - - -## Examples - The following example creates an and sets some of its properties. - + . + +|Properties|Initial Value| +|----------------|-------------------| +||empty string ("")| +||30| +||`Text`| +||null| + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.OleDbCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/.ctor/source.vb" id="Snippet1"::: + ]]> Working with Commands @@ -199,26 +199,26 @@ The text of the query. Initializes a new instance of the class with the text of the query. - . - -|Properties|Initial Value| -|----------------|-------------------| -||`cmdText`| -||30| -||`Text`| -||null| - - - -## Examples - The following example creates an and sets some of its properties. - + . + +|Properties|Initial Value| +|----------------|-------------------| +||`cmdText`| +||30| +||`Text`| +||null| + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.OleDbCommand1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/.ctor/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/.ctor/source1.vb" id="Snippet1"::: + ]]> Working with Commands @@ -252,28 +252,28 @@ An that represents the connection to a data source. Initializes a new instance of the class with the text of the query and an . - . - -|Properties|Initial Value| -|----------------|-------------------| -||`cmdText`| -||30| -||`Text`| -||A new that is the value for the `connection` parameter.| - - You can change the value for any of these parameters by setting the related property. - - - -## Examples - The following example creates an and sets some of its properties. - + . + +|Properties|Initial Value| +|----------------|-------------------| +||`cmdText`| +||30| +||`Text`| +||A new that is the value for the `connection` parameter.| + + You can change the value for any of these parameters by setting the related property. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.OleDbCommand2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/.ctor/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/.ctor/source2.vb" id="Snippet1"::: + ]]> Working with Commands @@ -309,28 +309,28 @@ The transaction in which the executes. Initializes a new instance of the class with the text of the query, an , and the . - . - -|Properties|Initial Value| -|----------------|-------------------| -||`cmdText`| -||30| -||`Text`| -||A new that is the value for the `connection` parameter.| - - You can change the value for any of these parameters by setting the related property. - - - -## Examples - The following example creates an and sets some of its properties. - + . + +|Properties|Initial Value| +|----------------|-------------------| +||`cmdText`| +||30| +||`Text`| +||A new that is the value for the `connection` parameter.| + + You can change the value for any of these parameters by setting the related property. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.OleDbCommand3/CS/mysample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/.ctor/mysample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/.ctor/mysample.vb" id="Snippet1"::: + ]]> Working with Commands @@ -369,19 +369,19 @@ Tries to cancel the execution of an . - , executes it, and then cancels the execution. To accomplish this, the method is passed a string that is an SQL SELECT statement and a string to use to connect to the data source. - + , executes it, and then cancels the execution. To accomplish this, the method is passed a string that is an SQL SELECT statement and a string to use to connect to the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.Cancel Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/Cancel/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/Cancel/source.vb" id="Snippet1"::: + ]]> Working with Commands @@ -476,31 +476,31 @@ Gets or sets the SQL statement or stored procedure to execute at the data source. The SQL statement or stored procedure to execute. The default value is an empty string. - property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the `Execute` methods. - - When is set to `TableDirect`, the property should be set to the name of the table or tables to be accessed. The user may be required to use escape character syntax if any of the named tables contain any special characters. All rows and columns of the named table or tables will be returned when you call one of the `Execute` methods. - - You cannot set the , , and properties if the current connection is performing an execute or fetch operation. - - The OLE DB.NET Provider does not support named parameters for passing parameters to an SQL Statement or a stored procedure called by an when is set to `Text`. In this case, the question mark (?) placeholder must be used. For example: - - `SELECT * FROM Customers WHERE CustomerID = ?` - - Therefore, the order in which objects are added to the must directly correspond to the position of the question mark placeholder for the parameter. - - For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). - - - -## Examples - The following example creates an and sets some of its properties. - + property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the `Execute` methods. + + When is set to `TableDirect`, the property should be set to the name of the table or tables to be accessed. The user may be required to use escape character syntax if any of the named tables contain any special characters. All rows and columns of the named table or tables will be returned when you call one of the `Execute` methods. + + You cannot set the , , and properties if the current connection is performing an execute or fetch operation. + + The OLE DB.NET Provider does not support named parameters for passing parameters to an SQL Statement or a stored procedure called by an when is set to `Text`. In this case, the question mark (?) placeholder must be used. For example: + + `SELECT * FROM Customers WHERE CustomerID = ?` + + Therefore, the order in which objects are added to the must directly correspond to the position of the question mark placeholder for the parameter. + + For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.CommandText Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/CommandText/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/CommandText/source.vb" id="Snippet1"::: + ]]> Working with Commands @@ -547,11 +547,11 @@ Gets or sets the wait time (in seconds) before terminating an attempt to execute a command and generating an error. The time (in seconds) to wait for the command to execute. The default is 30 seconds. - because an attempt to execute a command will wait indefinitely. - + because an attempt to execute a command will wait indefinitely. + ]]> Working with Commands @@ -602,19 +602,19 @@ Gets or sets a value that indicates how the property is interpreted. One of the values. The default is Text. - property to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods. - - The , and properties cannot be set if the current connection is performing an execute or fetch operation. - - The OLE DB .NET Provider does not support named parameters for passing parameters to an SQL statement or a stored procedure called by an when is set to Text. In this case, the question mark (?) placeholder must be used. For example: - - `SELECT * FROM Customers WHERE CustomerID = ?` - - Therefore, the order in which objects are added to the must directly correspond to the position of the question mark placeholder for the parameter. For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). - + property to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods. + + The , and properties cannot be set if the current connection is performing an execute or fetch operation. + + The OLE DB .NET Provider does not support named parameters for passing parameters to an SQL statement or a stored procedure called by an when is set to Text. In this case, the question mark (?) placeholder must be used. For example: + + `SELECT * FROM Customers WHERE CustomerID = ?` + + Therefore, the order in which objects are added to the must directly correspond to the position of the question mark placeholder for the parameter. For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). + ]]> The value was not a valid . @@ -669,21 +669,21 @@ Gets or sets the used by this instance of the . The connection to a data source. The default value is . - , and properties if the current connection is performing an execute or fetch operation. - - If you set while a transaction is in progress and the property is not null, an is generated. If the property is not null and the transaction has already been committed or rolled back, is set to null. - - - -## Examples - The following example creates an and sets some of its properties. - + , and properties if the current connection is performing an execute or fetch operation. + + If you set while a transaction is in progress and the property is not null, an is generated. If the property is not null and the transaction has already been committed or rolled back, is set to null. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.Connection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/Connection/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/Connection/source.vb" id="Snippet1"::: + ]]> The property was changed while a transaction was in progress. @@ -744,11 +744,11 @@ Creates a new instance of an object. An object. - method is a strongly typed version of . - + method is a strongly typed version of . + ]]> Working with Commands @@ -983,33 +983,33 @@ Executes an SQL statement against the and returns the number of rows affected. The number of rows affected. - to perform catalog operations, for example, to query the structure of a database or to create database objects such as tables, or to change the data in a database without using a by executing UPDATE, INSERT, or DELETE statements. - - Although the returns no rows, any output parameters or return values mapped to parameters are populated with data. - - For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1. If a rollback occurs, the return value is also -1. - - - -## Examples - The following example creates an and then executes it using . The example is passed a string that is an SQL statement such as UPDATE, INSERT, or DELETE, and a string to use to connect to the data source. - + to perform catalog operations, for example, to query the structure of a database or to create database objects such as tables, or to change the data in a database without using a by executing UPDATE, INSERT, or DELETE statements. + + Although the returns no rows, any output parameters or return values mapped to parameters are populated with data. + + For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1. If a rollback occurs, the return value is also -1. + + + +## Examples + The following example creates an and then executes it using . The example is passed a string that is an SQL statement such as UPDATE, INSERT, or DELETE, and a string to use to connect to the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.ExecuteNonQuery Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/ExecuteNonQuery/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/ExecuteNonQuery/source.vb" id="Snippet1"::: + ]]> - The connection does not exist. - - -or- - - The connection is not open. - - -or- - + The connection does not exist. + + -or- + + The connection is not open. + + -or- + Cannot execute a command within a transaction context that differs from the context in which the connection was originally enlisted. Working with Commands @@ -1051,21 +1051,21 @@ Sends the to the and builds an . An object. - property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . - - Before you close the , first close the object. You must also close the object if you plan to reuse an object. - - - -## Examples - The following example creates an , and then executes it by passing a string that is an SQL SELECT statement, and a string to use to connect to the data source. - + property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . + + Before you close the , first close the object. You must also close the object if you plan to reuse an object. + + + +## Examples + The following example creates an , and then executes it by passing a string that is an SQL SELECT statement, and a string to use to connect to the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.ExecuteReader1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/ExecuteReader/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/ExecuteReader/source.vb" id="Snippet1"::: + ]]> Cannot execute a command within a transaction context that differs from the context in which the connection was originally enlisted. @@ -1102,25 +1102,25 @@ Sends the to the , and builds an using one of the values. An object. - with the method of the object, the .NET Framework Data Provider for OLE DB performs binding using the OLE DB **IRow** interface if it is available. Otherwise, it uses the **IRowset** interface. If your SQL statement is expected to return only a single row, specifying can also improve application performance. - - When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . - - The supports a special mode that enables large binary values to be read efficiently. For more information, see the `SequentialAccess` setting for . - - Before you close the , first close the object. You must also close the object if you plan to reuse an object. If the is created with set to `CloseConnection`, closing the closes the connection automatically. - - - -## Examples - The following example creates an , and then executes it by passing a string that is a Transact-SQL SELECT statement, and a string to use to connect to the data source. is set to . - + with the method of the object, the .NET Framework Data Provider for OLE DB performs binding using the OLE DB **IRow** interface if it is available. Otherwise, it uses the **IRowset** interface. If your SQL statement is expected to return only a single row, specifying can also improve application performance. + + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . + + The supports a special mode that enables large binary values to be read efficiently. For more information, see the `SequentialAccess` setting for . + + Before you close the , first close the object. You must also close the object if you plan to reuse an object. If the is created with set to `CloseConnection`, closing the closes the connection automatically. + + + +## Examples + The following example creates an , and then executes it by passing a string that is a Transact-SQL SELECT statement, and a string to use to connect to the data source. is set to . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.ExecuteReader2/CS/mysample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/ExecuteReader/mysample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/ExecuteReader/mysample.vb" id="Snippet1"::: + ]]> Cannot execute a command within a transaction context that differs from the context in which the connection was originally enlisted. @@ -1162,26 +1162,26 @@ Executes the query, and returns the first column of the first row in the result set returned by the query. Additional columns or rows are ignored. The first column of the first row in the result set, or a null reference if the result set is empty. - method to retrieve a single value, for example, an aggregate value, from a data source. This requires less code than using the method, and then performing the operations that are required to generate the single value using the data returned by an . - - A typical query can be formatted as in the following C# example: - -``` -CommandText = "SELECT COUNT(*) FROM region"; -Int32 count = (Int32) ExecuteScalar(); -``` - - - -## Examples - The following example creates an and then executes it using . The example is passed a string that is an SQL statement that returns an aggregate result, and a string to use to connect to the data source. - + method to retrieve a single value, for example, an aggregate value, from a data source. This requires less code than using the method, and then performing the operations that are required to generate the single value using the data returned by an . + + A typical query can be formatted as in the following C# example: + +``` +CommandText = "SELECT COUNT(*) FROM region"; +Int32 count = (Int32) ExecuteScalar(); +``` + + + +## Examples + The following example creates an and then executes it using . The example is passed a string that is an SQL statement that returns an aggregate result, and a string to use to connect to the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.ExecuteScalar/CS/mysample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/ExecuteScalar/mysample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/ExecuteScalar/mysample.vb" id="Snippet1"::: + ]]> Cannot execute a command within a transaction context that differs from the context in which the connection was originally enlisted. @@ -1227,28 +1227,28 @@ Int32 count = (Int32) ExecuteScalar(); Gets the . The parameters of the SQL statement or stored procedure. The default is an empty collection. - when is set to `Text`. In this case, the question mark (?) placeholder must be used. For example: - - `SELECT * FROM Customers WHERE CustomerID = ?` - - Therefore, the order in which objects are added to the must directly correspond to the position of the question mark placeholder for the parameter in the command text. - + when is set to `Text`. In this case, the question mark (?) placeholder must be used. For example: + + `SELECT * FROM Customers WHERE CustomerID = ?` + + Therefore, the order in which objects are added to the must directly correspond to the position of the question mark placeholder for the parameter in the command text. + > [!NOTE] -> If the parameters in the collection do not match the requirements of the query to be executed, an error may result. - - For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). - - - -## Examples - The following example creates an and displays its parameters. To accomplish this, the method is passed an , a query string that is an SQL SELECT statement, and an array of objects. - +> If the parameters in the collection do not match the requirements of the query to be executed, an error may result. + + For more information, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). + + + +## Examples + The following example creates an and displays its parameters. To accomplish this, the method is passed an , a query string that is an SQL SELECT statement, and an array of objects. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.Parameters Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/Parameters/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbCommand/Parameters/source.vb" id="Snippet1"::: + ]]> Working with Commands @@ -1287,31 +1287,31 @@ Int32 count = (Int32) ExecuteScalar(); Creates a prepared (or compiled) version of the command on the data source. - property is set to `TableDirect`, does nothing. If is set to `StoredProcedure`, the call to should succeed, although it may cause a no-op. - - Before you call , specify the data type of each parameter in the statement to be prepared. For each parameter that has a variable length data type, you must set the **Size** property to the maximum size needed. returns an error if these conditions are not met. - - If you call an `Execute` method after you call , any parameter value that is larger than the value specified by the **Size** property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. - - Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type, you must also specify the maximum **Size**. - - - -## Examples - The following example creates an and opens the connection. The example then prepares a stored procedure on the data source by passing a string that is an SQL SELECT statement and a string to use to connect to the data source. - + property is set to `TableDirect`, does nothing. If is set to `StoredProcedure`, the call to should succeed, although it may cause a no-op. + + Before you call , specify the data type of each parameter in the statement to be prepared. For each parameter that has a variable length data type, you must set the **Size** property to the maximum size needed. returns an error if these conditions are not met. + + If you call an `Execute` method after you call , any parameter value that is larger than the value specified by the **Size** property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. + + Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type, you must also specify the maximum **Size**. + + + +## Examples + The following example creates an and opens the connection. The example then prepares a stored procedure on the data source by passing a string that is an SQL SELECT statement and a string to use to connect to the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.Prepare Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/Prepare/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/Prepare/source.vb" id="Snippet1"::: + ]]> - The is not set. - - -or- - + The is not set. + + -or- + The is not open. Working with Commands @@ -1341,11 +1341,11 @@ Int32 count = (Int32) ExecuteScalar(); Resets the property to the default value. - is 30 seconds. - + is 30 seconds. + ]]> Working with Commands @@ -1396,11 +1396,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1436,11 +1436,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . An object. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1479,13 +1479,13 @@ This member is an explicit interface member implementation. It can be used only Executes the against the , and builds an using one of the values. An built using one of the values. - instance is cast to an interface. - - For a description of this member, see . - + instance is cast to an interface. + + For a description of this member, see . + ]]> @@ -1520,11 +1520,11 @@ This member is an explicit interface member implementation. It can be used only For a description of this member, see . A new that is a copy of this instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1569,11 +1569,11 @@ This member is an explicit interface member implementation. It can be used only Gets or sets the within which the executes. The . The default value is . - property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to an object that is not connected to the same as the object, an exception is thrown the next time that you try to execute a statement. - + property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to an object that is not connected to the same as the object, an exception is thrown the next time that you try to execute a statement. + ]]> Working with Commands @@ -1620,13 +1620,13 @@ This member is an explicit interface member implementation. It can be used only Gets or sets how command results are applied to the when used by the method of the . One of the values. - value is Both unless the command is automatically generated (as with the ), in which case the default is None. - - For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). - + value is Both unless the command is automatically generated (as with the ), in which case the default is None. + + For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). + ]]> The value entered was not one of the values. diff --git a/xml/System.Data.OleDb/OleDbCommandBuilder.xml b/xml/System.Data.OleDb/OleDbCommandBuilder.xml index ce44d8a5009..bafdb2ed413 100644 --- a/xml/System.Data.OleDb/OleDbCommandBuilder.xml +++ b/xml/System.Data.OleDb/OleDbCommandBuilder.xml @@ -50,11 +50,11 @@ does not automatically generate the SQL statements required to reconcile changes made to a with the associated data source. However, you can create an object to automatically generate SQL statements for single-table updates if you set the property of the . Then, any additional SQL statements that you do not set are generated by the . + The does not automatically generate the SQL statements required to reconcile changes made to a with the associated data source. However, you can create an object to automatically generate SQL statements for single-table updates if you set the property of the . Then, any additional SQL statements that you do not set are generated by the . - The registers itself as a listener for events whenever you set the property. You can only associate one or object with each other at one time. + The registers itself as a listener for events whenever you set the property. You can only associate one or object with each other at one time. - To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata is retrieved, such as after the first update, you should call the method to update the metadata. + To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata is retrieved, such as after the first update, you should call the method to update the metadata. The also uses the , , and properties referenced by the . The user should call if one or more of these properties are modified, or if the itself is replaced. Otherwise the , , and properties retain their previous values. diff --git a/xml/System.Data.OleDb/OleDbConnection.xml b/xml/System.Data.OleDb/OleDbConnection.xml index 4179a504069..195763d2c3a 100644 --- a/xml/System.Data.OleDb/OleDbConnection.xml +++ b/xml/System.Data.OleDb/OleDbConnection.xml @@ -139,7 +139,7 @@ is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. + When a new instance of is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. |Properties|Initial value| |----------------|-------------------| @@ -148,7 +148,7 @@ ||empty string ("")| ||empty string ("")| - You can change the value for these properties only by using the property. + You can change the value for these properties only by using the property. @@ -192,7 +192,7 @@ is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. + When a new instance of is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. |Properties|Initial value| |----------------|-------------------| @@ -201,7 +201,7 @@ ||empty string ("")| ||empty string ("")| - You can change the value for these properties only by using the property. + You can change the value for these properties only by using the property. @@ -533,7 +533,7 @@ - Unlike ODBC or ADO, the connection string that is returned is the same as the user-set , minus security information if `Persist Security Info` is set to `false` (default). The .NET Framework Data Provider for OLE DB does not persist or return the password in a connection string unless you set the `Persist Security Info` keyword to `true` (not recommended). To maintain a high level of security, it is strongly recommended that you use the `Integrated Security` keyword with `Persist Security Info` set to `false`. - You can use the property to connect to a variety of data sources. The following example illustrates several possible connection strings. + You can use the property to connect to a variety of data sources. The following example illustrates several possible connection strings. ```txt "Provider=MSDAORA; Data Source=ORACLE8i7;Persist Security Info=False;Integrated Security=Yes" @@ -547,9 +547,9 @@ For more information about connection strings, see [Using Connection String Keywords with SQL Server Native Client](https://go.microsoft.com/fwlink/?LinkId=126696). - The property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, these properties are updated, except when an error is detected. In this case, none of the properties are updated. properties return only those settings that are contained in the . + The property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, these properties are updated, except when an error is detected. In this case, none of the properties are updated. properties return only those settings that are contained in the . - Resetting the on a closed connection resets all connection string values and related properties. This includes the password. For example, if you set a connection string that includes "Initial Catalog= AdventureWorks", and then reset the connection string to "Provider= SQLOLEDB;Data Source= MySQLServer;IntegratedSecurity=SSPI", the property is no longer set to AdventureWorks. (The Initial Catalog value of the connection string corresponds to the `Database` property.) + Resetting the on a closed connection resets all connection string values and related properties. This includes the password. For example, if you set a connection string that includes "Initial Catalog= AdventureWorks", and then reset the connection string to "Provider= SQLOLEDB;Data Source= MySQLServer;IntegratedSecurity=SSPI", the property is no longer set to AdventureWorks. (The Initial Catalog value of the connection string corresponds to the `Database` property.) A preliminary validation of the connection string is performed when the property is set. If values for the `Provider`, `Connect Timeout`, `Persist Security Info`, or `OLE DB Services` are included in the string, these values are checked. When an application calls the method, the connection string is fully validated. If the connection string contains invalid or unsupported properties, a run-time exception, such as , is generated. @@ -751,7 +751,7 @@ property updates dynamically. If you change the current database using a SQL statement or the method, an informational message is sent and the property is updated automatically. + The property updates dynamically. If you change the current database using a SQL statement or the method, an informational message is sent and the property is updated automatically. @@ -1367,7 +1367,7 @@ , the property will continue to return `Open`. If you are working with an OLE DB Provider that supports polling for this information on a live connection, calling the method and then checking the property will tell you that the connection is no longer open. The method relies on functionality in the OLE DB Provider to verify the current state of the connection. To determine if your OLE DB Provider supports this functionality, check the provider's documentation for information on DBPROP_CONNECTIONSTATUS. + Some OLE DB providers can check the current state of the connection. For example, if the database server has recycled since you opened your , the property will continue to return `Open`. If you are working with an OLE DB Provider that supports polling for this information on a live connection, calling the method and then checking the property will tell you that the connection is no longer open. The method relies on functionality in the OLE DB Provider to verify the current state of the connection. To determine if your OLE DB Provider supports this functionality, check the provider's documentation for information on DBPROP_CONNECTIONSTATUS. ]]> @@ -1419,7 +1419,7 @@ property maps to the OLE DB DBPROP_DBMSVER property. If is not supported by the underlying OLE DB provider, an empty string is returned. + The property maps to the OLE DB DBPROP_DBMSVER property. If is not supported by the underlying OLE DB provider, an empty string is returned. The version is of the form *##.##.####*, where the first two digits are the major version, the next two digits are the minor version, and the last four digits are the release version. The provider must render the product version in this form but can also append the product-specific version - for example, "04.01.0000 Rdb 4.1". The string is of the form *major.minor.build*, where major and minor are exactly two digits and build is exactly four digits. diff --git a/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml b/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml index 3f02a0587e7..794f781f21a 100644 --- a/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml +++ b/xml/System.Data.OleDb/OleDbConnectionStringBuilder.xml @@ -72,7 +72,7 @@ |Persist Security Info||False| |OLE DB Services||-13| - The property handles attempts to insert malicious entries. For example, the following code, using the default property (the indexer, in C#) correctly escapes the nested key/value pair: + The property handles attempts to insert malicious entries. For example, the following code, using the default property (the indexer, in C#) correctly escapes the nested key/value pair: ```vb Dim builder As _ @@ -172,7 +172,7 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal property, either directly (by setting the property) or by passing a connection string as a parameter to the constructor, might affect the set of key/value pairs that are contained within the instance. Setting the property to "sqloledb," for example, adds all the standard SQL connection string properties. + Setting the property, either directly (by setting the property) or by passing a connection string as a parameter to the constructor, might affect the set of key/value pairs that are contained within the instance. Setting the property to "sqloledb," for example, adds all the standard SQL connection string properties. For some providers, assigning a connection string within the constructor causes the order of supplied key/value pairs to be rearranged. @@ -210,7 +210,7 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal method removes all key/value pairs from the , and resets all corresponding properties to their default values. This includes setting the property to 0, and setting the property to an empty string. + The method removes all key/value pairs from the , and resets all corresponding properties to their default values. This includes setting the property to 0, and setting the property to an empty string. ]]> @@ -250,7 +250,7 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal property may implicitly fill in appropriate key/value pairs for the provider, the method does not return `true` for implicitly provided keys. This method returns `true` only for explicitly provided keys. + Although setting the property may implicitly fill in appropriate key/value pairs for the provider, the method does not return `true` for implicitly provided keys. This method returns `true` only for explicitly provided keys. @@ -302,7 +302,7 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is `String.Empty`. This property corresponds to the "Data Source" key within the connection string. + If the value passed in is null when you try to set the property, the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is `String.Empty`. This property corresponds to the "Data Source" key within the connection string. @@ -363,7 +363,7 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is `String.Empty`. This property corresponds to the "FileName" key within the connection string. + If the value passed in is null when you try to set the property, the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is `String.Empty`. This property corresponds to the "FileName" key within the connection string. Setting this property does not cause the instance to read the contents of the referenced file, even if the file exists and contains valid connection information. Setting this property has no effect other than to indicate the file to read when connecting to the data source. @@ -432,12 +432,12 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal property may add corresponding items to the collection of key/value pairs (depending on the behavior of the specific provider), you may be able to retrieve a value for a key you have not set explicitly. For example, as soon as you have set the property to "sqloledb," you can retrieve the "Workstation ID" value even if you have not set it yourself. See the example in this topic for a demonstration. + Because setting the property may add corresponding items to the collection of key/value pairs (depending on the behavior of the specific provider), you may be able to retrieve a value for a key you have not set explicitly. For example, as soon as you have set the property to "sqloledb," you can retrieve the "Workstation ID" value even if you have not set it yourself. See the example in this topic for a demonstration. ## Examples - The following example uses the property (the indexer, in C#) to retrieve and set values within the collection of key/value pairs. Note that setting the provider, in this case, also provides default values for all the key/value pairs associated with the selected provider. + The following example uses the property (the indexer, in C#) to retrieve and set values within the collection of key/value pairs. Note that setting the provider, in this case, also provides default values for all the key/value pairs associated with the selected provider. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OleDbConnectionStringBuilder.Item/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnectionStringBuilder/Item/source.vb" id="Snippet1"::: @@ -477,7 +477,7 @@ Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Sample.mdb;User ID="Admin;NewVal is unspecified, but it is the same order as the associated values in the returned by the property. +The order of the values in the is unspecified, but it is the same order as the associated values in the returned by the property. ]]> @@ -531,7 +531,7 @@ The order of the values in the is unspecif ## Examples - The following example works with the property in two ways. First, it assigns a value directly to the property, demonstrating the effect this action has on the resulting connection string. Then, the example clears the and assigns a complete connection string that contains a value for the OLE DB Services key. This step demonstrates that setting the value from the connection string modifies the property, as well. + The following example works with the property in two ways. First, it assigns a value directly to the property, demonstrating the effect this action has on the resulting connection string. Then, the example clears the and assigns a complete connection string that contains a value for the OLE DB Services key. This step demonstrates that setting the value from the connection string modifies the property, as well. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OleDbConnectionStringBuilder.OleDbServices/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnectionStringBuilder/OleDbServices/source.vb" id="Snippet1"::: @@ -584,7 +584,7 @@ The order of the values in the is unspecif ## Examples - The following example works with the property in two ways. First, it assigns a value directly to the property, demonstrating the effect this action has on the resulting connection string. Then, the example clears the and assigns a complete connection string that contains a value for the "Persist Security Info" key. This step demonstrates that setting the value from the connection string modifies the property, as well. + The following example works with the property in two ways. First, it assigns a value directly to the property, demonstrating the effect this action has on the resulting connection string. Then, the example clears the and assigns a complete connection string that contains a value for the "Persist Security Info" key. This step demonstrates that setting the value from the connection string modifies the property, as well. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks OleDbConnectionStringBuilder.PersistSecurityInfo/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbConnectionStringBuilder/PersistSecurityInfo/source.vb" id="Snippet1"::: @@ -636,9 +636,9 @@ The order of the values in the is unspecif property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is `String.Empty`. This property corresponds to the "Provider" key within the connection string. + If the value passed in is null when you try to set the property, the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is `String.Empty`. This property corresponds to the "Provider" key within the connection string. - Setting the value of the `Provider` property, either directly (by setting the property) or by passing a connection string as a parameter to the constructor, might affect the set of key/value pairs that are contained within the instance. Setting the property to "sqloledb," for example, adds all the standard SQL connection string properties. See the example in this topic for a demonstration of this behavior. + Setting the value of the `Provider` property, either directly (by setting the property) or by passing a connection string as a parameter to the constructor, might affect the set of key/value pairs that are contained within the instance. Setting the property to "sqloledb," for example, adds all the standard SQL connection string properties. See the example in this topic for a demonstration of this behavior. For some providers, assigning a connection string within the constructor causes the order of supplied key/value pairs to be rearranged. diff --git a/xml/System.Data.OleDb/OleDbDataAdapter.xml b/xml/System.Data.OleDb/OleDbDataAdapter.xml index cfca7f2d869..278f629ced2 100644 --- a/xml/System.Data.OleDb/OleDbDataAdapter.xml +++ b/xml/System.Data.OleDb/OleDbDataAdapter.xml @@ -90,27 +90,27 @@ Represents a set of data commands and a database connection that are used to fill the and update the data source. - serves as a bridge between a and data source for retrieving and saving data. The provides this bridge by using to load data from the data source into the , and using to send changes made in the back to the data source. - - When the fills a , it will create the appropriate tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). - - Note that some OLE DB providers, including the MSDataShape provider, do not return base table or primary key information. Therefore, the cannot correctly set the property on any created . In these cases you should explicitly specify primary keys for tables in the . - - The also includes the , , , , and properties to facilitate the loading and updating of data. - - When you create an instance of , properties are set to their initial values. For a list of these values, see the constructor. - - - -## Examples - The following example uses the , and , to select records from an Access data source, and populate a with the selected rows. The filled is then returned. To accomplish this, the method is passed an initialized , a connection string, and a query string that is an SQL SELECT statement. - + serves as a bridge between a and data source for retrieving and saving data. The provides this bridge by using to load data from the data source into the , and using to send changes made in the back to the data source. + + When the fills a , it will create the appropriate tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). + + Note that some OLE DB providers, including the MSDataShape provider, do not return base table or primary key information. Therefore, the cannot correctly set the property on any created . In these cases you should explicitly specify primary keys for tables in the . + + The also includes the , , , , and properties to facilitate the loading and updating of data. + + When you create an instance of , properties are set to their initial values. For a list of these values, see the constructor. + + + +## Examples + The following example uses the , and , to select records from an Access data source, and populate a with the selected rows. The filled is then returned. To accomplish this, the method is passed an initialized , a connection string, and a query string that is an SQL SELECT statement. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/.ctor/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/.ctor/source1.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -147,26 +147,26 @@ Initializes a new instance of the class. - , the following read/write properties are set to the following initial values. - -|Properties|Initial value| -|----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| - - You can change the value of any of these properties through a separate call to the property. - - - -## Examples - The following example creates an and sets some of its properties. - + , the following read/write properties are set to the following initial values. + +|Properties|Initial value| +|----------------|-------------------| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| + + You can change the value of any of these properties through a separate call to the property. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter.OleDbDataAdapter Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/.ctor/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -198,28 +198,28 @@ An that is a SELECT statement or stored procedure, and is set as the property of the . Initializes a new instance of the class with the specified as the property. - constructor sets the property to the value specified in the `selectCommand` parameter. - - When you create an instance of , the following read/write properties are set to the following initial values. - -|Properties|Initial value| -|----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| - - You can change the value of any of these properties through a separate call to the property. - - - -## Examples - The following example creates an and sets some of its properties. - + constructor sets the property to the value specified in the `selectCommand` parameter. + + When you create an instance of , the following read/write properties are set to the following initial values. + +|Properties|Initial value| +|----------------|-------------------| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| + + You can change the value of any of these properties through a separate call to the property. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter.OleDbDataAdapter1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/Overview/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -253,28 +253,28 @@ An that represents the connection. Initializes a new instance of the class with a . - opens and closes an if it is not already open. This can be useful in an application that must call the method for two or more objects. If the is already open, you must explicitly call or **Dispose** to close it. - - When you create an instance of , the following read/write properties are set to the following initial values. - -|Properties|Initial value| -|----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| - - You can change the value of either of these properties through a separate call to the property. - - - -## Examples - The following example creates an and sets some of its properties. - + opens and closes an if it is not already open. This can be useful in an application that must call the method for two or more objects. If the is already open, you must explicitly call or **Dispose** to close it. + + When you create an instance of , the following read/write properties are set to the following initial values. + +|Properties|Initial value| +|----------------|-------------------| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| + + You can change the value of either of these properties through a separate call to the property. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter.OleDbDataAdapter3 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/.ctor/source3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/.ctor/source3.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -308,28 +308,28 @@ The connection string. Initializes a new instance of the class with a . - constructor uses the `selectConnectionString` parameter to set the property. However, it does not open the connection. You still must explicitly open the connection. - - When you create an instance of , the following read/write properties are set to the following initial values. - -|Properties|Initial value| -|----------------|-------------------| -||`MissingMappingAction.Passthrough`| -||`MissingSchemaAction.Add`| - - You can change the value of any of these properties through a separate call to the property. - - - -## Examples - The following example creates an and sets some of its properties. - + constructor uses the `selectConnectionString` parameter to set the property. However, it does not open the connection. You still must explicitly open the connection. + + When you create an instance of , the following read/write properties are set to the following initial values. + +|Properties|Initial value| +|----------------|-------------------| +||`MissingMappingAction.Passthrough`| +||`MissingSchemaAction.Add`| + + You can change the value of any of these properties through a separate call to the property. + + + +## Examples + The following example creates an and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter.OleDbDataAdapter2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/.ctor/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/.ctor/source2.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -473,21 +473,21 @@ Gets or sets an SQL statement or stored procedure for deleting records from the data set. An used during to delete records in the data source that correspond to deleted rows in the . - , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - - - -## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. - + , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + + + +## Examples + The following example creates an and sets the and properties. It assumes that you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.DeleteCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -561,77 +561,77 @@ Adds or refreshes rows in a to match those in an ADO or object using the specified and ADO objects. The number of rows successfully refreshed to the . This does not include rows affected by statements that do not return rows. - , but any updates to the data must be handled by ADO.NET. - - This overload of the method does not close the input `Recordset` on completion of the operation. - - When handling batch SQL statements that return multiple results, this implementation of and for the OLE DB.NET Framework Data Provider retrieves schema information for only the first result. - - The operation adds the rows to the specified destination object in the , creating the object if it does not already exist. When you create a object, the operation ordinarily creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - - You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . If primary key information is present, any duplicate rows are reconciled and only appear one time in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. - - If the returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to make sure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - - To function correctly with the .NET Framework Data Provider for OLE DB, `AddWithKey` requires that the native OLE DB provider obtains required primary key information by setting the DBPROP_UNIQUEROWS property, and then determines which columns are primary key columns by examining DBCOLUMN_KEYCOLUMN in the `IColumnsRowset`. Alternatively the user may explicitly set the primary key constraints on each . This makes sure that incoming records that match existing records are updated instead of appended. - - If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. Empty column names are added to the , using an empty string for the first column, followed by "1", "2", "3", and so on for the subsequent empty columns. - - Values in ADO `Recordset` or `Record` objects are converted to common language runtime types for storage in the . - + , but any updates to the data must be handled by ADO.NET. + + This overload of the method does not close the input `Recordset` on completion of the operation. + + When handling batch SQL statements that return multiple results, this implementation of and for the OLE DB.NET Framework Data Provider retrieves schema information for only the first result. + + The operation adds the rows to the specified destination object in the , creating the object if it does not already exist. When you create a object, the operation ordinarily creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + + You can use the method multiple times on the same . If a primary key exists, incoming rows are merged with matching rows that already exist. If no primary key exists, incoming rows are appended to the . If primary key information is present, any duplicate rows are reconciled and only appear one time in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. + + If the returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to make sure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + + To function correctly with the .NET Framework Data Provider for OLE DB, `AddWithKey` requires that the native OLE DB provider obtains required primary key information by setting the DBPROP_UNIQUEROWS property, and then determines which columns are primary key columns by examining DBCOLUMN_KEYCOLUMN in the `IColumnsRowset`. Alternatively the user may explicitly set the primary key constraints on each . This makes sure that incoming records that match existing records are updated instead of appended. + + If the encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. Empty column names are added to the , using an empty string for the first column, followed by "1", "2", "3", and so on for the subsequent empty columns. + + Values in ADO `Recordset` or `Record` objects are converted to common language runtime types for storage in the . + > [!CAUTION] -> This overload of the method does not implicitly call `Close` on the ADO object when the fill operation is complete. Therefore, always call `Close` when you are finished using ADO `Recordset` or `Record` objects. This makes sure that the underlying connection to a data source is released in a timely manner, and also prevents possible access violations because of unmanaged ADO objects being reclaimed by garbage collection when existing references still exist. - - When you call the `TableMappings.Add` method on a `DataAdapter` and you explicitly map the source table parameter to an empty string, the dataset is successfully filled using the source table, but the dataset will be populated with nothing. For example, in the following example, `rDataSet` will be populated with nothing. - -``` -rAdapter.TableMappings.Add("source table", ""); -rAdapter.Fill(rDataSet, "source table"); -``` - - This example shows how you can skip a result when dealing with multiple results. - - The following example uses an to fill a using an ADO `Recordset`. This example assumes that you have created an ADO `Recordset`. - -```vb -Dim custDA As OleDbDataAdapter = New OleDbDataAdapter() - Dim custDS As DataSet = New DataSet - Dim custTable As DataTable = New DataTable("Customers") - custTable.Columns.Add("CustomerID", Type.GetType("System.String")) - custTable.Columns.Add("CompanyName", Type.GetType("System.String")) - custDS.Tables.Add(custTable) - 'Use ADO objects from ADO library (msado15.dll) imported - ' as.NET library ADODB.dll using TlbImp.exe - Dim adoConn As ADODB.Connection = New ADODB.Connection() - Dim adoRS As ADODB.Recordset = New ADODB.Recordset() - adoConn.Open("Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;", "", "", -1) - adoRS.Open("SELECT CustomerID, CompanyName FROM Customers", adoConn, ADODB.CursorTypeEnum.adOpenForwardOnly, ADODB.LockTypeEnum.adLockReadOnly, 1) - custDA.Fill(custTable, adoRS) - adoRS.Close() - adoConn.Close() -``` - -```csharp -OleDbDataAdapter custDA = new OleDbDataAdapter(); - DataSet custDS = new DataSet(); - DataTable custTable = new DataTable("Customers"); - custTable.Columns.Add("CustomerID", typeof(String)); - custTable.Columns.Add("CompanyName", typeof(String)); - custDS.Tables.Add(custTable); - //Use ADO objects from ADO library (msado15.dll) imported - // as.NET library ADODB.dll using TlbImp.exe - ADODB.Connection adoConn = new ADODB.Connection(); - ADODB.Recordset adoRS = new ADODB.Recordset(); - adoConn.Open("Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;", "", "", -1); - adoRS.Open("SELECT CustomerID, CompanyName FROM Customers", adoConn, ADODB.CursorTypeEnum.adOpenForwardOnly, ADODB.LockTypeEnum.adLockReadOnly, 1); - custDA.Fill(custTable, adoRS); - adoRS.Close(); - adoConn.Close(); -``` - +> This overload of the method does not implicitly call `Close` on the ADO object when the fill operation is complete. Therefore, always call `Close` when you are finished using ADO `Recordset` or `Record` objects. This makes sure that the underlying connection to a data source is released in a timely manner, and also prevents possible access violations because of unmanaged ADO objects being reclaimed by garbage collection when existing references still exist. + + When you call the `TableMappings.Add` method on a `DataAdapter` and you explicitly map the source table parameter to an empty string, the dataset is successfully filled using the source table, but the dataset will be populated with nothing. For example, in the following example, `rDataSet` will be populated with nothing. + +``` +rAdapter.TableMappings.Add("source table", ""); +rAdapter.Fill(rDataSet, "source table"); +``` + + This example shows how you can skip a result when dealing with multiple results. + + The following example uses an to fill a using an ADO `Recordset`. This example assumes that you have created an ADO `Recordset`. + +```vb +Dim custDA As OleDbDataAdapter = New OleDbDataAdapter() + Dim custDS As DataSet = New DataSet + Dim custTable As DataTable = New DataTable("Customers") + custTable.Columns.Add("CustomerID", Type.GetType("System.String")) + custTable.Columns.Add("CompanyName", Type.GetType("System.String")) + custDS.Tables.Add(custTable) + 'Use ADO objects from ADO library (msado15.dll) imported + ' as.NET library ADODB.dll using TlbImp.exe + Dim adoConn As ADODB.Connection = New ADODB.Connection() + Dim adoRS As ADODB.Recordset = New ADODB.Recordset() + adoConn.Open("Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;", "", "", -1) + adoRS.Open("SELECT CustomerID, CompanyName FROM Customers", adoConn, ADODB.CursorTypeEnum.adOpenForwardOnly, ADODB.LockTypeEnum.adLockReadOnly, 1) + custDA.Fill(custTable, adoRS) + adoRS.Close() + adoConn.Close() +``` + +```csharp +OleDbDataAdapter custDA = new OleDbDataAdapter(); + DataSet custDS = new DataSet(); + DataTable custTable = new DataTable("Customers"); + custTable.Columns.Add("CustomerID", typeof(String)); + custTable.Columns.Add("CompanyName", typeof(String)); + custDS.Tables.Add(custTable); + //Use ADO objects from ADO library (msado15.dll) imported + // as.NET library ADODB.dll using TlbImp.exe + ADODB.Connection adoConn = new ADODB.Connection(); + ADODB.Recordset adoRS = new ADODB.Recordset(); + adoConn.Open("Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;", "", "", -1); + adoRS.Open("SELECT CustomerID, CompanyName FROM Customers", adoConn, ADODB.CursorTypeEnum.adOpenForwardOnly, ADODB.LockTypeEnum.adLockReadOnly, 1); + custDA.Fill(custTable, adoRS); + adoRS.Close(); + adoConn.Close(); +``` + ]]> DataAdapters and DataReaders @@ -670,60 +670,60 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); Adds or refreshes rows in the to match those in an ADO or object using the specified , ADO object, and source table name. The number of rows successfully added to or refreshed in the . This does not include rows affected by statements that do not return rows. - , but any updates to the data must be handled by ADO.NET. - - The method iterates through multiple results by calling the `NextRecordset` method on the `Recordset`, closing the input `Recordset` on completion of the operation. - - The operation adds the rows to the specified destination object in the , creating the object if it does not already exist. When you create a object, the operation ordinarily creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. - - If primary key information is present, any duplicate rows are reconciled and only appear one time in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. - - To function correctly with the .NET Framework Data Provider for OLE DB, `AddWithKey` requires the native OLE DB provider to obtain required primary key information by setting the DBPROP_UNIQUEROWS property, and then determine which columns are primary key columns by examining DBCOLUMN_KEYCOLUMN in the **IColumnsRowset**. Alternatively the user may explicitly set the primary key constraints on each . This ensures that incoming records that match existing records are updated instead of appended. - - If the returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to make sure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). - - If the `Recordset` is closed before the starting of the operation, no error results. This is required for handling of multiple results, because queries that do not return rows are indicated by a closed `Recordset`. The just calls `NextRecordset` on the closed `Recordset` and continues processing. - - If an error is encountered while populating the data set, rows added before the occurrence of the error remain in the . The rest of the operation is aborted. - - If the object encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). Applications that use column and table names should make sure that conflicts with these naming patterns does not occur. - - Values in ADO `Recordset` or `Record` objects are converted to common language runtime types for storage in the . - + , but any updates to the data must be handled by ADO.NET. + + The method iterates through multiple results by calling the `NextRecordset` method on the `Recordset`, closing the input `Recordset` on completion of the operation. + + The operation adds the rows to the specified destination object in the , creating the object if it does not already exist. When you create a object, the operation ordinarily creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + + If primary key information is present, any duplicate rows are reconciled and only appear one time in the that corresponds to the . Primary key information may be set either through , by specifying the property of the , or by setting the property to `AddWithKey`. + + To function correctly with the .NET Framework Data Provider for OLE DB, `AddWithKey` requires the native OLE DB provider to obtain required primary key information by setting the DBPROP_UNIQUEROWS property, and then determine which columns are primary key columns by examining DBCOLUMN_KEYCOLUMN in the **IColumnsRowset**. Alternatively the user may explicitly set the primary key constraints on each . This ensures that incoming records that match existing records are updated instead of appended. + + If the returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to make sure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). + + If the `Recordset` is closed before the starting of the operation, no error results. This is required for handling of multiple results, because queries that do not return rows are indicated by a closed `Recordset`. The just calls `NextRecordset` on the closed `Recordset` and continues processing. + + If an error is encountered while populating the data set, rows added before the occurrence of the error remain in the . The rest of the operation is aborted. + + If the object encounters duplicate columns while populating a , it generates names for the subsequent columns, using the pattern "*columnname*1", "*columnname*2", "*columnname*3", and so on. If the incoming data contains unnamed columns, they are placed in the according to the pattern "Column1", "Column2", and so on. When multiple result sets are added to the each result set is placed in a separate table. Additional result sets are named by appending integral values to the specified table name (for example, "Table", "Table1", "Table2", and so on.). Applications that use column and table names should make sure that conflicts with these naming patterns does not occur. + + Values in ADO `Recordset` or `Record` objects are converted to common language runtime types for storage in the . + > [!NOTE] -> This overload of the method implicitly calls `Close` on the ADO object when the fill operation is complete. - - The following example uses an to fill a using an ADO `Recordset` that is an ADO `Record` object. This example assumes that you have created an ADO `RecordSet` and `Record` object. - -```vb -Dim custDA As OleDbDataAdapter = New OleDbDataAdapter() - Dim custDS As DataSet = New DataSet - 'Use ADO objects from ADO library (msado15.dll) imported - ' as.NET library ADODB.dll using TlbImp.exe - Dim adoConn As ADODB.Connection = New ADODB.Connection() - Dim adoRS As ADODB.Recordset = New ADODB.Recordset() - adoConn.Open("Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;", "", "", -1) - adoRS.Open("SELECT * FROM Customers", adoConn, ADODB.CursorTypeEnum.adOpenForwardOnly, ADODB.LockTypeEnum.adLockReadOnly, 1) - custDA.Fill(custDS, adoRS, "Customers") - adoConn.Close() -``` - -```csharp -OleDbDataAdapter custDA = new OleDbDataAdapter(); - DataSet custDS = new DataSet(); - //Use ADO objects from ADO library (msado15.dll) imported - // as.NET library ADODB.dll using TlbImp.exe - ADODB.Connection adoConn = new ADODB.Connection(); - ADODB.Recordset adoRS = new ADODB.Recordset(); - adoConn.Open("Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;", "", "", -1); - adoRS.Open("SELECT * FROM Customers", adoConn, ADODB.CursorTypeEnum.adOpenForwardOnly, ADODB.LockTypeEnum.adLockReadOnly, 1); - custDA.Fill(custDS, adoRS, "Customers"); - adoConn.Close(); -``` - +> This overload of the method implicitly calls `Close` on the ADO object when the fill operation is complete. + + The following example uses an to fill a using an ADO `Recordset` that is an ADO `Record` object. This example assumes that you have created an ADO `RecordSet` and `Record` object. + +```vb +Dim custDA As OleDbDataAdapter = New OleDbDataAdapter() + Dim custDS As DataSet = New DataSet + 'Use ADO objects from ADO library (msado15.dll) imported + ' as.NET library ADODB.dll using TlbImp.exe + Dim adoConn As ADODB.Connection = New ADODB.Connection() + Dim adoRS As ADODB.Recordset = New ADODB.Recordset() + adoConn.Open("Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;", "", "", -1) + adoRS.Open("SELECT * FROM Customers", adoConn, ADODB.CursorTypeEnum.adOpenForwardOnly, ADODB.LockTypeEnum.adLockReadOnly, 1) + custDA.Fill(custDS, adoRS, "Customers") + adoConn.Close() +``` + +```csharp +OleDbDataAdapter custDA = new OleDbDataAdapter(); + DataSet custDS = new DataSet(); + //Use ADO objects from ADO library (msado15.dll) imported + // as.NET library ADODB.dll using TlbImp.exe + ADODB.Connection adoConn = new ADODB.Connection(); + ADODB.Recordset adoRS = new ADODB.Recordset(); + adoConn.Open("Provider=SQLOLEDB;Data Source=localhost;Initial Catalog=Northwind;Integrated Security=SSPI;", "", "", -1); + adoRS.Open("SELECT * FROM Customers", adoConn, ADODB.CursorTypeEnum.adOpenForwardOnly, ADODB.LockTypeEnum.adLockReadOnly, 1); + custDA.Fill(custDS, adoRS, "Customers"); + adoConn.Close(); +``` + ]]> The source table is invalid. @@ -778,24 +778,24 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); Gets or sets an SQL statement or stored procedure used to insert new records into the data source. An used during to insert records in the data source that correspond to new rows in the . - , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - + , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + > [!NOTE] -> If execution of this command returns rows, these rows may be added to the depending on how you set the property of the object. - - - -## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. - +> If execution of this command returns rows, these rows may be added to the depending on how you set the property of the object. + + + +## Examples + The following example creates an and sets the and properties. It assumes that you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.InsertCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/InsertCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/InsertCommand/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -892,33 +892,33 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); Occurs during after a command is executed against the data source. The attempt to update is made. Therefore, the event occurs. - , there are two events that occur per data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - - -## Examples - The following example shows the and events being used. - + , there are two events that occur per data row updated. The order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + + +## Examples + The following example shows the and events being used. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter.RowUpdated Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/RowUpdated/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/RowUpdated/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -955,33 +955,33 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); Occurs during before a command is executed against the data source. The attempt to update is made. Therefore, the event occurs. - , there are two events that occur per data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - - -## Examples - The following example shows the and events being used. - + , there are two events that occur per data row updated. The order of execution is as follows: + +1. The values in the are moved to the parameter values. + +2. The event is raised. + +3. The command executes. + +4. If the command is set to `FirstReturnedRecord`, the first returned result is placed in the . + +5. If there are output parameters, they are placed in the . + +6. The event is raised. + +7. is called. + + + +## Examples + The following example shows the and events being used. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter.RowUpdated Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/RowUpdated/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OleDb/OleDbDataAdapter/RowUpdated/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -1035,21 +1035,21 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); Gets or sets an SQL statement or stored procedure used to select records in the data source. An that is used during to select records from data source for placement in the . - is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - - If the returns no rows, no tables are added to the , and no exception is raised. - - - -## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. - + is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + + If the returns no rows, no tables are added to the , and no exception is raised. + + + +## Examples + The following example creates an and sets the and properties. It assumes that you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.SelectCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/SelectCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/SelectCommand/source.vb" id="Snippet1"::: + ]]> DataAdapters and DataReaders @@ -1083,11 +1083,11 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); For a description of this member, see . An used during an update to delete records in the data source for deleted rows in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1120,11 +1120,11 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); For a description of this member, see . An that is used during an update to insert records from a data source for placement in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1157,11 +1157,11 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); For a description of this member, see . An that is used during an update to select records from a data source for placement in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1194,11 +1194,11 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); For a description of this member, see . An used during an update to update records in the data source for modified rows in the data set. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1233,11 +1233,11 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); For a description of this member, see . A new that is a copy of this instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]>
@@ -1290,24 +1290,24 @@ OleDbDataAdapter custDA = new OleDbDataAdapter(); Gets or sets an SQL statement or stored procedure used to update records in the data source. An used during to update records in the data source that correspond to modified rows in the . - , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - + , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + > [!NOTE] -> If execution of this command returns rows, these rows may be merged with the depending on how you set the property of the object. - - - -## Examples - The following example creates an and sets the and properties. It assumes that you have already created an object. - +> If execution of this command returns rows, these rows may be merged with the depending on how you set the property of the object. + + + +## Examples + The following example creates an and sets the and properties. It assumes that you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter.UpdateCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: + ]]>
diff --git a/xml/System.Data.OleDb/OleDbDataReader.xml b/xml/System.Data.OleDb/OleDbDataReader.xml index 09cd82d3c68..1e6364113a9 100644 --- a/xml/System.Data.OleDb/OleDbDataReader.xml +++ b/xml/System.Data.OleDb/OleDbDataReader.xml @@ -73,7 +73,7 @@ Changes made to a result set by another process or thread while data is being read may be visible to the user of the . However, the precise behavior is timing dependent. - and are the only properties that you can call after the is closed. Although the property may be accessed while the exists, always call before returning the value of to guarantee an accurate return value. + and are the only properties that you can call after the is closed. Although the property may be accessed while the exists, always call before returning the value of to guarantee an accurate return value. @@ -1837,7 +1837,7 @@ property is not set until all rows are read and you close the . + The property is not set until all rows are read and you close the . The value of this property is cumulative. For example, if two records are inserted in batch mode, the value of is two. diff --git a/xml/System.Data.OleDb/OleDbInfoMessageEventArgs.xml b/xml/System.Data.OleDb/OleDbInfoMessageEventArgs.xml index e235cd917d2..69d17290f03 100644 --- a/xml/System.Data.OleDb/OleDbInfoMessageEventArgs.xml +++ b/xml/System.Data.OleDb/OleDbInfoMessageEventArgs.xml @@ -41,11 +41,11 @@ Provides data for the event. This class cannot be inherited. - event contains an collection with warnings sent from the data source. - + event contains an collection with warnings sent from the data source. + ]]> @@ -75,11 +75,11 @@ Gets the HRESULT following the ANSI SQL standard for the database. The HRESULT, which identifies the source of the error, if the error can be issued from more than one place. - property of the first in the collection. - + property of the first in the collection. + ]]> @@ -136,11 +136,11 @@ Gets the full text of the error sent from the data source. The full text of the error. - property of the first in the collection. - + property of the first in the collection. + ]]> @@ -177,11 +177,11 @@ Gets the name of the object that generated the error. The name of the object that generated the error. - property of the first in the collection. - + property of the first in the collection. + ]]> diff --git a/xml/System.Data.OleDb/OleDbParameter.xml b/xml/System.Data.OleDb/OleDbParameter.xml index 8112e9799f4..3ddcbab66f6 100644 --- a/xml/System.Data.OleDb/OleDbParameter.xml +++ b/xml/System.Data.OleDb/OleDbParameter.xml @@ -888,9 +888,9 @@ public void CreateOleDbParameter() property is only used for decimal and numeric input parameters. + The property is only used for decimal and numeric input parameters. - The property should be set only for `Decimal` and `Numeric` parameters prior to calling the method of the . + The property should be set only for `Decimal` and `Numeric` parameters prior to calling the method of the . Setting this property to a value other than the value in the database depends on the implementation of the data provider and may return an error code, truncate, or round data. @@ -1046,7 +1046,7 @@ public void CreateOleDbParameter() property is only used for decimal and numeric input parameters before calling the method of the and to specify numeric output parameters. + The property is only used for decimal and numeric input parameters before calling the method of the and to specify numeric output parameters. Setting this property to a value other than the value in the database depends on the implementation of the data provider and may return an error code, truncate, or round data. @@ -1131,9 +1131,9 @@ public void CreateOleDbParameter() property is used for binary and string types. + The property is used for binary and string types. - For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. + For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first 100 characters. @@ -1226,7 +1226,7 @@ public void CreateOleDbParameter() ## Remarks When is set to anything other than an empty string, the value of the parameter is retrieved from the column with the name. If is set to `Input`, the value is taken from the . If is set to `Output`, the value is taken from the data source. A of `InputOutput` is a combination of both. - For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). @@ -1347,7 +1347,7 @@ FieldName = @OriginalFieldName during an update operation to determine whether the parameter value is set to `Current` or `Original`. This lets primary keys be updated. This property is set to the version of the used by the property, or the method of the object. + Used by during an update operation to determine whether the parameter value is set to `Current` or `Original`. This lets primary keys be updated. This property is set to the version of the used by the property, or the method of the object. @@ -1506,7 +1506,7 @@ public void CreateOleDbParameter() Both the and properties can be inferred by setting the Value. - The property is overwritten by the Update method of . + The property is overwritten by the Update method of . diff --git a/xml/System.Data.OleDb/OleDbPermission.xml b/xml/System.Data.OleDb/OleDbPermission.xml index cb513f4b902..d8733494615 100644 --- a/xml/System.Data.OleDb/OleDbPermission.xml +++ b/xml/System.Data.OleDb/OleDbPermission.xml @@ -45,14 +45,14 @@ Enables the .NET Framework Data Provider for OLE DB to help make sure that a user has a security level sufficient to access an OLE DB data source. - @@ -187,11 +187,11 @@ Indicates whether a blank password is allowed. Initializes a new instance of the class. - enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. - + enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. + ]]> diff --git a/xml/System.Data.OracleClient/OracleBFile.xml b/xml/System.Data.OracleClient/OracleBFile.xml index 83b5a28d413..a11430bbf21 100644 --- a/xml/System.Data.OracleClient/OracleBFile.xml +++ b/xml/System.Data.OracleClient/OracleBFile.xml @@ -170,7 +170,7 @@ object initially have the same values as those of the original object. However, after the is complete, each object is independent from the other. For example, changing the value of the property on the original does not change the value of on the copy. + The properties of the new object initially have the same values as those of the original object. However, after the is complete, each object is independent from the other. For example, changing the value of the property on the original does not change the value of on the copy. ]]> @@ -379,7 +379,7 @@ - The file name of the underlying physical file, which is located in the directory associated with the DIRECTORY object. - The property returns the name of the DIRECTORY object from the Oracle database. + The property returns the name of the DIRECTORY object from the Oracle database. For more information about creating and using an Oracle `BFILE`, see the appropriate topic in your Oracle documentation. @@ -796,7 +796,7 @@ using (dataReader) { ## Remarks The operation must be within a transaction to succeed. Simply calling on a `BFILE` associates the object with a different file, but does not update the Oracle table. To update the Oracle table after calling , you must call the `Update` method of the and then commit the transaction. - Once you retrieve the or property, they are cached in the object and are unaffected by any cloned objects' calls to , or by any changes to the `BFILE` in the database. In other words, they might not represent the actual values of the `BFILE` object in the server. + Once you retrieve the or property, they are cached in the object and are unaffected by any cloned objects' calls to , or by any changes to the `BFILE` in the database. In other words, they might not represent the actual values of the `BFILE` object in the server. Furthermore, retrieving either property ( or ) causes both property values to be retrieved from the server and cached in the object. @@ -881,7 +881,7 @@ using (dataReader) { property reads the entire `BFILE` at one time. + The property reads the entire `BFILE` at one time. > [!NOTE] > A benefit of using `BFILE`s is the ability to retrieve large amounts of data in chunks at the client. However, when you use , you obtain all the data for the BFILE column as one contiguous chunk, which can significantly increase application overhead. diff --git a/xml/System.Data.OracleClient/OracleBinary.xml b/xml/System.Data.OracleClient/OracleBinary.xml index bbec56124c5..b03558701d8 100644 --- a/xml/System.Data.OracleClient/OracleBinary.xml +++ b/xml/System.Data.OracleClient/OracleBinary.xml @@ -25,11 +25,11 @@ Represents a variable-length stream of binary data to be stored in or retrieved from a database. - object, call the method. - + object, call the method. + ]]> @@ -83,24 +83,24 @@ The object to be compared to this structure. Compares this object to the supplied object and returns an indication of their relative values. - A signed number indicating the relative values of this structure and the object. - - Return Value - - Condition - - Less than zero - - The value of this object is less than the object. - - Zero - - This object is the same as the object. - - Greater than zero - - This object is greater than the object, or the object is a null reference. - + A signed number indicating the relative values of this structure and the object. + + Return Value + + Condition + + Less than zero + + The value of this object is less than the object. + + Zero + + This object is the same as the object. + + Greater than zero + + This object is greater than the object, or the object is a null reference. + To be added. @@ -334,11 +334,11 @@ Gets the single byte from the property located at the position indicated by the integer parameter, . If indicates a position beyond the end of the byte array, an exception is raised. The byte located at the position indicated by the integer parameter. - property and the `Length` property before reading `this`. - + property and the `Length` property before reading `this`. + ]]> @@ -364,11 +364,11 @@ Gets the length in bytes of the property. This property is read-only. The length of the binary data in the property. - property before reading the `Length` property. - + property before reading the `Length` property. + ]]> @@ -480,11 +480,11 @@ Represents a null value that can be assigned to the property of an structure. - @@ -517,15 +517,15 @@ Concatenates the two parameters to create a new structure. The concatenated values of the and parameters. - ]]> @@ -586,13 +586,13 @@ Gets the contents of the property of the parameter as an array of bytes. An array of bytes. - to convert the to a binary object. - + to convert the to a binary object. + The equivalent method for this operator is ]]> @@ -800,11 +800,11 @@ Gets the value of the structure. This property is read-only. The value of the structure. - property before reading the `Value` property. - + property before reading the `Value` property. + ]]> diff --git a/xml/System.Data.OracleClient/OracleCommand.xml b/xml/System.Data.OracleClient/OracleCommand.xml index dea650f883a..81038049799 100644 --- a/xml/System.Data.OracleClient/OracleCommand.xml +++ b/xml/System.Data.OracleClient/OracleCommand.xml @@ -75,12 +75,12 @@ ||Retrieves a single value (for example, an aggregate value) from a database as a .NET Framework data type.| ||Retrieves a single value (for example, an aggregate value) from a database as an Oracle-specific data type.| - You can reset the property and reuse the object. + You can reset the property and reuse the object. If execution of the command results in a fatal , the may close. However, the user can reopen the connection and continue. > [!NOTE] -> Unlike the **Command** object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), the object does not support a property. Setting a command timeout has no effect and the value returned is always zero. +> Unlike the **Command** object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), the object does not support a property. Setting a command timeout has no effect and the value returned is always zero. ]]> @@ -342,11 +342,11 @@ property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the Execute methods. + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the Execute methods. The .NET Framework Data Provider for Oracle does not support the question mark (?) placeholder for passing parameters to an SQL statement called by an of `CommandType.Text`. In this case, named parameters must be used. - When using named parameters in an SQL statement called by an of `CommandType.Text`, you must precede the parameter name with a colon (:). However, in a stored procedure, or when referring to a named parameter elsewhere in your code (for example, when adding objects to the property), do not precede the named parameter with a colon (:). The .NET Framework Data Provider for Oracle supplies the colon automatically. + When using named parameters in an SQL statement called by an of `CommandType.Text`, you must precede the parameter name with a colon (:). However, in a stored procedure, or when referring to a named parameter elsewhere in your code (for example, when adding objects to the property), do not precede the named parameter with a colon (:). The .NET Framework Data Provider for Oracle supplies the colon automatically. ]]> @@ -390,7 +390,7 @@ is generated if the assigned property value is less than 0. + An is generated if the assigned property value is less than 0. ]]> @@ -437,13 +437,13 @@ property is set to `StoredProcedure`, you should set the property to the full Oracle call syntax. The command then executes this stored procedure when you call one of the Execute methods (for example, or ). + When the property is set to `StoredProcedure`, you should set the property to the full Oracle call syntax. The command then executes this stored procedure when you call one of the Execute methods (for example, or ). The , and properties cannot be set if the current connection is performing an execute or fetch operation. The .NET Framework Data Provider for Oracle does not support the question mark (?) placeholder for passing parameters to an SQL statement called by an of `CommandType.Text`. In this case, named parameters must be used. - When using named parameters in an SQL statement called by an of `CommandType.Text`, you must precede the parameter name with a colon (:). However, in a stored procedure, or when referring to a named parameter elsewhere in your code (for example, when adding objects to the property), do not precede the named parameter with a colon (:). The .NET Framework Data Provider for Oracle supplies the colon automatically. + When using named parameters in an SQL statement called by an of `CommandType.Text`, you must precede the parameter name with a colon (:). However, in a stored procedure, or when referring to a named parameter elsewhere in your code (for example, when adding objects to the property), do not precede the named parameter with a colon (:). The .NET Framework Data Provider for Oracle supplies the colon automatically. ]]> @@ -495,7 +495,7 @@ ## Remarks You cannot set the , , and properties if the current connection is performing an execute or fetch operation. - If you set while a transaction is in progress and the property is not null, an is generated. If you set after the transaction has been committed or rolled back, and the property is not null, the property is then set to a null value. + If you set while a transaction is in progress and the property is not null, an is generated. If you set after the transaction has been committed or rolled back, and the property is not null, the property is then set to a null value. ]]> @@ -858,7 +858,7 @@ property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command then executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command then executes this stored procedure when you call . More than one can be open at any given time. @@ -898,7 +898,7 @@ ## Remarks If you expect your SQL statement to return only a single row, specifying `SingleRow` as the value may improve application performance. - When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command then executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command then executes this stored procedure when you call . The supports a special mode that enables large binary values to be read efficiently. For more information, see the `SequentialAccess` setting for . @@ -979,11 +979,11 @@ property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the Execute methods. + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the Execute methods. The .NET Framework Data Provider for Oracle does not support the question mark (?) placeholder for passing parameters to an SQL statement called by an of `CommandType.Text`. In this case, named parameters must be used. - When using named parameters in an SQL statement called by an of `CommandType.Text`, you must precede the parameter name with a colon (:). However, in a stored procedure, or when referring to a named parameter elsewhere in your code (for example, when adding objects to the property), do not precede the named parameter with a colon (:). The .NET Framework Data Provider for Oracle supplies the colon automatically. + When using named parameters in an SQL statement called by an of `CommandType.Text`, you must precede the parameter name with a colon (:). However, in a stored procedure, or when referring to a named parameter elsewhere in your code (for example, when adding objects to the property), do not precede the named parameter with a colon (:). The .NET Framework Data Provider for Oracle supplies the colon automatically. ]]> @@ -1190,7 +1190,7 @@ For more information, see . property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to an object that is not connected to the same as the object, an exception will be thrown the next time you attempt to execute a statement. + You cannot set the property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to an object that is not connected to the same as the object, an exception will be thrown the next time you attempt to execute a statement. ]]> diff --git a/xml/System.Data.OracleClient/OracleCommandBuilder.xml b/xml/System.Data.OracleClient/OracleCommandBuilder.xml index aff355ca8c4..04b7cd25dd9 100644 --- a/xml/System.Data.OracleClient/OracleCommandBuilder.xml +++ b/xml/System.Data.OracleClient/OracleCommandBuilder.xml @@ -35,11 +35,11 @@ ## Remarks This type is deprecated and will be removed in a future version of the .NET Framework. For more information, see [Oracle and ADO.NET](/dotnet/framework/data/adonet/oracle-and-adonet). - The does not automatically generate the SQL statements required to reconcile changes made to a associated with the database. However, you can create an object that generates SQL statements for single-table updates by setting the property of the . Then, the generates any additional SQL statements that you do not set. + The does not automatically generate the SQL statements required to reconcile changes made to a associated with the database. However, you can create an object that generates SQL statements for single-table updates by setting the property of the . Then, the generates any additional SQL statements that you do not set. The relationship between an and its corresponding is always one-to-one. To create this correspondence, you set the property of the object. This causes the to register itself as a listener, which produces the output of events that affect the . - To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata. + To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata. The also uses the , and properties referenced by the . diff --git a/xml/System.Data.OracleClient/OracleConnection.xml b/xml/System.Data.OracleClient/OracleConnection.xml index ee19ca67827..16a7dcce7b2 100644 --- a/xml/System.Data.OracleClient/OracleConnection.xml +++ b/xml/System.Data.OracleClient/OracleConnection.xml @@ -54,7 +54,7 @@ An application that creates an instance of the object can set declarative or imperative security demands that require all direct and indirect callers to have adequate permission to the code. creates security demands by using the object. Users can verify that their code has adequate permissions by using the object. Users and administrators can also use the Code Access Security Policy Tool (Caspol.exe) to modify security policy at the machine, user, and enterprise levels. For more information, see [Security](/dotnet/standard/security/). > [!NOTE] -> Unlike the **Connection** object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either as a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. +> Unlike the **Connection** object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either as a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. If the object goes out of scope, it remains open. Therefore, you should always close objects by calling or **Dispose**, or by using the object within a `Using` statement. Otherwise, the garbage collection might not free them immediately. Such delays can cause errors if the maximum number of connections is reached while a number of connections are waiting to be deleted by the garbage collector. By contrast, closing the connections by calling uses native resources more efficiently, enhancing scalability and improving overall application performance. To ensure that connections are always closed, open the connection inside of a `Using` block. @@ -262,7 +262,7 @@ The `value` parameter must contain a valid database name, and cannot contain a null value, an empty string (""), or a string with only blank characters. > [!NOTE] -> Unlike the **Connection** object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either as a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. +> Unlike the **Connection** object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either as a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. ]]> @@ -440,9 +440,9 @@ ## Remarks The can be set only when the connection is closed. - You can use the property to connect to a database. + You can use the property to connect to a database. - Many of the settings specified in the string have corresponding read-only properties (for example, `Data Source=MyServer`, which corresponds to the property). When the connection string is set, all of these properties are updated, unless an error is detected, in which case none of the properties are updated. properties return only default settings or those settings specified in the . + Many of the settings specified in the string have corresponding read-only properties (for example, `Data Source=MyServer`, which corresponds to the property). When the connection string is set, all of these properties are updated, unless an error is detected, in which case none of the properties are updated. properties return only default settings or those settings specified in the . Resetting the on a closed connection resets all connection string values (and related properties), including the password. @@ -527,7 +527,7 @@ You can set the amount of time a connection waits to time out by using the `Connect Timeout` or `Connection Timeout` keywords in the connection string. A value of 0 indicates no limit, and should be avoided in a because an attempt to connect waits indefinitely. > [!NOTE] -> Unlike the `Connection` object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either with a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. +> Unlike the `Connection` object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either with a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. ]]> @@ -615,10 +615,10 @@ property updates dynamically. If you change the current database using a SQL statement or the method, an informational message is sent and the property is updated automatically. + The property updates dynamically. If you change the current database using a SQL statement or the method, an informational message is sent and the property is updated automatically. > [!NOTE] -> Unlike the `Connection` object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either with a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. +> Unlike the `Connection` object in the other .NET Framework data providers (SQL Server, OLE DB, and ODBC), does not support a property. Setting a connection time-out either with a property or in the connection string has no effect, and the value returned is always zero. also does not support a property or a method. ]]> @@ -1004,7 +1004,7 @@ property is in Oracle version format. For example, the format for an Oracle8 release is a string in the form "8.1.7.0.0 Oracle8 Release 8.1.7.0.0 - Production." + The property is in Oracle version format. For example, the format for an Oracle8 release is a string in the form "8.1.7.0.0 Oracle8 Release 8.1.7.0.0 - Production." ]]> diff --git a/xml/System.Data.OracleClient/OracleConnectionStringBuilder.xml b/xml/System.Data.OracleClient/OracleConnectionStringBuilder.xml index 8459c11139e..0f8a4f40d3f 100644 --- a/xml/System.Data.OracleClient/OracleConnectionStringBuilder.xml +++ b/xml/System.Data.OracleClient/OracleConnectionStringBuilder.xml @@ -40,7 +40,7 @@ Developers needing to create connection strings as part of applications can use the class to build and modify connection strings. The class also makes it easy to manage connection strings stored in an application configuration file. - The performs checks for valid key/value pairs. Therefore, this class cannot be used to create invalid connection strings. Trying to add invalid pairs will throw an exception. The class maintains a fixed collection of synonyms, and when required, can perform the required translation to convert from a synonym to the corresponding well-known key name. For example, when you use the property to retrieve a value, you can specify a string that contains any synonym for the key you need. See the property for a full list of acceptable synonyms. + The performs checks for valid key/value pairs. Therefore, this class cannot be used to create invalid connection strings. Trying to add invalid pairs will throw an exception. The class maintains a fixed collection of synonyms, and when required, can perform the required translation to convert from a synonym to the corresponding well-known key name. For example, when you use the property to retrieve a value, you can specify a string that contains any synonym for the key you need. See the property for a full list of acceptable synonyms. [!INCLUDE[ROPC warning](~/includes/ropc-warning.md)] @@ -99,7 +99,7 @@ class provides a fixed internal collection of key/value pairs. Even if you supply only a small subset of the possible connection string values in the constructor, the object always provides default values for each key/value pair. When the property of the object is retrieved, the string contains only key/value pairs in which the value is different from the default value for the item. + The class provides a fixed internal collection of key/value pairs. Even if you supply only a small subset of the possible connection string values in the constructor, the object always provides default values for each key/value pair. When the property of the object is retrieved, the string contains only key/value pairs in which the value is different from the default value for the item. ]]> @@ -208,7 +208,7 @@ will use the well-known "Data Source" key. If the value passed in is null when you try to set the property, the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is . + This property corresponds to the "Data Source" and "Server" keys within the connection string. Regardless of which of these values has been supplied within the supplied connection string, the connection string created by the will use the well-known "Data Source" key. If the value passed in is null when you try to set the property, the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is . ]]> @@ -417,7 +417,7 @@ is unspecified, but it is the same order as the associated values in the returned by the property. + The order of the values in the is unspecified, but it is the same order as the associated values in the returned by the property. ]]> @@ -629,7 +629,7 @@ ## Examples - If the value passed in is null when you try to set the property, the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is . + If the value passed in is null when you try to set the property, the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is . ]]> @@ -918,7 +918,7 @@ The collection of keys supported by the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is . + If the value passed in is null when you try to set the property, the property is reset. If the value has not been set and the developer tries to retrieve the property, the return value is . ]]> @@ -948,7 +948,7 @@ The collection of keys supported by the is unspecified, but it is the same order as the associated keys in the returned by the property. Because each instance of the always contains the same fixed set of keys, the property always returns the values corresponding to the fixed set of keys, in the same order as the keys. + The order of the values in the is unspecified, but it is the same order as the associated keys in the returned by the property. Because each instance of the always contains the same fixed set of keys, the property always returns the values corresponding to the fixed set of keys, in the same order as the keys. ]]> diff --git a/xml/System.Data.OracleClient/OracleDataAdapter.xml b/xml/System.Data.OracleClient/OracleDataAdapter.xml index 117d201619a..406c134b36a 100644 --- a/xml/System.Data.OracleClient/OracleDataAdapter.xml +++ b/xml/System.Data.OracleClient/OracleDataAdapter.xml @@ -74,7 +74,7 @@ The serves as a bridge between a **DataSet** and database for retrieving and saving data. The provides this bridge by using to load data from the database into the , and using to send changes made in the back to the data source. - When the fills a , it creates the necessary tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). + When the fills a , it creates the necessary tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using . For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). > [!NOTE] > By default, numeric fields imported to a with are mapped to objects. It is possible to overflow the , and throw an Oracle exception, by importing a non-integral numeric value that is either too large or too high precision for the 's precision limitations. Refer to the description of for more information. @@ -157,7 +157,7 @@ constructor sets the property to the value specified in the `selectCommand` parameter. + This implementation of the constructor sets the property to the value specified in the `selectCommand` parameter. When you create an instance of , the following read/write properties are set to their default values, as shown in the table. @@ -388,9 +388,9 @@ property is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created . + When the property is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created . - During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate the , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate the , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). ]]> @@ -542,12 +542,12 @@ property is assigned to a previously created object, the is not cloned. Instead, maintains a reference to the previously created . + When the property is assigned to a previously created object, the is not cloned. Instead, maintains a reference to the previously created . - During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During an update operation, if is not set and primary key information is present in the , you can use the class to automatically generate , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). > [!NOTE] -> If execution of this command returns rows, these rows may be added to the depending upon how you set the property of the object. +> If execution of this command returns rows, these rows may be added to the depending upon how you set the property of the object. When you update a column with the `LONG RAW` data type, an exception is thrown when you enter a value of `NULL` in the column. The Oracle `LONG RAW` data type is a deprecated type in Oracle version 8.0. To avoid this error, use the `BLOB` data type instead of `LONG RAW`. @@ -971,7 +971,7 @@ property to update a data source with changes from a . This can increase application performance by reducing the number of round-trips to the server. + Use the property to update a data source with changes from a . This can increase application performance by reducing the number of round-trips to the server. Executing an extremely large batch could decrease performance. Therefore, you should test for the optimum batch size setting before you implement your application. @@ -1026,10 +1026,10 @@ ## Remarks When is assigned to a previously created , the is not cloned. Instead, the maintains a reference to the previously created object. - During an update operation, if is not set and primary key information is present in the **DataSet**, you can use the class to automatically generate , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During an update operation, if is not set and primary key information is present in the **DataSet**, you can use the class to automatically generate , and additional commands needed to reconcile the to the database. To do this, set the property of the . The generation logic also requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). > [!NOTE] -> If execution of this command returns rows, these rows may be merged with the depending upon how you set the property of the object. +> If execution of this command returns rows, these rows may be merged with the depending upon how you set the property of the object. When you update a column with the `LONG RAW` data type, an exception is thrown when you enter a value of `NULL` in the column. The Oracle `LONG RAW` data type is a deprecated type in Oracle version 8.0. To avoid this error, use the `BLOB` data type instead of `LONG RAW`. diff --git a/xml/System.Data.OracleClient/OracleDataReader.xml b/xml/System.Data.OracleClient/OracleDataReader.xml index 96d2cdd6baa..b78772d8330 100644 --- a/xml/System.Data.OracleClient/OracleDataReader.xml +++ b/xml/System.Data.OracleClient/OracleDataReader.xml @@ -37,214 +37,214 @@ Provides a way of reading a forward-only stream of data rows from a data source. This class cannot be inherited. - , you must call the method of the object, rather than directly using a constructor. - - Changes made to a resultset by another process or thread while data is being read may be visible to the user of the . - - and are the only properties that you can call after the is closed. In some cases, you must call before you can call . - - More than one can be open at any given time. - - The following two Visual Basic examples demonstrate how to use an to retrieve an Oracle `REF CURSOR`. These examples use tables that are defined in the Oracle Scott/Tiger schema, and require the following PL/SQL package and package body. You must create these on your server to use the examples. - - Create the following Oracle package on the Oracle server. - -``` -CREATE OR REPLACE PACKAGE CURSPKG AS - TYPE T_CURSOR IS REF CURSOR; - PROCEDURE OPEN_ONE_CURSOR (N_EMPNO IN NUMBER, - IO_CURSOR IN OUT T_CURSOR); - PROCEDURE OPEN_TWO_CURSORS (EMPCURSOR OUT T_CURSOR, - DEPTCURSOR OUT T_CURSOR); -END CURSPKG; -/ -``` - - Create the following Oracle package body on the Oracle server. - -``` - -CREATE OR REPLACE PACKAGE BODY CURSPKG AS - PROCEDURE OPEN_ONE_CURSOR (N_EMPNO IN NUMBER, - IO_CURSOR OUT T_CURSOR) - IS - V_CURSOR T_CURSOR; - BEGIN - IF N_EMPNO <> 0 THEN - OPEN V_CURSOR FOR - SELECT EMP.EMPNO, EMP.ENAME, DEPT.DEPTNO, DEPT.DNAME - FROM EMP, DEPT - WHERE EMP.DEPTNO = DEPT.DEPTNO - AND EMP.EMPNO = N_EMPNO; - ELSE - OPEN V_CURSOR FOR - SELECT EMP.EMPNO, EMP.ENAME, DEPT.DEPTNO, DEPT.DNAME - FROM EMP, DEPT - WHERE EMP.DEPTNO = DEPT.DEPTNO; - END IF; - IO_CURSOR := V_CURSOR; - END OPEN_ONE_CURSOR; - PROCEDURE OPEN_TWO_CURSORS (EMPCURSOR OUT T_CURSOR, - DEPTCURSOR OUT T_CURSOR) - IS - V_CURSOR1 T_CURSOR; - V_CURSOR2 T_CURSOR; - BEGIN - OPEN V_CURSOR1 FOR SELECT * FROM EMP; - OPEN V_CURSOR2 FOR SELECT * FROM DEPT; - EMPCURSOR := V_CURSOR1; - DEPTCURSOR := V_CURSOR2; - END OPEN_TWO_CURSORS; -END CURSPKG; -/ -``` - - This Visual Basic example executes a PL/SQL stored procedure that returns a `REF CURSOR` parameter, and reads the value as an . - -```vb -Private Sub ReadOracleData(ByVal connectionString As String) - Dim connection As New OracleConnection(connectionString) - Dim command As New OracleCommand() - Dim reader As OracleDataReader - - connection.Open() - command.Connection = connection - command.CommandText = "CURSPKG.OPEN_ONE_CURSOR" - command.CommandType = CommandType.StoredProcedure - command.Parameters.Add(New OracleParameter("N_EMPNO", OracleType.Number)).Value = 7369 - command.Parameters.Add(New OracleParameter("IO_CURSOR", OracleType.Cursor)).Direction = ParameterDirection.Output - - reader = command.ExecuteReader() - While (reader.Read()) - ' Do something with the values. - End While - reader.Close() - connection.Close() -End Sub -``` - - This Visual Basic example executes a PL/SQL stored procedure that returns two `REF CURSOR` parameters, and reads the values using an . - -```vb -Private Sub ReadOracleData(ByVal connectionString As String) - Dim dataSet As New DataSet() - Dim connection As New OracleConnection(connectionString) - Dim command As New OracleCommand() - Dim reader As OracleDataReader - - connection.Open() - command.Connection = connection - command.CommandText = "CURSPKG.OPEN_TWO_CURSORS" - command.CommandType = CommandType.StoredProcedure - command.Parameters.Add(New OracleParameter("EMPCURSOR", OracleType.Cursor)).Direction = ParameterDirection.Output - command.Parameters.Add(New OracleParameter("DEPTCURSOR", OracleType.Cursor)).Direction = ParameterDirection.Output - - reader = command.ExecuteReader(CommandBehavior.CloseConnection) - While (reader.Read()) - ' Do something with the values. - End While - reader.NextResult() - While (reader.Read()) - ' Do something with the values. - End While - reader.Close() - connection.Close() - End Sub -``` - - This C# example creates an Oracle table and loads it with data. You must run this example prior to running the subsequent example, which demonstrates using an to access the data using OracleType structures. - -```csharp -public void Setup(string connectionString) -{ - OracleConnection connection = new OracleConnection(connectionString); - try - { - connection.Open(); - OracleCommand command = connection.CreateCommand(); - command.CommandText ="CREATE TABLE OracleTypesTable (MyVarchar2 varchar2(3000),MyNumber number(28,4) PRIMARY KEY,MyDate date, MyRaw raw(255))"; - command.ExecuteNonQuery(); - command.CommandText ="INSERT INTO OracleTypesTable VALUES ('test', 2, to_date('2000-01-11 12:54:01','yyyy-mm-dd hh24:mi:ss'), '0001020304')"; - command.ExecuteNonQuery(); - command.CommandText="SELECT * FROM OracleTypesTable"; - } - catch(Exception) - { - } - finally - { - connection.Close(); - } -} -``` - - This C# example uses an to access data, and uses several structures to display the data. - -```csharp -public void ReadOracleTypesExample(string connectionString) -{ - OracleConnection connection = new OracleConnection(connectionString); - connection.Open(); - OracleCommand command = connection.CreateCommand(); - try - { - command.CommandText = "SELECT * FROM OracleTypesTable"; - OracleDataReader reader = command.ExecuteReader(); - reader.Read(); - //Using the Oracle specific getters for each type is faster than - //using GetOracleValue. - //First column, MyVarchar2, is a VARCHAR2 data type in Oracle Server - //and maps to OracleString. - OracleString oraclestring1 = reader.GetOracleString(0); - Console.WriteLine("OracleString " + oraclestring1.ToString()); - - //Second column, MyNumber, is a NUMBER data type in Oracle Server - //and maps to OracleNumber. - OracleNumber oraclenumber1 = reader.GetOracleNumber(1); - Console.WriteLine("OracleNumber " + oraclenumber1.ToString()); - - //Third column, MyDate, is a DATA data type in Oracle Server - //and maps to OracleDateTime. - OracleDateTime oracledatetime1 = reader.GetOracleDateTime(2); - Console.WriteLine("OracleDateTime " + oracledatetime1.ToString()); - - //Fourth column, MyRaw, is a RAW data type in Oracle Server and - //maps to OracleBinary. - OracleBinary oraclebinary1 = reader.GetOracleBinary(3); - - //Calling value on a null OracleBinary throws - //OracleNullValueException; therefore, check for a null value. - if (oraclebinary1.IsNull==false) - { - foreach(byte b in oraclebinary1.Value) - { - Console.WriteLine("byte " + b.ToString()); - } - } - reader.Close(); - } - catch(Exception e) - { - Console.WriteLine(e.ToString()); - } - finally - { - connection.Close(); - } -} -``` - - - -## Examples - The following example creates an , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , then the . - + , you must call the method of the object, rather than directly using a constructor. + + Changes made to a resultset by another process or thread while data is being read may be visible to the user of the . + + and are the only properties that you can call after the is closed. In some cases, you must call before you can call . + + More than one can be open at any given time. + + The following two Visual Basic examples demonstrate how to use an to retrieve an Oracle `REF CURSOR`. These examples use tables that are defined in the Oracle Scott/Tiger schema, and require the following PL/SQL package and package body. You must create these on your server to use the examples. + + Create the following Oracle package on the Oracle server. + +``` +CREATE OR REPLACE PACKAGE CURSPKG AS + TYPE T_CURSOR IS REF CURSOR; + PROCEDURE OPEN_ONE_CURSOR (N_EMPNO IN NUMBER, + IO_CURSOR IN OUT T_CURSOR); + PROCEDURE OPEN_TWO_CURSORS (EMPCURSOR OUT T_CURSOR, + DEPTCURSOR OUT T_CURSOR); +END CURSPKG; +/ +``` + + Create the following Oracle package body on the Oracle server. + +``` + +CREATE OR REPLACE PACKAGE BODY CURSPKG AS + PROCEDURE OPEN_ONE_CURSOR (N_EMPNO IN NUMBER, + IO_CURSOR OUT T_CURSOR) + IS + V_CURSOR T_CURSOR; + BEGIN + IF N_EMPNO <> 0 THEN + OPEN V_CURSOR FOR + SELECT EMP.EMPNO, EMP.ENAME, DEPT.DEPTNO, DEPT.DNAME + FROM EMP, DEPT + WHERE EMP.DEPTNO = DEPT.DEPTNO + AND EMP.EMPNO = N_EMPNO; + ELSE + OPEN V_CURSOR FOR + SELECT EMP.EMPNO, EMP.ENAME, DEPT.DEPTNO, DEPT.DNAME + FROM EMP, DEPT + WHERE EMP.DEPTNO = DEPT.DEPTNO; + END IF; + IO_CURSOR := V_CURSOR; + END OPEN_ONE_CURSOR; + PROCEDURE OPEN_TWO_CURSORS (EMPCURSOR OUT T_CURSOR, + DEPTCURSOR OUT T_CURSOR) + IS + V_CURSOR1 T_CURSOR; + V_CURSOR2 T_CURSOR; + BEGIN + OPEN V_CURSOR1 FOR SELECT * FROM EMP; + OPEN V_CURSOR2 FOR SELECT * FROM DEPT; + EMPCURSOR := V_CURSOR1; + DEPTCURSOR := V_CURSOR2; + END OPEN_TWO_CURSORS; +END CURSPKG; +/ +``` + + This Visual Basic example executes a PL/SQL stored procedure that returns a `REF CURSOR` parameter, and reads the value as an . + +```vb +Private Sub ReadOracleData(ByVal connectionString As String) + Dim connection As New OracleConnection(connectionString) + Dim command As New OracleCommand() + Dim reader As OracleDataReader + + connection.Open() + command.Connection = connection + command.CommandText = "CURSPKG.OPEN_ONE_CURSOR" + command.CommandType = CommandType.StoredProcedure + command.Parameters.Add(New OracleParameter("N_EMPNO", OracleType.Number)).Value = 7369 + command.Parameters.Add(New OracleParameter("IO_CURSOR", OracleType.Cursor)).Direction = ParameterDirection.Output + + reader = command.ExecuteReader() + While (reader.Read()) + ' Do something with the values. + End While + reader.Close() + connection.Close() +End Sub +``` + + This Visual Basic example executes a PL/SQL stored procedure that returns two `REF CURSOR` parameters, and reads the values using an . + +```vb +Private Sub ReadOracleData(ByVal connectionString As String) + Dim dataSet As New DataSet() + Dim connection As New OracleConnection(connectionString) + Dim command As New OracleCommand() + Dim reader As OracleDataReader + + connection.Open() + command.Connection = connection + command.CommandText = "CURSPKG.OPEN_TWO_CURSORS" + command.CommandType = CommandType.StoredProcedure + command.Parameters.Add(New OracleParameter("EMPCURSOR", OracleType.Cursor)).Direction = ParameterDirection.Output + command.Parameters.Add(New OracleParameter("DEPTCURSOR", OracleType.Cursor)).Direction = ParameterDirection.Output + + reader = command.ExecuteReader(CommandBehavior.CloseConnection) + While (reader.Read()) + ' Do something with the values. + End While + reader.NextResult() + While (reader.Read()) + ' Do something with the values. + End While + reader.Close() + connection.Close() + End Sub +``` + + This C# example creates an Oracle table and loads it with data. You must run this example prior to running the subsequent example, which demonstrates using an to access the data using OracleType structures. + +```csharp +public void Setup(string connectionString) +{ + OracleConnection connection = new OracleConnection(connectionString); + try + { + connection.Open(); + OracleCommand command = connection.CreateCommand(); + command.CommandText ="CREATE TABLE OracleTypesTable (MyVarchar2 varchar2(3000),MyNumber number(28,4) PRIMARY KEY,MyDate date, MyRaw raw(255))"; + command.ExecuteNonQuery(); + command.CommandText ="INSERT INTO OracleTypesTable VALUES ('test', 2, to_date('2000-01-11 12:54:01','yyyy-mm-dd hh24:mi:ss'), '0001020304')"; + command.ExecuteNonQuery(); + command.CommandText="SELECT * FROM OracleTypesTable"; + } + catch(Exception) + { + } + finally + { + connection.Close(); + } +} +``` + + This C# example uses an to access data, and uses several structures to display the data. + +```csharp +public void ReadOracleTypesExample(string connectionString) +{ + OracleConnection connection = new OracleConnection(connectionString); + connection.Open(); + OracleCommand command = connection.CreateCommand(); + try + { + command.CommandText = "SELECT * FROM OracleTypesTable"; + OracleDataReader reader = command.ExecuteReader(); + reader.Read(); + //Using the Oracle specific getters for each type is faster than + //using GetOracleValue. + //First column, MyVarchar2, is a VARCHAR2 data type in Oracle Server + //and maps to OracleString. + OracleString oraclestring1 = reader.GetOracleString(0); + Console.WriteLine("OracleString " + oraclestring1.ToString()); + + //Second column, MyNumber, is a NUMBER data type in Oracle Server + //and maps to OracleNumber. + OracleNumber oraclenumber1 = reader.GetOracleNumber(1); + Console.WriteLine("OracleNumber " + oraclenumber1.ToString()); + + //Third column, MyDate, is a DATA data type in Oracle Server + //and maps to OracleDateTime. + OracleDateTime oracledatetime1 = reader.GetOracleDateTime(2); + Console.WriteLine("OracleDateTime " + oracledatetime1.ToString()); + + //Fourth column, MyRaw, is a RAW data type in Oracle Server and + //maps to OracleBinary. + OracleBinary oraclebinary1 = reader.GetOracleBinary(3); + + //Calling value on a null OracleBinary throws + //OracleNullValueException; therefore, check for a null value. + if (oraclebinary1.IsNull==false) + { + foreach(byte b in oraclebinary1.Value) + { + Console.WriteLine("byte " + b.ToString()); + } + } + reader.Close(); + } + catch(Exception e) + { + Console.WriteLine(e.ToString()); + } + finally + { + connection.Close(); + } +} +``` + + + +## Examples + The following example creates an , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , then the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OracleDataReader/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleDataReader/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.OracleClient/OracleDataReader/Overview/source.vb" id="Snippet1"::: + ]]> @@ -278,14 +278,14 @@ public void ReadOracleTypesExample(string connectionString) Closes the object. - can be open at any given time. - + can be open at any given time. + > [!CAUTION] -> Do not call `Close` or `Dispose` on a connection, a `DataReader`, or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). - +> Do not call `Close` or `Dispose` on a connection, a `DataReader`, or any other managed object in the `Finalize` method of your class. In a finalizer, you should only release unmanaged resources that your class owns directly. If your class does not own any unmanaged resources, do not include a `Finalize` method in your class definition. For more information, see [Garbage Collection](/dotnet/standard/garbage-collection/). + ]]> @@ -317,11 +317,11 @@ public void ReadOracleTypesExample(string connectionString) Gets a value indicating the depth of nesting for the current row. The depth of nesting for the current row. - @@ -377,13 +377,13 @@ public void ReadOracleTypesExample(string connectionString) Gets the number of columns in the current row. When not positioned in a valid record set, 0; otherwise the number of columns in the current record. The default is -1. - to exclude hidden fields. - - After executing a query that does not return rows, returns 0. - + to exclude hidden fields. + + After executing a query that does not return rows, returns 0. + ]]> There is no current connection to a data source. @@ -422,11 +422,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a Boolean. A Boolean that is the value of the column. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -465,11 +465,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a byte. The value of the specified column as a byte. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -516,13 +516,13 @@ public void ReadOracleTypesExample(string connectionString) Reads a stream of bytes from the specified column offset into the buffer as an array, starting at the given buffer offset. The actual number of bytes read. - returns the number of available bytes in the field. In most cases this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting of . - - If you pass a buffer that is a null value, returns the length of the field in bytes. - + returns the number of available bytes in the field. In most cases this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetBytes` has already been used to obtain bytes from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting of . + + If you pass a buffer that is a null value, returns the length of the field in bytes. + ]]> @@ -560,11 +560,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a character. The value of the specified column as a character. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -611,13 +611,13 @@ public void ReadOracleTypesExample(string connectionString) Reads a stream of characters from the specified column offset into the buffer as an array, starting at the given buffer offset. The actual number of characters read. - returns the number of available characters in the field. In most cases this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetChars` has already been used to obtain characters from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting of . - - If you pass a buffer that is a null value. returns the length of the field in characters. - + returns the number of available characters in the field. In most cases this is the exact length of the field. However, the number returned may be less than the true length of the field if `GetChars` has already been used to obtain characters from the field. This may be the case, for example, if the is reading a large data structure into a buffer. For more information, see the `SequentialAccess` setting of . + + If you pass a buffer that is a null value. returns the length of the field in characters. + ]]> @@ -718,11 +718,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a object. The value of the specified column as a object. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -761,11 +761,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a object. The value of the specified column as a object. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -804,11 +804,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a double-precision floating point number. The value of the specified column as a double-precision floating point number. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -835,11 +835,11 @@ public void ReadOracleTypesExample(string connectionString) Returns an that can be used to iterate through the rows in the data reader. An that can be used to iterate through the rows in the data reader. - @@ -912,11 +912,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a single-precision floating-point number. The value of the specified column as a single-precision floating-point number. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -955,11 +955,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a globally-unique identifier (GUID). The value of the specified column as a GUID. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -998,11 +998,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a 16-bit signed integer. The value of the specified column as a 16-bit signed integer. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1041,11 +1041,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a 32-bit signed integer. The value of the specified column as a 32-bit signed integer. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1084,11 +1084,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as a 64-bit signed integer. The value of the specified column as a 64-bit signed integer. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1155,11 +1155,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as an object. The value of the specified column as an object. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1190,11 +1190,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as an object. The value of the specified column as an object. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1225,11 +1225,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as an object. The value of the specified column as an object. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1260,11 +1260,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as an object. The value of the specified column as an object. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1295,11 +1295,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as an object. The value of the specified column as an object. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1330,11 +1330,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as an object. The value of the specified column as an object. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1365,11 +1365,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as an object. The value of the specified column as an object. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1400,11 +1400,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the specified column as an object. The value of the specified column as an object. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1435,11 +1435,11 @@ public void ReadOracleTypesExample(string connectionString) Gets the value of the column at the specified ordinal in its Oracle format. The Oracle value to return. - for null database columns. - + for null database columns. + ]]> @@ -1469,15 +1469,15 @@ public void ReadOracleTypesExample(string connectionString) Gets all the attribute columns in the current row in Oracle format. The number of instances of in the array. - method provides an efficient means for retrieving all columns, rather than retrieving each column individually. - - You can pass an array that contains fewer than the number of columns contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns contained in the resulting row. - - This method returns for null database columns. - + method provides an efficient means for retrieving all columns, rather than retrieving each column individually. + + You can pass an array that contains fewer than the number of columns contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns contained in the resulting row. + + This method returns for null database columns. + ]]> @@ -1515,62 +1515,62 @@ public void ReadOracleTypesExample(string connectionString) Gets the column ordinal, given the name of the column. The zero-based column ordinal. - performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. The method throws an `IndexOutOfRange` exception if the zero-based column ordinal is not found. - - is kana-width insensitive. - - Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call within a loop. Instead, call once and then assign the results to an integer variable for use within the loop. - - - -## Examples - The following example demonstrates how to use the method. - -```vb -Public Sub ReadOracleData(ByVal connectionString As String) - - Dim queryString As String = "SELECT OrderID, CustomerID FROM Orders" - Dim connection As New OracleConnection(connectionString) - Dim command As New OracleCommand(queryString, connectionString) - - connection.Open() - - Dim reader As OracleDataReader = command.ExecuteReader() - - Dim custIdCol As Integer = reader.GetOrdinal("CustomerID") - - Do While reader.Read() - Console.WriteLine("CustomerID = {0}", reader.GetString(custIdCol)) - Loop - - reader.Close() - connection.Close() -End Sub -``` - -```csharp -public void ReadOracleData(string connectionString) -{ - string queryString = "SELECT OrderID, CustomerID FROM Orders"; - OracleConnection connection = new OracleConnection(connectionString); - OracleCommand command = new OracleCommand(queryString,connection); - - connection.Open(); - OracleDataReader reader = command.ExecuteReader(); - - int custIdCol = reader.GetOrdinal("CustomerID"); - - while (reader.Read()) - Console.WriteLine("CustomerID = {0}", reader.GetString(custIdCol)); - - reader.Close(); - connection.Close(); -} -``` - + performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. The method throws an `IndexOutOfRange` exception if the zero-based column ordinal is not found. + + is kana-width insensitive. + + Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call within a loop. Instead, call once and then assign the results to an integer variable for use within the loop. + + + +## Examples + The following example demonstrates how to use the method. + +```vb +Public Sub ReadOracleData(ByVal connectionString As String) + + Dim queryString As String = "SELECT OrderID, CustomerID FROM Orders" + Dim connection As New OracleConnection(connectionString) + Dim command As New OracleCommand(queryString, connectionString) + + connection.Open() + + Dim reader As OracleDataReader = command.ExecuteReader() + + Dim custIdCol As Integer = reader.GetOrdinal("CustomerID") + + Do While reader.Read() + Console.WriteLine("CustomerID = {0}", reader.GetString(custIdCol)) + Loop + + reader.Close() + connection.Close() +End Sub +``` + +```csharp +public void ReadOracleData(string connectionString) +{ + string queryString = "SELECT OrderID, CustomerID FROM Orders"; + OracleConnection connection = new OracleConnection(connectionString); + OracleCommand command = new OracleCommand(queryString,connection); + + connection.Open(); + OracleDataReader reader = command.ExecuteReader(); + + int custIdCol = reader.GetOrdinal("CustomerID"); + + while (reader.Read()) + Console.WriteLine("CustomerID = {0}", reader.GetString(custIdCol)); + + reader.Close(); + connection.Close(); +} +``` + ]]> @@ -1651,15 +1651,15 @@ public void ReadOracleData(string connectionString) Gets an array of objects that are a representation of the underlying provider specific values. The number of instances of in the array. - method provides an efficient means for retrieving all columns, rather than retrieving each column individually. - - You can pass an array that contains fewer than the number of columns contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns contained in the resulting row. - - This method returns for null database columns. - + method provides an efficient means for retrieving all columns, rather than retrieving each column individually. + + You can pass an array that contains fewer than the number of columns contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns contained in the resulting row. + + This method returns for null database columns. + ]]> @@ -1694,32 +1694,32 @@ public void ReadOracleData(string connectionString) Returns a that describes the column metadata of the OracleDataReader. A that describes the column metadata. - method returns metadata about each column in the following order: - -|DataReader Column|Description| -|-----------------------|-----------------| -|ColumnName|The name of the column; this might not be unique. If the column name cannot be determined, a null value is returned. This name always reflects the most recent naming of the column in the current view or command text.| -|ColumnOrdinal|The zero-based ordinal of the column. This column cannot contain a null value.| -|ColumnSize|The maximum possible length of a value in the column. For columns that use a fixed-length data type, this is the size of the data type.| -|NumericPrecision|If is a numeric data type, this is the maximum precision of the column. The precision depends on the definition of the column. `Float` and `Double` data types in Oracle are binary precision.| -|NumericScale|If is a numeric data type, the number of digits to the right of the decimal point. `Float` and `Double` data types in Oracle are binary scale.| -|DataType|Maps to the common language runtime type of .| -|IsLong|`true` if the column contains a Binary Long Object (BLOB) that contains very long data.| -|AllowDBNull|`true` if the consumer can set the column to a null value; otherwise, `false`. A column may contain null values, even if it cannot be set to a null value.| -|IsUnique|`true`: No two rows in the base table-the table returned in -can have the same value in this column. **IsUnique** is guaranteed to be `true` if the column constitutes a key by itself or if there is a constraint of type UNIQUE that applies only to this column. `false`: The column can contain duplicate values in the base table. The default for this column is false.| -|IsKey|`true`: The column is one of a set of columns in the rowset that, taken together, uniquely identify the row. The set of columns with **IsKey** set to true must uniquely identify a row in the rowset. There is no requirement that this set of columns is a minimal set of columns. This set of columns may be generated from a base table primary key, a unique constraint or a unique index. `false`: The column is not required to uniquely identify the row.| -|BaseTableName|The name of the table or view in the data store that contains the column. A null value if the base table name cannot be determined. The default of this column is a null value.| -|BaseColumnName|The name of the column in the data store. This might be different than the column name returned in the **ColumnName** column if an alias was used. A null value if the base column name cannot be determined or if the rowset column is derived, but not identical to, a column in the data store. The default for this column is a null value.| -|BaseSchemaName|The name of the schema in the data store that contains the column. A null value if the base schema name cannot be determined. The default for this column is a null value.| - - A row is returned for every column in the results set. - + method returns metadata about each column in the following order: + +|DataReader Column|Description| +|-----------------------|-----------------| +|ColumnName|The name of the column; this might not be unique. If the column name cannot be determined, a null value is returned. This name always reflects the most recent naming of the column in the current view or command text.| +|ColumnOrdinal|The zero-based ordinal of the column. This column cannot contain a null value.| +|ColumnSize|The maximum possible length of a value in the column. For columns that use a fixed-length data type, this is the size of the data type.| +|NumericPrecision|If is a numeric data type, this is the maximum precision of the column. The precision depends on the definition of the column. `Float` and `Double` data types in Oracle are binary precision.| +|NumericScale|If is a numeric data type, the number of digits to the right of the decimal point. `Float` and `Double` data types in Oracle are binary scale.| +|DataType|Maps to the common language runtime type of .| +|IsLong|`true` if the column contains a Binary Long Object (BLOB) that contains very long data.| +|AllowDBNull|`true` if the consumer can set the column to a null value; otherwise, `false`. A column may contain null values, even if it cannot be set to a null value.| +|IsUnique|`true`: No two rows in the base table-the table returned in -can have the same value in this column. **IsUnique** is guaranteed to be `true` if the column constitutes a key by itself or if there is a constraint of type UNIQUE that applies only to this column. `false`: The column can contain duplicate values in the base table. The default for this column is false.| +|IsKey|`true`: The column is one of a set of columns in the rowset that, taken together, uniquely identify the row. The set of columns with **IsKey** set to true must uniquely identify a row in the rowset. There is no requirement that this set of columns is a minimal set of columns. This set of columns may be generated from a base table primary key, a unique constraint or a unique index. `false`: The column is not required to uniquely identify the row.| +|BaseTableName|The name of the table or view in the data store that contains the column. A null value if the base table name cannot be determined. The default of this column is a null value.| +|BaseColumnName|The name of the column in the data store. This might be different than the column name returned in the **ColumnName** column if an alias was used. A null value if the base column name cannot be determined or if the rowset column is derived, but not identical to, a column in the data store. The default for this column is a null value.| +|BaseSchemaName|The name of the schema in the data store that contains the column. A null value if the base schema name cannot be determined. The default for this column is a null value.| + + A row is returned for every column in the results set. + > [!NOTE] -> To ensure that metadata columns return the correct information, you must call with the `behavior` parameter set to `KeyInfo`. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. - +> To ensure that metadata columns return the correct information, you must call with the `behavior` parameter set to `KeyInfo`. Otherwise, some of the columns in the schema table may return default, null, or incorrect data. + ]]> Retrieving Database Schema Information (ADO.NET) @@ -1758,11 +1758,11 @@ public void ReadOracleData(string connectionString) Gets the value of the specified column as a string. The value of the specified column as a string. - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1793,11 +1793,11 @@ public void ReadOracleData(string connectionString) Gets the value of the specified column as a . The value of the specified column as a . - to check for null values before calling this method. - + to check for null values before calling this method. + ]]> The specified cast is not valid. @@ -1836,11 +1836,11 @@ public void ReadOracleData(string connectionString) Gets the value of the column at the specified ordinal in its native format. The value to return. - for null database columns. The value returned by this method might be the result of the conversion from Oracle's Number data type to .NET Decimal type. If the value is too large to be stored in the .NET Decimal, this method throws an that is an overflow exception. - + for null database columns. The value returned by this method might be the result of the conversion from Oracle's Number data type to .NET Decimal type. If the value is too large to be stored in the .NET Decimal, this method throws an that is an overflow exception. + ]]> The value is too large to be stored in the .NET Decimal. @@ -1879,15 +1879,15 @@ public void ReadOracleData(string connectionString) Populates an array of objects with the column values of the current row. The number of instances of in the array. - method provides an efficient means for retrieving all columns, rather than retrieving each column individually. - - You can pass an array that contains fewer than the number of columns contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns contained in the resulting row. - - This method returns for null database columns. The value returned in the array might be the result of the conversion from Oracle's Number data type to .NET Decimal type. If the value is too large to be stored in the .NET Decimal, this method throws an that is an overflow exception. - + method provides an efficient means for retrieving all columns, rather than retrieving each column individually. + + You can pass an array that contains fewer than the number of columns contained in the resulting row. Only the amount of data the array holds is copied to the array. You can also pass an array whose length is more than the number of columns contained in the resulting row. + + This method returns for null database columns. The value returned in the array might be the result of the conversion from Oracle's Number data type to .NET Decimal type. If the value is too large to be stored in the .NET Decimal, this method throws an that is an overflow exception. + ]]> The value is too large to be stored in the .NET Decimal. @@ -1948,11 +1948,11 @@ public void ReadOracleData(string connectionString) if the is closed; otherwise, . - and are the only properties that you can call after the is closed. - + and are the only properties that you can call after the is closed. + ]]> @@ -1991,11 +1991,11 @@ public void ReadOracleData(string connectionString) if the specified column value is equivalent to ; otherwise, . - , , and so on). - + , , and so on). + ]]> @@ -2108,11 +2108,11 @@ public void ReadOracleData(string connectionString) if there are more result sets; otherwise, . - @@ -2148,21 +2148,21 @@ public void ReadOracleData(string connectionString) if there are more rows; otherwise, . - is prior to the first record. Therefore, you must call to begin accessing any data. - - More than one can be open at any given time. - - - -## Examples - The following example creates an , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , then the . - + is prior to the first record. Therefore, you must call to begin accessing any data. + + More than one can be open at any given time. + + + +## Examples + The following example creates an , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , then the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDataReader.Read Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataReader/Read/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataReader/Read/source.vb" id="Snippet1"::: + ]]> @@ -2194,13 +2194,13 @@ public void ReadOracleData(string connectionString) Gets the number of rows changed, inserted, or deleted by execution of the SQL statement. The number of rows changed, inserted, or deleted. -1 for SELECT statements; 0 if no rows were affected, or the statement failed. - property is not set until all rows are read and you close the . - - and are the only properties that you can call after the is closed. - + property is not set until all rows are read and you close the . + + and are the only properties that you can call after the is closed. + ]]> diff --git a/xml/System.Data.OracleClient/OracleLob.xml b/xml/System.Data.OracleClient/OracleLob.xml index 43ecc7d556c..9eeaa5b717f 100644 --- a/xml/System.Data.OracleClient/OracleLob.xml +++ b/xml/System.Data.OracleClient/OracleLob.xml @@ -341,7 +341,7 @@ connection.Close(); property is not a setting of the .NET Framework Data Provider for Oracle. Instead, it is the value that the Oracle Call Interface (OCI) uses when communicating with the server. Use to ensure that client-side chunks are the same size. Reading or writing in smaller chunks does not cache data, and causes a less-optimized round trip to the server, because a full packet is not received or sent. + The value returned by the property is not a setting of the .NET Framework Data Provider for Oracle. Instead, it is the value that the Oracle Call Interface (OCI) uses when communicating with the server. Use to ensure that client-side chunks are the same size. Reading or writing in smaller chunks does not cache data, and causes a less-optimized round trip to the server, because a full packet is not received or sent. ]]> @@ -378,7 +378,7 @@ connection.Close(); object initially have the same values as those of the original object. However, after the is complete, each object is independent from the other. For example, changing the value of the property on the original does not change the value of on the copy. + The properties of the new object initially have the same values as those of the original object. However, after the is complete, each object is independent from the other. For example, changing the value of the property on the original does not change the value of on the copy. ]]> @@ -763,7 +763,7 @@ connection.Close(); . Therefore, specifying a value greater than that returned by the property succeeds; however only erases to the end of the . (Similarly, if a negative value is passed to `offset`, will succeed, but only erase starting from the beginning of the .) This behavior is different from that of the and methods, and offers the advantage of being able to erase all data from the value specified by `offset` without making an additional roundtrip to the server to verify the actual size. + The sum of the values in the `offset` and `amount` parameters can be greater than that of the size of the . Therefore, specifying a value greater than that returned by the property succeeds; however only erases to the end of the . (Similarly, if a negative value is passed to `offset`, will succeed, but only erase starting from the beginning of the .) This behavior is different from that of the and methods, and offers the advantage of being able to erase all data from the value specified by `offset` without making an additional roundtrip to the server to verify the actual size. does not truncate data. The `LOB` length remains the same for a `BLOB` data type, and the erased data is replaced by 0x00. `CLOB` and `NCLOB` data types are replaced by spaces. @@ -1058,9 +1058,9 @@ if(myLob == OracleLob.Null) property to determine whether the stream supports seeking. + The stream must support seeking to get or set the position. Use the property to determine whether the stream supports seeking. - Seeking to any location beyond the length of the stream is supported. Seeking to an odd position for `CLOB` and `NCLOB` data types is also supported. For more information, see the Remarks section of the property. + Seeking to any location beyond the length of the stream is supported. Seeking to an odd position for `CLOB` and `NCLOB` data types is also supported. For more information, see the Remarks section of the property. ]]> @@ -1212,7 +1212,7 @@ if (myLob == OracleLob.Null) ## Remarks If `offset` is negative, the new position must precede the position specified by `origin` by the number of bytes specified by `offset`. If `offset` is zero, the new position must be the position specified by `origin`. If `offset` is positive, the new position must follow the position specified by `origin` by the number of bytes specified by `offset`. - Seeking to any location beyond the length of the stream is supported. Seeking to an odd position for `CLOB` and `NCLOB` data types is also supported. For more information, see the Remarks section of the property. + Seeking to any location beyond the length of the stream is supported. Seeking to an odd position for `CLOB` and `NCLOB` data types is also supported. For more information, see the Remarks section of the property. ]]> diff --git a/xml/System.Data.OracleClient/OracleParameter.xml b/xml/System.Data.OracleClient/OracleParameter.xml index 4a7f45b21dc..805656c7a25 100644 --- a/xml/System.Data.OracleClient/OracleParameter.xml +++ b/xml/System.Data.OracleClient/OracleParameter.xml @@ -951,9 +951,9 @@ public void CreateOracleDbParameter() ## Remarks Setting affects only the input value of a parameter. Return values and output parameters are not affected by this property. - The property is used for binary and string types. + The property is used for binary and string types. - For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. + For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first one hundred characters. @@ -1027,7 +1027,7 @@ public void CreateOracleParameter() and the may be bidirectional depending on the value of the property. + The link between the value of the and the may be bidirectional depending on the value of the property. @@ -1140,7 +1140,7 @@ FieldName = @OriginalFieldName during the to determine whether the original or current value is used for a parameter value. This lets primary keys be updated. This property is set to the version of the used by the property ( indexer), or the method of the object. + This property is used by the during the to determine whether the original or current value is used for a parameter value. This lets primary keys be updated. This property is set to the version of the used by the property ( indexer), or the method of the object. @@ -1286,7 +1286,7 @@ public void CreateOracleParameter() The `InputOutput`, `Output`, and `ReturnValue` values used by the Value property will be Microsoft .NET Framework data types, unless the input value was an Oracle data type (for example, or ). This does not apply to REF CURSOR, BFILE, or LOB data types. - The property is overwritten by the **Update** method. + The property is overwritten by the **Update** method. ]]> diff --git a/xml/System.Data.OracleClient/OracleParameterCollection.xml b/xml/System.Data.OracleClient/OracleParameterCollection.xml index 3e387298e3d..26c94fca81d 100644 --- a/xml/System.Data.OracleClient/OracleParameterCollection.xml +++ b/xml/System.Data.OracleClient/OracleParameterCollection.xml @@ -66,7 +66,7 @@ SELECT * FROM Customers WHERE CustomerID = :pCustomerID ``` - When using named parameters in an SQL statement called by an of `CommandType.Text`, you must precede the parameter name with a colon (:). However, in a stored procedure, or when referring to a named parameter elsewhere in your code (for example, when adding objects to the property), do not precede the named parameter with a colon (:). The data provider supplies the colon automatically. + When using named parameters in an SQL statement called by an of `CommandType.Text`, you must precede the parameter name with a colon (:). However, in a stored procedure, or when referring to a named parameter elsewhere in your code (for example, when adding objects to the property), do not precede the named parameter with a colon (:). The data provider supplies the colon automatically. diff --git a/xml/System.Data.OracleClient/OraclePermission.xml b/xml/System.Data.OracleClient/OraclePermission.xml index 8063a4fb83e..fe82eb421c7 100644 --- a/xml/System.Data.OracleClient/OraclePermission.xml +++ b/xml/System.Data.OracleClient/OraclePermission.xml @@ -53,18 +53,18 @@ Enables the .NET Framework Data Provider for Oracle to help ensure that a user has a security level adequate to access an Oracle database. - property takes precedence over the property. Therefore, if you set to `false`, you must also set to `false` to prevent a user from making a connection using a blank password. - - For an example demonstrating how to use security demands, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). - + This type is deprecated and will be removed in a future version of .NET Framework. For more information, see [Oracle and ADO.NET](/dotnet/framework/data/adonet/oracle-and-adonet). + + The property takes precedence over the property. Therefore, if you set to `false`, you must also set to `false` to prevent a user from making a connection using a blank password. + + For an example demonstrating how to use security demands, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). + ]]> @@ -179,11 +179,11 @@ if a blank password is allowed, otherwise . - enumeration takes precedence over the property. Therefore, if you set to false, you must also set to `None` to prevent a user from making a connection using a blank password. - + enumeration takes precedence over the property. Therefore, if you set to false, you must also set to `None` to prevent a user from making a connection using a blank password. + ]]> diff --git a/xml/System.Data.OracleClient/OraclePermissionAttribute.xml b/xml/System.Data.OracleClient/OraclePermissionAttribute.xml index 07c1c1c3949..af0baaf4be1 100644 --- a/xml/System.Data.OracleClient/OraclePermissionAttribute.xml +++ b/xml/System.Data.OracleClient/OraclePermissionAttribute.xml @@ -53,14 +53,14 @@ Associates a security action with a custom security attribute. - @@ -168,11 +168,11 @@ Gets or sets a permitted connection string. A permitted connection string. - . - + . + ]]> @@ -279,15 +279,15 @@ Gets or sets connection string parameters that are allowed or disallowed. One or more connection string parameters that are allowed or disallowed. - property. - - If no key restrictions are specified, and the property is set to `AllowOnly`, no additional connection string parameters are allowed. - - If no key restrictions are specified, and the property is set to `PreventUsage`, additional connection string parameters are allowed. If more than one rule is set for the same connection string, the more restrictive rule is selected during the permission check. - + property. + + If no key restrictions are specified, and the property is set to `AllowOnly`, no additional connection string parameters are allowed. + + If no key restrictions are specified, and the property is set to `PreventUsage`, additional connection string parameters are allowed. If more than one rule is set for the same connection string, the more restrictive rule is selected during the permission check. + ]]> diff --git a/xml/System.Data.OracleClient/OracleString.xml b/xml/System.Data.OracleClient/OracleString.xml index 23f6d6d45b2..2e3059fa40b 100644 --- a/xml/System.Data.OracleClient/OracleString.xml +++ b/xml/System.Data.OracleClient/OracleString.xml @@ -411,7 +411,7 @@ public class Class1 { ## Remarks If `index` indicates a position beyond the end of the byte array, an exception is raised. - To avoid raising an exception, always check the property and the `Length` property before reading `this`. + To avoid raising an exception, always check the property and the `Length` property before reading `this`. This property is read-only. diff --git a/xml/System.Data.Services.Client/DataServiceClientException.xml b/xml/System.Data.Services.Client/DataServiceClientException.xml index 5a7bd588691..e2c37d98577 100644 --- a/xml/System.Data.Services.Client/DataServiceClientException.xml +++ b/xml/System.Data.Services.Client/DataServiceClientException.xml @@ -56,18 +56,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error. This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error. This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -99,16 +99,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -166,18 +166,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 the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + 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| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -276,11 +276,11 @@ The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - diff --git a/xml/System.Data.Services.Client/DataServiceCollection`1.xml b/xml/System.Data.Services.Client/DataServiceCollection`1.xml index bce290a67e3..ec25952867b 100644 --- a/xml/System.Data.Services.Client/DataServiceCollection`1.xml +++ b/xml/System.Data.Services.Client/DataServiceCollection`1.xml @@ -25,25 +25,25 @@ An entity type. Represents a dynamic entity collection that provides notifications when items get added, removed, or when the list is refreshed. - class to support binding data to controls in client applications. This class inherits from the class, which implements the interface and is the primary data binding mechanism for Windows Presentation Foundation (WPF) and Silverlight-based applications. - - You can load an binding collection by using any collection that implements the interface. Items loaded into the binding collection must implement the interface. For more information, see [Binding Data to Controls](/dotnet/framework/data/wcf/binding-data-to-controls-wcf-data-services). - - - -## Examples - The following example is from the code-behind page for an Extensible Application Markup Language (XAML) page that defines the `SalesOrders` window in WPF. When the window is loaded, an is created based on the result of a query that returns customers with related objects, filtered by country/region. This result is bound to the property of the that is the root layout control for the WPF window. - + class to support binding data to controls in client applications. This class inherits from the class, which implements the interface and is the primary data binding mechanism for Windows Presentation Foundation (WPF) and Silverlight-based applications. + + You can load an binding collection by using any collection that implements the interface. Items loaded into the binding collection must implement the interface. For more information, see [Binding Data to Controls](/dotnet/framework/data/wcf/binding-data-to-controls-wcf-data-services). + + + +## Examples + The following example is from the code-behind page for an Extensible Application Markup Language (XAML) page that defines the `SalesOrders` window in WPF. When the window is loaded, an is created based on the result of a query that returns customers with related objects, filtered by country/region. This result is bound to the property of the that is the root layout control for the WPF window. + :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf.xaml.cs" id="Snippetwpfdatabinding"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf.xaml.vb" id="Snippetwpfdatabinding"::: - - The following is the XAML that defines the `SalesOrders` window in WPF for the previous example. - - :::code language="xaml" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf.xaml" id="Snippetwpfdatabindingxaml"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf.xaml.vb" id="Snippetwpfdatabinding"::: + + The following is the XAML that defines the `SalesOrders` window in WPF for the previous example. + + :::code language="xaml" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf.xaml" id="Snippetwpfdatabindingxaml"::: + ]]> Binding Data to Controls (WCF Data Services) @@ -81,13 +81,13 @@ Creates a new instance of the class. - . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . - - Automatic change tracking begins after items are loaded into the collection. - + . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + + Automatic change tracking begins after items are loaded into the collection. + ]]> @@ -118,13 +118,13 @@ A or LINQ query that returns an collection of objects that are used to initialize the collection. Creates a new instance of the class based on query execution. - collection of objects supplied for `items` is usually a query that returns the items in the collection. However, any collection of the correct type can be supplied. - - By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . - + collection of objects supplied for `items` is usually a query that returns the items in the collection. However, any collection of the correct type can be supplied. + + By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + ]]> @@ -155,13 +155,13 @@ The used to track changes to objects in the collection. Creates a new instance of the class that uses the specified . - to which entity objects can be added without executing a query against the service or when an is not available. - - By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . - + to which entity objects can be added without executing a query against the service or when an is not available. + + By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + ]]> @@ -194,13 +194,13 @@ A value that indicated whether or not changes made to items in the collection are automatically tracked. Creates a new instance of the class based on query execution and with the specified tracking mode. - . Use this class constructor and supply a value of for `trackingMode` to create an instance of that uses manual change tracking. When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . - - The collection of objects supplied for `items` is usually a query that returns the items in the collection. However, any collection of the correct type can be supplied. - + . Use this class constructor and supply a value of for `trackingMode` to create an instance of that uses manual change tracking. When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + + The collection of objects supplied for `items` is usually a query that returns the items in the collection. However, any collection of the correct type can be supplied. + ]]> @@ -237,13 +237,13 @@ A delegate that encapsulates a method that is called when the collection of entities changes. Creates a new instance of the class with the supplied change method delegates and that uses the specified . - to which entity objects can be added without executing a query against the service or when an is not available. - - By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . - + to which entity objects can be added without executing a query against the service or when an is not available. + + By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + ]]> @@ -282,13 +282,13 @@ A delegate that encapsulates a method that is called when the collection of entities changes. Creates a new instance of the class a based on query execution and with the supplied change method delegates. - and events, respectively. The `entityChanged` method takes an value and the `collectionChanged` method takes a value. Both methods must return a Boolean value that indicates whether the event was handled by the function. When the method returns `true`, the default behavior still occurs. - - By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . - + and events, respectively. The `entityChanged` method takes an value and the `collectionChanged` method takes a value. Both methods must return a Boolean value that indicates whether the event was handled by the function. When the method returns `true`, the default behavior still occurs. + + By default, automatic change tracking is enabled for a . You can create an instance of that uses manual change tracking when you create an instance using a constructor that enables you to supply a value of for . When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + ]]> @@ -323,15 +323,15 @@ A delegate that encapsulates a method that is called when the collection of entities changes. Creates a new instance of the class a based on query execution, with the supplied change method delegates, and that uses the supplied . - . Use this class constructor to supply a value of for `trackingMode` to create an instance of that uses manual change tracking. When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . - - The must be supplied when `items` is not a or that has a reference to a instance. - - The `entityChanged` and `collectionChanged` functions are invoked by the and events, respectively. The `entityChanged` method takes an value and the `collectionChanged` method takes a value. Both methods must return a Boolean value that indicates whether the event was handled by the function. When the method returns `true`, the default behavior will still occur. - + . Use this class constructor to supply a value of for `trackingMode` to create an instance of that uses manual change tracking. When you use manual tracking, you must implement and and handle the raise events to manually report changes to the . + + The must be supplied when `items` is not a or that has a reference to a instance. + + The `entityChanged` and `collectionChanged` functions are invoked by the and events, respectively. The `entityChanged` method takes an value and the `collectionChanged` method takes a value. Both methods must return a Boolean value that indicates whether the event was handled by the function. When the method returns `true`, the default behavior will still occur. + ]]> @@ -359,11 +359,11 @@ When , detaches all items from the . Removes all items from the collection, and optionally detaches all the items from the . - . - + . + ]]> @@ -398,21 +398,21 @@ Gets a continuation object that is used to return the next set of paged results. A object that contains the URI to return the next set of paged results. - property returns a link that is used to access the next set of paged results when paging is enabled in the data service. For more information, see [Configuring the Data Service](/dotnet/framework/data/wcf/configuring-the-data-service-wcf-data-services). - - When loading a paged result into a , you must explicitly load pages by calling the method on the by passing the result of the execution of the URI that was obtained from the property. - - - -## Examples - The following example is from the code-behind page for an Extensible Application Markup Language (XAML) page that defines the `SalesOrders` window in WPF. When the window is loaded, a is created based on the result of a query that returns customers, filtered by country/region. All of the pages of this paged result are loaded, along with the related orders, and are bound to the property of the that is the root layout control for the WPF window. For more information, see [How to: Bind Data to Windows Presentation Foundation Elements](/dotnet/framework/data/wcf/bind-data-to-wpf-elements-wcf-data-services). - + property returns a link that is used to access the next set of paged results when paging is enabled in the data service. For more information, see [Configuring the Data Service](/dotnet/framework/data/wcf/configuring-the-data-service-wcf-data-services). + + When loading a paged result into a , you must explicitly load pages by calling the method on the by passing the result of the execution of the URI that was obtained from the property. + + + +## Examples + The following example is from the code-behind page for an Extensible Application Markup Language (XAML) page that defines the `SalesOrders` window in WPF. When the window is loaded, a is created based on the result of a query that returns customers, filtered by country/region. All of the pages of this paged result are loaded, along with the related orders, and are bound to the property of the that is the root layout control for the WPF window. For more information, see [How to: Bind Data to Windows Presentation Foundation Elements](/dotnet/framework/data/wcf/bind-data-to-wpf-elements-wcf-data-services). + :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf3.xaml.cs" id="Snippetbindpageddata"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf3.xaml.vb" id="Snippetbindpageddata"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/customerorderswpf3.xaml.vb" id="Snippetbindpageddata"::: + ]]> Loading Deferred Content (WCF Data Services) @@ -439,13 +439,13 @@ Disables tracking of all items in the collection. - method can only be called when is the root collection. - - When the method is called on a collection that is a root collection, tracking is also stopped for all related objects in the data graph. - + method can only be called when is the root collection. + + When the method is called on a collection that is a root collection, tracking is also stopped for all related objects in the data graph. + ]]> @@ -475,11 +475,11 @@ The item to add. Adds a specified item to the collection at the specified index. - method to prevent items from being automatically added to the collection. - + method to prevent items from being automatically added to the collection. + ]]> @@ -517,13 +517,13 @@ Collection of entity objects to be added to the . Loads a collection of entity objects into the collection. - method attaches all objects in the collection, if they are not already attached to the that is associated with the . - - When an object is attached by using the method, all related objects are also attached. - + method attaches all objects in the collection, if they are not already attached to the that is associated with the . + + When an object is attached by using the method, all related objects are also attached. + ]]> @@ -551,13 +551,13 @@ Entity object to be added. Loads a single entity object into the collection. - method attaches the object, if it is not already attached to the that is associated with the . - - When an object is attached by using the method, all related objects are also attached. - + method attaches the object, if it is not already attached to the that is associated with the . + + When an object is attached by using the method, all related objects are also attached. + ]]> diff --git a/xml/System.Data.Services.Client/DataServiceContext.xml b/xml/System.Data.Services.Client/DataServiceContext.xml index ae295cf06a2..2ff2014013f 100644 --- a/xml/System.Data.Services.Client/DataServiceContext.xml +++ b/xml/System.Data.Services.Client/DataServiceContext.xml @@ -867,7 +867,7 @@ - The is always 200. -- The property returns an empty collection. +- The property returns an empty collection. If is set: @@ -911,7 +911,7 @@ object passed to the `asyncResult` parameter is the object returned when an operation is executed asynchronously. For more information, see [Asynchronous Operations](/dotnet/framework/data/wcf/asynchronous-operations-wcf-data-services).Until this request is processed, the instance is not in a predictable state. The can be safely used when the property of the `asyncResult` returns a value of `true`. + The object passed to the `asyncResult` parameter is the object returned when an operation is executed asynchronously. For more information, see [Asynchronous Operations](/dotnet/framework/data/wcf/asynchronous-operations-wcf-data-services).Until this request is processed, the instance is not in a predictable state. The can be safely used when the property of the `asyncResult` returns a value of `true`. ]]> diff --git a/xml/System.Data.Services.Client/DataServiceQueryException.xml b/xml/System.Data.Services.Client/DataServiceQueryException.xml index 112e405d532..b52efc530b0 100644 --- a/xml/System.Data.Services.Client/DataServiceQueryException.xml +++ b/xml/System.Data.Services.Client/DataServiceQueryException.xml @@ -28,11 +28,11 @@ Exception that indicates an error occurred loading the property value from the data service. - to get the exception results. - + to get the exception results. + ]]> @@ -63,18 +63,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error. This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error. This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -106,16 +106,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -179,18 +179,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 the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + 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| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions diff --git a/xml/System.Data.Services.Client/DataServiceQuery`1.xml b/xml/System.Data.Services.Client/DataServiceQuery`1.xml index 7deec7a9e19..ac470a9f5cf 100644 --- a/xml/System.Data.Services.Client/DataServiceQuery`1.xml +++ b/xml/System.Data.Services.Client/DataServiceQuery`1.xml @@ -39,11 +39,11 @@ Type of results returned by the query. Represents a single query request to a data service. - or on the class. - + or on the class. + ]]> @@ -74,26 +74,26 @@ Creates a new with the query option set in the URI generated by the returned query. A new query that includes the requested query option appended to the URI of the supplied query. - that is used with sequential method calls to only return orders with a freight cost of more than $30 and to order the results by the ship date in descending order. - + that is used with sequential method calls to only return orders with a freight cost of more than $30 and to order the results by the ship date in descending order. + :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetaddqueryoptions"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetaddqueryoptions"::: - - The following example shows how to compose a LINQ query that is equivalent to the previous query that used . - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetaddqueryoptions"::: + + The following example shows how to compose a LINQ query that is equivalent to the previous query that used . + :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetaddqueryoptionslinq"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetaddqueryoptionslinq"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetaddqueryoptionslinq"::: + ]]> @@ -149,11 +149,11 @@ Returns the type of the object used in the template to create the instance. Returns representing the type used in the template when the query is created. - or . - + or . + ]]> @@ -206,11 +206,11 @@ Executes the query and returns the results as a collection that implements . An in which represents the type of the query results. - is thrown. - + is thrown. + ]]> When the data service returns an HTTP 404: Resource Not Found error. @@ -297,11 +297,11 @@ Executes the query and returns the results as a collection. A typed enumerator over the results in which represents the type of the query results. - method is called, the is executed against the service. - + method is called, the is executed against the service. + ]]> @@ -327,19 +327,19 @@ Requests that the count of all entities in the entity set be returned inline with the query results. A new object that has the inline count option set. - method is equivalent to including the `$inlinecount` query option in the query URI. - - - -## Examples - This example executes a query after it calls the method. The property is used to determine number of entities returned by the query. - + method is equivalent to including the `$inlinecount` query option in the query URI. + + + +## Examples + This example executes a query after it calls the method. The property is used to determine number of entities returned by the query. + :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Client/DataServiceCollectionT/Overview/source.cs" id="Snippetcountallcustomers"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetcountallcustomers"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.Services.Client/DataServiceCollectionT/Overview/source.vb" id="Snippetcountallcustomers"::: + ]]> @@ -427,13 +427,13 @@ Executes the query and returns the results as a collection. An enumerator over the query results. - method is called, the is executed against the service. - - returns an enumerable the first time it is called. On successive calls it returns null. - + method is called, the is executed against the service. + + returns an enumerable the first time it is called. On successive calls it returns null. + ]]> diff --git a/xml/System.Data.Services.Client/DataServiceRequestArgs.xml b/xml/System.Data.Services.Client/DataServiceRequestArgs.xml index dc4d314c0ad..d44bf6b64a7 100644 --- a/xml/System.Data.Services.Client/DataServiceRequestArgs.xml +++ b/xml/System.Data.Services.Client/DataServiceRequestArgs.xml @@ -68,11 +68,11 @@ Gets or sets the Accept header of the request message. The value of the Accept header. - property. Therefore, make sure that the supplied value is a valid value for an HTTP Accept header. - + property. Therefore, make sure that the supplied value is a valid value for an HTTP Accept header. + ]]> @@ -107,11 +107,11 @@ Gets or sets the Content-Type header of the request message. The value of the Content-Type header. - property. Therefore, make sure that the supplied value is a valid value for an HTTP Content-Type header. - + property. Therefore, make sure that the supplied value is a valid value for an HTTP Content-Type header. + ]]> @@ -142,13 +142,13 @@ Gets the headers in the request message. The headers in the request message. - object that contains key-value pairs of strings for each header in the request. - - No validation is performed on the headers in the property. Therefore, make sure that you do not change an HTTP header in a way that changes the meaning of the request. - + object that contains key-value pairs of strings for each header in the request. + + No validation is performed on the headers in the property. Therefore, make sure that you do not change an HTTP header in a way that changes the meaning of the request. + ]]> @@ -183,11 +183,11 @@ Gets or sets the value of the Slug header of the request message. A value that is the Slug header of the request. - property. Therefore, make sure that the supplied value is a valid value for an HTTP Slug header. - + property. Therefore, make sure that the supplied value is a valid value for an HTTP Slug header. + ]]> diff --git a/xml/System.Data.Services.Client/DataServiceRequestException.xml b/xml/System.Data.Services.Client/DataServiceRequestException.xml index a51b862b7a4..6d98a9368ba 100644 --- a/xml/System.Data.Services.Client/DataServiceRequestException.xml +++ b/xml/System.Data.Services.Client/DataServiceRequestException.xml @@ -56,18 +56,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply". This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply". This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -99,16 +99,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -172,18 +172,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 the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + 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| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions diff --git a/xml/System.Data.Services.Client/DataServiceStreamResponse.xml b/xml/System.Data.Services.Client/DataServiceStreamResponse.xml index 41d8f656bbe..d17d9c57af6 100644 --- a/xml/System.Data.Services.Client/DataServiceStreamResponse.xml +++ b/xml/System.Data.Services.Client/DataServiceStreamResponse.xml @@ -44,11 +44,11 @@ Gets the header field for the response stream. The contents of the header field. - property returns `null`. - + property returns `null`. + ]]> @@ -73,11 +73,11 @@ Gets the content type of the response stream. The content type of the response stream. - property returns `null`. - + property returns `null`. + ]]> @@ -105,15 +105,15 @@ Releases all resources used by the current instance of the class. - method when you have finished using the . This releases resources held by the object. You should always do this to release the resources held by the ; otherwise, the consumed resources will not be released until after the garbage collector calls the method on the object. - - After the method is called and all references to the are released, the memory used can be reclaimed by garbage collection. - - You cannot use after calling the method. - + method when you have finished using the . This releases resources held by the object. You should always do this to release the resources held by the ; otherwise, the consumed resources will not be released until after the garbage collector calls the method on the object. + + After the method is called and all references to the are released, the memory used can be reclaimed by garbage collection. + + You cannot use after calling the method. + ]]> @@ -138,11 +138,11 @@ Gets the collection of headers from the response. The headers collection from the response message as a object. - object that contains key-value pairs of strings for each header in the response. - + object that contains key-value pairs of strings for each header in the response. + ]]> @@ -167,17 +167,17 @@ Gets the binary property data from the data service as a binary stream. The stream that contains the binary property data. - is read-only. - - You must call either the method on the or the method on the . Otherwise, the network connection remains open and unavailable to other applications. - - The method is used to access the stream. - + is read-only. + + You must call either the method on the or the method on the . Otherwise, the network connection remains open and unavailable to other applications. + + The method is used to access the stream. + ]]> When the is already disposed. diff --git a/xml/System.Data.Services.Client/EntityDescriptor.xml b/xml/System.Data.Services.Client/EntityDescriptor.xml index 8ea78acaf5c..8b5412d141b 100644 --- a/xml/System.Data.Services.Client/EntityDescriptor.xml +++ b/xml/System.Data.Services.Client/EntityDescriptor.xml @@ -24,17 +24,17 @@ Description of modifications done to entities by operations returned in a . - method returns a object that contains a series of objects each of which contains a sequence of or instances that represent changes that were persisted. - - For successful operations, the property of the descriptor will be set to unchanged and the new values for insert and update operations will be merged according to the merge settings. - - For operations with errors, the of the descriptor will remain the same as it was before was called. - - If an error occurred and processing stopped during an operation, the will remain unchanged. - + method returns a object that contains a series of objects each of which contains a sequence of or instances that represent changes that were persisted. + + For successful operations, the property of the descriptor will be set to unchanged and the new values for insert and update operations will be merged according to the merge settings. + + For operations with errors, the of the descriptor will remain the same as it was before was called. + + If an error occurred and processing stopped during an operation, the will remain unchanged. + ]]> @@ -149,13 +149,13 @@ Gets an eTag value that indicates the state of data targeted for update since the last call to . A string value that indicates the state of data. - @@ -270,11 +270,11 @@ Gets or sets the URI that accesses the binary property data of the entity. A URI that accesses the binary property as a stream. - property contains the URI for the Media Resource that is associated with the entity, which is a Media Link Entry. - + property contains the URI for the Media Resource that is associated with the entity, which is a Media Link Entry. + ]]> @@ -361,15 +361,15 @@ Gets the eTag for the media resource associated with an entity that is a media link entry. A string value that indicates the state of data. - property returns an eTag value that indicates the state of the Media Resource targeted for update since the last call to when the entity is a media link entry. - - The eTag associated with the media resource is used to represent original values for use with optimistic concurrency checks according to eTag rules in HTTP [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=114956). - - The value may be empty or null. Null represents the case in which no eTag is currently associated with the Media Resource. - + property returns an eTag value that indicates the state of the Media Resource targeted for update since the last call to when the entity is a media link entry. + + The eTag associated with the media resource is used to represent original values for use with optimistic concurrency checks according to eTag rules in HTTP [RFC 2616](https://go.microsoft.com/fwlink/?LinkID=114956). + + The value may be empty or null. Null represents the case in which no eTag is currently associated with the Media Resource. + ]]> diff --git a/xml/System.Data.Services.Client/MediaEntryAttribute.xml b/xml/System.Data.Services.Client/MediaEntryAttribute.xml index 4720b465d76..948795c9b2e 100644 --- a/xml/System.Data.Services.Client/MediaEntryAttribute.xml +++ b/xml/System.Data.Services.Client/MediaEntryAttribute.xml @@ -24,17 +24,17 @@ Signifies that the specified class is to be treated as a media link entry. - is called. The media property is also called a Media resource. On saving, the media property of the type denoted by the property, is inserted by a POST request to the URI `//$value`. - - After the `POST`, a `PUT` request with all the properties on the type other than the property, which is binary content, are sent to the URI `/()`. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - + is called. The media property is also called a Media resource. On saving, the media property of the type denoted by the property, is inserted by a POST request to the URI `//$value`. + + After the `POST`, a `PUT` request with all the properties on the type other than the property, which is binary content, are sent to the URI `/()`. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + ]]> diff --git a/xml/System.Data.Services.Client/SaveChangesOptions.xml b/xml/System.Data.Services.Client/SaveChangesOptions.xml index fa2b04a0acb..b03ea09540e 100644 --- a/xml/System.Data.Services.Client/SaveChangesOptions.xml +++ b/xml/System.Data.Services.Client/SaveChangesOptions.xml @@ -23,15 +23,15 @@ Indicates change options when is called. - property returns an empty collection, and the property is zero. - - You cannot set both `Batch` and `ContinueOnError` at the same time. - + property returns an empty collection, and the property is zero. + + You cannot set both `Batch` and `ContinueOnError` at the same time. + ]]> Updating the Data Service (WCF Data Services) diff --git a/xml/System.Data.Services.Common/EntityPropertyMappingAttribute.xml b/xml/System.Data.Services.Common/EntityPropertyMappingAttribute.xml index d7f84e4e408..689265aa0d3 100644 --- a/xml/System.Data.Services.Common/EntityPropertyMappingAttribute.xml +++ b/xml/System.Data.Services.Common/EntityPropertyMappingAttribute.xml @@ -24,23 +24,23 @@ Attribute that specifies a custom mapping between properties of an entity type and elements of an entry in a feed returned by WCF Data Services. - is used to define custom feed mapping in the data model of a reflection provider. This attribute is also applied to generated client data service classes when the metadata used to generate the classes indicates that custom feed mappings are defined in the data model. This information is necessary to make sure that the client can create and consume messages that support custom feeds. For more information, see [Feed Customization](/dotnet/framework/data/wcf/feed-customization-wcf-data-services). - - - -## Examples - In the following example, both properties of the `Order` type are mapped to existing feed elements. The `Product` property of the `Item` type is mapped to a custom feed attribute in a separate namespace. - + is used to define custom feed mapping in the data model of a reflection provider. This attribute is also applied to generated client data service classes when the metadata used to generate the classes indicates that custom feed mappings are defined in the data model. This information is necessary to make sure that the client can create and consume messages that support custom feeds. For more information, see [Feed Customization](/dotnet/framework/data/wcf/feed-customization-wcf-data-services). + + + +## Examples + In the following example, both properties of the `Order` type are mapped to existing feed elements. The `Product` property of the `Item` type is mapped to a custom feed attribute in a separate namespace. + :::code language="csharp" source="~/snippets/csharp/System.Data.Services.Common/EntityPropertyMappingAttribute/Overview/orderitems.svc.cs" id="Snippetcustomiqueryablefeeds"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/astoria_custom_feeds/vb/orderitems.svc.vb" id="Snippetcustomiqueryablefeeds"::: - - The previous example returns the following result for the URI `http://myservice/OrderItems.svc/Orders(0)?$expand=Items`. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Misc/astoria_custom_feeds/xml/iqueryablefeedresultinline.xml" id="Snippetiqueryablefeedresultinline"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/astoria_custom_feeds/vb/orderitems.svc.vb" id="Snippetcustomiqueryablefeeds"::: + + The previous example returns the following result for the URI `http://myservice/OrderItems.svc/Orders(0)?$expand=Items`. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Misc/astoria_custom_feeds/xml/iqueryablefeedresultinline.xml" id="Snippetiqueryablefeedresultinline"::: + ]]> How to: Create a Data Service Using the Reflection Provider (WCF Data Services) @@ -112,11 +112,11 @@ Boolean value that is when the property being mapped should appear both in its mapped-to location and in the content section of the feed. Creates an instance of the to map a property to a custom feed element. - @@ -147,11 +147,11 @@ Gets a Boolean value that indicates whether a property value should be repeated both in the content section of the feed and in the mapped location. A value that is when the property is mapped into both locations in the feed; otherwise, . - is `true`, the feed is backward compatible with WCF Data Services client applications that use protocol version 1.0. When the value of is `false`, the protocol version used by the data service must be 2.0 or later versions. For more information, see [Data Service Versioning](/dotnet/framework/data/wcf/data-service-versioning-wcf-data-services). - + is `true`, the feed is backward compatible with WCF Data Services client applications that use protocol version 1.0. When the value of is `false`, the protocol version used by the data service must be 2.0 or later versions. For more information, see [Data Service Versioning](/dotnet/framework/data/wcf/data-service-versioning-wcf-data-services). + ]]> @@ -182,17 +182,17 @@ Gets the name of the property of the syndication item that will be mapped to the specified element of the feed. String value that contains property name. - property cannot directly reference a complex type. For complex types, you must use a path expression where property names are separated by a backslash (`/`) character. For example, the following values are permitted for an entity type `Person` with an integer property `Age` and a complex property `Address`: - -- `Age` - -- `Address/Street` - - The property cannot be set to a value that contains a space or any other character that is not valid in a property name. - + property cannot directly reference a complex type. For complex types, you must use a path expression where property names are separated by a backslash (`/`) character. For example, the following values are permitted for an entity type `Person` with an integer property `Age` and a complex property `Address`: + +- `Age` + +- `Address/Street` + + The property cannot be set to a value that contains a space or any other character that is not valid in a property name. + ]]> @@ -223,11 +223,11 @@ Gets a string value that, together with , specifies the namespace in which the element exists. String value that contains the target namespace prefix. - nor are specified, the will be put in the default namespace. If is not specified, a prefix is autogenerated. If is specified, but is not specified, an exception is thrown at construction time. - + nor are specified, the will be put in the default namespace. If is not specified, a prefix is autogenerated. If is specified, but is not specified, an exception is thrown at construction time. + ]]> @@ -258,13 +258,13 @@ Gets a string value that specifies the namespace URI of the element specified by the property. String that contains the namespace URI. - nor are specified, the will be put in the default namespace. If is not specified, a prefix is autogenerated. If is specified, but is not specified, an exception is thrown at construction time. - + nor are specified, the will be put in the default namespace. If is not specified, a prefix is autogenerated. If is specified, but is not specified, an exception is thrown at construction time. + ]]> @@ -295,21 +295,21 @@ Gets the name of the custom target in the feed to which the property is mapped. String value with target XML element or attribute. - property is set, the and properties must also be set. - - The value of must be `null` (`Nothing` in Visual Basic) when the value of the property is anything other than . - - must be a path expression in which nested elements are separated by a backslash (`/`) and attributes are specified by an ampersand (`@`). In the following example, the string `UnitsInStock/@ReorderLevel` maps a property value to an attribute named `ReorderLevel` on a child element named `UnitsInStock` of the root entry element. - - :::code language="xml" source="~/snippets/xml/VS_Snippets_Misc/astoria_custom_feeds/xml/northwind.csdl" id="Snippetedmfeedmappedtoattributespecific"::: - - The property cannot contain white space. - - The property is not expressed as a true XPath expression, but the specified element and attribute names must represent well-formed XML elements and attributes. An invalid value will cause an exception to occur when the data service is initialized. - + property is set, the and properties must also be set. + + The value of must be `null` (`Nothing` in Visual Basic) when the value of the property is anything other than . + + must be a path expression in which nested elements are separated by a backslash (`/`) and attributes are specified by an ampersand (`@`). In the following example, the string `UnitsInStock/@ReorderLevel` maps a property value to an attribute named `ReorderLevel` on a child element named `UnitsInStock` of the root entry element. + + :::code language="xml" source="~/snippets/xml/VS_Snippets_Misc/astoria_custom_feeds/xml/northwind.csdl" id="Snippetedmfeedmappedtoattributespecific"::: + + The property cannot contain white space. + + The property is not expressed as a true XPath expression, but the specified element and attribute names must represent well-formed XML elements and attributes. An invalid value will cause an exception to occur when the data service is initialized. + ]]> @@ -340,13 +340,13 @@ Gets a property on the class. A object. - is not null. - + is not null. + ]]> @@ -377,13 +377,13 @@ Gets the type of content of the property mapped by . A string that identifies the type of content in the feed element. - for the attribute, you must ensure that the property value contains properly formatted XML. The data service returns the value without performing any transformations. You must also ensure that any XML element prefixes in the returned XML have a namespace URI and prefix defined in the mapped feed. - + for the attribute, you must ensure that the property value contains properly formatted XML. The data service returns the value without performing any transformations. You must also ensure that any XML element prefixes in the returned XML have a namespace URI and prefix defined in the mapped feed. + ]]> diff --git a/xml/System.Data.Services.Providers/ResourceProperty.xml b/xml/System.Data.Services.Providers/ResourceProperty.xml index 1a8b393b1f4..0bdfd5e3de3 100644 --- a/xml/System.Data.Services.Providers/ResourceProperty.xml +++ b/xml/System.Data.Services.Providers/ResourceProperty.xml @@ -23,21 +23,21 @@ Provides a type to describe a property on a resource. - method will not properly escape these invalid EDM characters." - + method will not properly escape these invalid EDM characters." + ]]> @@ -67,21 +67,21 @@ The of the resource to which the property refers. Initializes a new for an open property. - method will not properly escape these invalid EDM characters." - + method will not properly escape these invalid EDM characters." + ]]> @@ -113,13 +113,13 @@ if the property can be accessed through reflection; otherwise, . - property returns `true`, the data service runtime uses reflection to get the property information on the declaring. of the . - - When the property returns `false`, the data service runtime uses the interface to get or set this property value. - + property returns `true`, the data service runtime uses reflection to get the property information on the declaring. of the . + + When the property returns `false`, the data service runtime uses the interface to get or set this property value. + ]]> @@ -251,11 +251,11 @@ Gets or sets MIME type for the property. String value that indicates MIME type. - diff --git a/xml/System.Data.Services/DataServiceConfiguration.xml b/xml/System.Data.Services/DataServiceConfiguration.xml index 39cc60885d1..3e2e8fdd6e2 100644 --- a/xml/System.Data.Services/DataServiceConfiguration.xml +++ b/xml/System.Data.Services/DataServiceConfiguration.xml @@ -21,14 +21,14 @@ Manages the configuration of WCF Data Services. - Configuring the Data Service (WCF Data Services) @@ -86,21 +86,21 @@ The namespace-qualified name of the type that is enabled for use with the custom data service provider. Registers a data type with the data service runtime so that it can be used by a custom data service provider. - method is used to register a type with the data service runtime. After registration, a type can be returned in the properties of an open type. This makes the type visible in `$metadata` output and usable by the data service. - - The supplied `typeName` must be defined in the same format as a type in the data model and not as a CLR type. The registered types are added to those types already made available by calling the method. - - The data service runtime cannot determine what kind of data type the `typeName` maps to until information about the type can be obtained from the underlying provider. - - A value of '*' can be supplied for `typeName`, which matches all types. - - When the data service runtime enumerates types or must obtain a type from the underlying data provider, it must first determine whether the type must be visible when the method is called. When the type is not available in this manner, then types registered by using the method are checked. When a type is not made visible by using either of these mechanisms, that type is not included in the response to a `$metadata` request, and instances of that type are not returned to the client as the response of a request to the data service. - - The method can be called many times with the same type name. - + method is used to register a type with the data service runtime. After registration, a type can be returned in the properties of an open type. This makes the type visible in `$metadata` output and usable by the data service. + + The supplied `typeName` must be defined in the same format as a type in the data model and not as a CLR type. The registered types are added to those types already made available by calling the method. + + The data service runtime cannot determine what kind of data type the `typeName` maps to until information about the type can be obtained from the underlying provider. + + A value of '*' can be supplied for `typeName`, which matches all types. + + When the data service runtime enumerates types or must obtain a type from the underlying data provider, it must first determine whether the type must be visible when the method is called. When the type is not available in this manner, then types registered by using the method are checked. When a type is not made visible by using either of these mechanisms, that type is not included in the response to a `$metadata` request, and instances of that type are not returned to the client as the response of a request to the data service. + + The method can be called many times with the same type name. + ]]> Configuring the Data Service (WCF Data Services) @@ -323,11 +323,11 @@ Get or sets the maximum number of items in each returned collection. The maximum number of items. - Configuring the Data Service (WCF Data Services) @@ -359,11 +359,11 @@ Type to add to the collection of known types. Adds a type to the list of types that are recognized by the data service. - method to register a type when it cannot be detected by the runtime by using the default set of rules. - + method to register a type when it cannot be detected by the runtime by using the default set of rules. + ]]> Configuring the Data Service (WCF Data Services) @@ -397,19 +397,19 @@ Access rights to be granted to this resource, passed as an value. Sets the permissions for the specified entity set resource. - Configuring the Data Service (WCF Data Services) @@ -440,11 +440,11 @@ Page size for the entity set resource that is specified in . Sets the maximum page size for an entity set resource. - Configuring the Data Service (WCF Data Services) @@ -478,11 +478,11 @@ Access rights to be granted to this resource, passed as a value. Sets the permissions for the specified service operation. - Configuring the Data Service (WCF Data Services) @@ -517,13 +517,13 @@ Gets or sets whether verbose errors should be returned by the data service. Whether verbose errors are returned. - property sets the default verbose error behavior for the whole service. Individual responses can behave differently depending on the value of the property of the arguments to the method on the class. - - For security reasons, verbose errors should only be enabled during development, not in production environments, - + property sets the default verbose error behavior for the whole service. Individual responses can behave differently depending on the value of the property of the arguments to the method on the class. + + For security reasons, verbose errors should only be enabled during development, not in production environments, + ]]> Configuring the Data Service (WCF Data Services) diff --git a/xml/System.Data.Services/DataServiceException.xml b/xml/System.Data.Services/DataServiceException.xml index 2c537097c64..be4cc423937 100644 --- a/xml/System.Data.Services/DataServiceException.xml +++ b/xml/System.Data.Services/DataServiceException.xml @@ -54,11 +54,11 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error. This message takes into account the current system culture. - + property of the new instance to a system-supplied message that describes the error. This message takes into account the current system culture. + ]]> Handling and Throwing Exceptions @@ -90,16 +90,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -187,18 +187,18 @@ The exception that is the cause of the current 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| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + 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| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions diff --git a/xml/System.Data.Services/IDataServiceHost.xml b/xml/System.Data.Services/IDataServiceHost.xml index d06bac10643..90549fc31ad 100644 --- a/xml/System.Data.Services/IDataServiceHost.xml +++ b/xml/System.Data.Services/IDataServiceHost.xml @@ -14,11 +14,11 @@ Interface that specifies interactions between WCF Data Services and its hosting environment. - is the contract between WCF Data Services and its hosting environment. This abstraction allows the WCF Data Services runtime to be agnostic to any particular hosting environment. The interface provides WCF Data Services with access to inbound HTTP requests. A new object implementing this interface is instantiated for each HTTP request and is then used to inspect properties of the HTTP request and configure the HTTP response. - + is the contract between WCF Data Services and its hosting environment. This abstraction allows the WCF Data Services runtime to be agnostic to any particular hosting environment. The interface provides WCF Data Services with access to inbound HTTP requests. A new object implementing this interface is instantiated for each HTTP request and is then used to inspect properties of the HTTP request and configure the HTTP response. + ]]> @@ -43,11 +43,11 @@ Gets an absolute URI that is the URI as sent by the client. A string that is the absolute URI of the request. - property always returns the absolute URI from the client HTTP request. This enables consistent access to the request URI, even in cases where the host revises the URI. - + property always returns the absolute URI from the client HTTP request. This enables consistent access to the request URI, even in cases where the host revises the URI. + ]]> @@ -72,11 +72,11 @@ Gets an absolute URI that is the root URI of the data service. A string that is the absolute root URI of the data service. - property always returns the absolute root URI of the service request. This enables consistent access to the root data service URI, even in cases where the host revises the URI. - + property always returns the absolute root URI of the service request. This enables consistent access to the root data service URI, even in cases where the host revises the URI. + ]]> @@ -105,11 +105,11 @@ Gets a data item identified by the identity key contained by the parameter of the method. The data item requested by the query serialized as a string. - @@ -160,11 +160,11 @@ The transport protocol specified by the request accept header. String that indicates the transport protocol required by the request. - @@ -189,11 +189,11 @@ Gets a string representing the value of the Accept-Charset HTTP header. String representing the value of the Accept-Charset HTTP header. - @@ -218,11 +218,11 @@ Gets the transport protocol specified by the content type header. String value that indicates content type. - @@ -247,11 +247,11 @@ Gets the request method of GET, PUT, POST, or DELETE. String value that indicates request method. - and their use, see [WCF Data Services Client Library](/dotnet/framework/data/wcf/wcf-data-services-client-library). - + and their use, see [WCF Data Services Client Library](/dotnet/framework/data/wcf/wcf-data-services-client-library). + ]]> @@ -365,11 +365,11 @@ Gets the value that identifies the version of the request that the client submitted, possibly null. A string that identifies the version of the request that the client submitted, possibly null. - @@ -416,11 +416,11 @@ Gets the transport protocol of the response. String value containing the content type. - and their use, see [WCF Data Services Client Library](/dotnet/framework/data/wcf/wcf-data-services-client-library). - + and their use, see [WCF Data Services Client Library](/dotnet/framework/data/wcf/wcf-data-services-client-library). + ]]> @@ -467,21 +467,21 @@ Gets or sets the service location. String that contains the service location. - @@ -529,11 +529,11 @@ http://myhost/myservice.svc/Customers, the response location would be http://myh object to which the response body will be written. - diff --git a/xml/System.Data.Sql/SqlDataSourceEnumerator.xml b/xml/System.Data.Sql/SqlDataSourceEnumerator.xml index 46e2f826346..d74b39ee497 100644 --- a/xml/System.Data.Sql/SqlDataSourceEnumerator.xml +++ b/xml/System.Data.Sql/SqlDataSourceEnumerator.xml @@ -18,11 +18,11 @@ Provides a mechanism for enumerating all available instances of SQL Server within the local network. - class exposes this information to the application developer, providing a containing information about all the available servers. This returned table contains a list of server instances that matches the list provided when a user attempts to create a new connection, and on the `Connection Properties` dialog box, expands the drop-down list containing all the available servers. - + class exposes this information to the application developer, providing a containing information about all the available servers. This returned table contains a list of server instances that matches the list provided when a user attempts to create a new connection, and on the `Connection Properties` dialog box, expands the drop-down list containing all the available servers. + ]]> Enumerating Instances of SQL Server @@ -49,87 +49,87 @@ Retrieves a containing information about all visible SQL Server instances. A containing information about the visible SQL Server instances. -
10.0.xx for SQL Server 2008
10.50.x for SQL Server 2008 R2
11.0.xx for SQL Server 2012
12.0.xx for SQL Server 2014
13.0.xx for SQL Server 2016
14.0.xx for SQL Server 2017| - +
10.0.xx for SQL Server 2008
10.50.x for SQL Server 2008 R2
11.0.xx for SQL Server 2012
12.0.xx for SQL Server 2014
13.0.xx for SQL Server 2016
14.0.xx for SQL Server 2017| + > [!NOTE] -> Due to the nature of the mechanism used by to locate data sources on a network, the method will not always return a complete list of the available servers, and the list might not be the same on every call. If you plan to use this function to let users select a server from a list, make sure that you always also supply an option to type in a name that is not in the list, in case the server enumeration does not return all the available servers. In addition, this method may take a significant amount of time to execute, so be careful about calling it when performance is critical. - - - -## Examples - The following console application retrieves information about all the visible SQL Server instances and displays the information in the console window. - -```vb -Imports System.Data.Sql - -Module Module1 - Sub Main() - ' Retrieve the enumerator instance and then the data. - Dim instance As SqlDataSourceEnumerator = _ - SqlDataSourceEnumerator.Instance - Dim table As System.Data.DataTable = instance.GetDataSources() - - ' Display the contents of the table. - DisplayData(table) - - Console.WriteLine("Press any key to continue.") - Console.ReadKey() - End Sub - - Private Sub DisplayData(ByVal table As DataTable) - For Each row As DataRow In table.Rows - For Each col As DataColumn In table.Columns - Console.WriteLine("{0} = {1}", col.ColumnName, row(col)) - Next - Console.WriteLine("============================") - Next - End Sub -End Module -``` - -```csharp -using System.Data.Sql; - -class Program -{ - static void Main() - { - // Retrieve the enumerator instance and then the data. - SqlDataSourceEnumerator instance = - SqlDataSourceEnumerator.Instance; - System.Data.DataTable table = instance.GetDataSources(); - - // Display the contents of the table. - DisplayData(table); - - Console.WriteLine("Press any key to continue."); - Console.ReadKey(); - } - - private static void DisplayData(System.Data.DataTable table) - { - foreach (System.Data.DataRow row in table.Rows) - { - foreach (System.Data.DataColumn col in table.Columns) - { - Console.WriteLine("{0} = {1}", col.ColumnName, row[col]); - } - Console.WriteLine("============================"); - } - } -} -``` - +> Due to the nature of the mechanism used by to locate data sources on a network, the method will not always return a complete list of the available servers, and the list might not be the same on every call. If you plan to use this function to let users select a server from a list, make sure that you always also supply an option to type in a name that is not in the list, in case the server enumeration does not return all the available servers. In addition, this method may take a significant amount of time to execute, so be careful about calling it when performance is critical. + + + +## Examples + The following console application retrieves information about all the visible SQL Server instances and displays the information in the console window. + +```vb +Imports System.Data.Sql + +Module Module1 + Sub Main() + ' Retrieve the enumerator instance and then the data. + Dim instance As SqlDataSourceEnumerator = _ + SqlDataSourceEnumerator.Instance + Dim table As System.Data.DataTable = instance.GetDataSources() + + ' Display the contents of the table. + DisplayData(table) + + Console.WriteLine("Press any key to continue.") + Console.ReadKey() + End Sub + + Private Sub DisplayData(ByVal table As DataTable) + For Each row As DataRow In table.Rows + For Each col As DataColumn In table.Columns + Console.WriteLine("{0} = {1}", col.ColumnName, row(col)) + Next + Console.WriteLine("============================") + Next + End Sub +End Module +``` + +```csharp +using System.Data.Sql; + +class Program +{ + static void Main() + { + // Retrieve the enumerator instance and then the data. + SqlDataSourceEnumerator instance = + SqlDataSourceEnumerator.Instance; + System.Data.DataTable table = instance.GetDataSources(); + + // Display the contents of the table. + DisplayData(table); + + Console.WriteLine("Press any key to continue."); + Console.ReadKey(); + } + + private static void DisplayData(System.Data.DataTable table) + { + foreach (System.Data.DataRow row in table.Rows) + { + foreach (System.Data.DataColumn col in table.Columns) + { + Console.WriteLine("{0} = {1}", col.ColumnName, row[col]); + } + Console.WriteLine("============================"); + } + } +} +``` + ]]>
Enumerating Instances of SQL Server @@ -155,63 +155,63 @@ class Program Gets an instance of the , which can be used to retrieve information about available SQL Server instances. An instance of the used to retrieve information about available SQL Server instances. - class does not provide a constructor. Use the property to retrieve an instance of the class instead. - - - -## Examples - The following console application displays a list of all the available SQL Server 2005 instances within the local network. This code uses the method to filter the rows in the table returned by the method. - -```vb -Imports System.Data.Sql - -Module Module1 - Sub Main() - ' Retrieve the enumerator instance, and - ' then retrieve the data sources. - Dim instance As SqlDataSourceEnumerator = _ - SqlDataSourceEnumerator.Instance - Dim table As System.Data.DataTable = instance.GetDataSources() - - ' Filter the sources to just show SQL Server 2005 instances. - Dim rows() As DataRow = table.Select("Version LIKE '9%'") - For Each row As DataRow In rows - Console.WriteLine(row("ServerName")) - Next - Console.WriteLine("Press any key to continue.") - Console.ReadKey() - End Sub -End Module -``` - -```csharp -using System.Data.Sql; - -class Program -{ - static void Main() - { - // Retrieve the enumerator instance, and - // then retrieve the data sources. - SqlDataSourceEnumerator instance = - SqlDataSourceEnumerator.Instance; - System.Data.DataTable table = instance.GetDataSources(); - - // Filter the sources to just show SQL Server 2005 instances. - System.Data.DataRow[] rows = table.Select("Version LIKE '9%'"); - foreach (System.Data.DataRow row in rows) - { - Console.WriteLine(row["ServerName"]); - } - Console.WriteLine("Press any key to continue."); - Console.ReadKey(); - } -} -``` - + class does not provide a constructor. Use the property to retrieve an instance of the class instead. + + + +## Examples + The following console application displays a list of all the available SQL Server 2005 instances within the local network. This code uses the method to filter the rows in the table returned by the method. + +```vb +Imports System.Data.Sql + +Module Module1 + Sub Main() + ' Retrieve the enumerator instance, and + ' then retrieve the data sources. + Dim instance As SqlDataSourceEnumerator = _ + SqlDataSourceEnumerator.Instance + Dim table As System.Data.DataTable = instance.GetDataSources() + + ' Filter the sources to just show SQL Server 2005 instances. + Dim rows() As DataRow = table.Select("Version LIKE '9%'") + For Each row As DataRow In rows + Console.WriteLine(row("ServerName")) + Next + Console.WriteLine("Press any key to continue.") + Console.ReadKey() + End Sub +End Module +``` + +```csharp +using System.Data.Sql; + +class Program +{ + static void Main() + { + // Retrieve the enumerator instance, and + // then retrieve the data sources. + SqlDataSourceEnumerator instance = + SqlDataSourceEnumerator.Instance; + System.Data.DataTable table = instance.GetDataSources(); + + // Filter the sources to just show SQL Server 2005 instances. + System.Data.DataRow[] rows = table.Select("Version LIKE '9%'"); + foreach (System.Data.DataRow row in rows) + { + Console.WriteLine(row["ServerName"]); + } + Console.WriteLine("Press any key to continue."); + Console.ReadKey(); + } +} +``` + ]]> Enumerating Instances of SQL Server diff --git a/xml/System.Data.Sql/SqlNotificationRequest.xml b/xml/System.Data.Sql/SqlNotificationRequest.xml index 2ac07781ad0..d94f073bf66 100644 --- a/xml/System.Data.Sql/SqlNotificationRequest.xml +++ b/xml/System.Data.Sql/SqlNotificationRequest.xml @@ -28,11 +28,11 @@ Represents a request for notification for a given command. - class provides a simpler way of using query notifications. However, if you need fine control over when notifications occur, or you need to customize the message data returned as part of a notification, the class is the one to use. - + class provides a simpler way of using query notifications. However, if you need fine control over when notifications occur, or you need to customize the message data returned as part of a notification, the class is the one to use. + ]]> Using Query Notifications @@ -68,11 +68,11 @@ Creates a new instance of the class with default values. - object, that instance must have its and properties initialized before assigning the object to a object's property. The default values used by the constructor are NULL (`Nothing` in Visual Basic) for the , an empty string for the , and zero for the . - + object, that instance must have its and properties initialized before assigning the object to a object's property. The default values used by the constructor are NULL (`Nothing` in Visual Basic) for the , an empty string for the , and zero for the . + ]]> Using Query Notifications @@ -102,17 +102,17 @@ A string that contains an application-specific identifier for this notification. It is not used by the notifications infrastructure, but it allows you to associate notifications with the application state. The value indicated in this parameter is included in the Service Broker queue message. - A string that contains the Service Broker service name where notification messages are posted, and it must include a database name or a Service Broker instance GUID that restricts the scope of the service name lookup to a particular database. - + A string that contains the Service Broker service name where notification messages are posted, and it must include a database name or a Service Broker instance GUID that restricts the scope of the service name lookup to a particular database. + For more information about the format of the parameter, see . The time, in seconds, to wait for a notification message. Creates a new instance of the class with a user-defined string that identifies a particular notification request, the name of a predefined SQL Server 2005 Service Broker service name, and the time-out period, measured in seconds. - instance, providing your own identifier, the SQL Server 2005 Service Broker service name, and a time-out value. - + instance, providing your own identifier, the SQL Server 2005 Service Broker service name, and a time-out value. + ]]> The value of the parameter is NULL. @@ -145,19 +145,19 @@ that contains the SQL Server 2005 Service Broker service name where notification messages are posted and the database or service broker instance GUID to scope the server name lookup. - property has the following format: - - `service={;(local database=|broker instance=)}` - - For example, if you use the service "myservice" in the database "AdventureWorks" the format is: - - `service=myservice;local database=AdventureWorks` - - The SQL Server Service Broker service must be previously configured on the server. In addition, a Service Broker service and queue must be defined and security access granted as needed. See the SQL Server 2005 documentation for more information. - + property has the following format: + + `service={;(local database=|broker instance=)}` + + For example, if you use the service "myservice" in the database "AdventureWorks" the format is: + + `service=myservice;local database=AdventureWorks` + + The SQL Server Service Broker service must be previously configured on the server. In addition, a Service Broker service and queue must be defined and security access granted as needed. See the SQL Server 2005 documentation for more information. + ]]> The value is NULL. @@ -189,11 +189,11 @@ Gets or sets a value that specifies how long SQL Server waits for a change to occur before the operation times out. A signed integer value that specifies, in seconds, how long SQL Server waits for a change to occur before the operation times out. - property defaults to the value set on the server. - + property defaults to the value set on the server. + ]]> The value is less than zero. @@ -224,11 +224,11 @@ Gets or sets an application-specific identifier for this notification. A value of the application-specific identifier for this notification. - property is included in the SQL Server 2005 queue message. - + property is included in the SQL Server 2005 queue message. + ]]> The value is longer than . diff --git a/xml/System.Data.SqlClient/SqlBulkCopy.xml b/xml/System.Data.SqlClient/SqlBulkCopy.xml index 103912fd65a..979e309a3c8 100644 --- a/xml/System.Data.SqlClient/SqlBulkCopy.xml +++ b/xml/System.Data.SqlClient/SqlBulkCopy.xml @@ -318,7 +318,7 @@ If the instance has been declared without the option in effect, rows are sent to the server rows at a time, but no transaction-related action is taken. If is in effect, each batch of rows is inserted as a separate transaction. - The property can be set at any time. If a bulk copy is already in progress, the current batch is sized according to the previous batch size. Subsequent batches use the new size. If the is initially zero and changed while a operation is already in progress, that operation loads the data as a single batch. Any subsequent operations on the same instance use the new . + The property can be set at any time. If a bulk copy is already in progress, the current batch is sized according to the previous batch size. Subsequent batches use the new size. If the is initially zero and changed while a operation is already in progress, that operation loads the data as a single batch. Any subsequent operations on the same instance use the new . @@ -528,7 +528,7 @@ is a three-part name (`..`). You can qualify the table name with its database and owning schema if you choose. However, if the table name uses an underscore ("_") or any other special characters, you must escape the name using surrounding brackets as in (`[..]`). For more information, see [Database Identifiers](/sql/relational-databases/databases/database-identifiers). - You can bulk-copy data to a temporary table by using a value such as `tempdb..#table` or `tempdb..#table` for the property. + You can bulk-copy data to a temporary table by using a value such as `tempdb..#table` or `tempdb..#table` for the property. @@ -619,14 +619,14 @@ property can be set at any time, even while a bulk copy operation is underway. Changes made during a bulk copy operation take effect after the next notification. The new setting applies to all subsequent operations on the same instance. + This property is designed for user interface components that illustrate the progress of a bulk copy operation. It indicates the number of rows to be processed before generating a notification event. The property can be set at any time, even while a bulk copy operation is underway. Changes made during a bulk copy operation take effect after the next notification. The new setting applies to all subsequent operations on the same instance. If is set to a number less than zero, an is thrown. ## Examples - The following console application demonstrates how to bulk load data using a connection that is already open. The property is set so that the event handler is called after every 50 rows copied to the table. + The following console application demonstrates how to bulk load data using a connection that is already open. The property is set so that the event handler is called after every 50 rows copied to the table. In this example, the connection is first used to read data from a SQL Server table to a instance. Then a second connection is opened to bulk copy the data. Note that the source data does not have to be located on SQL Server; you can use any data source that can be read to an or loaded to a . @@ -675,14 +675,14 @@ ## Remarks Note that the settings of and are independent. Receipt of a event does not imply that any rows have been sent to the server or committed. - You cannot call SqlBulkCopy.Close () or SqlConnection.Close () from this event. Doing this will cause an being thrown, and the object state will not change. If the user wants to cancel the operation from the event, the property of the can be used. (See [Transaction and Bulk Copy Operations](/dotnet/framework/data/adonet/sql/transaction-and-bulk-copy-operations) for examples that use the property.) + You cannot call SqlBulkCopy.Close () or SqlConnection.Close () from this event. Doing this will cause an being thrown, and the object state will not change. If the user wants to cancel the operation from the event, the property of the can be used. (See [Transaction and Bulk Copy Operations](/dotnet/framework/data/adonet/sql/transaction-and-bulk-copy-operations) for examples that use the property.) No action, such as transaction activity, is supported in the connection during the execution of the bulk copy operation, and it is recommended that you not use the same connection used during the event. However, you can open a different connection. ## Examples - The following console application demonstrates how to bulk load data using a connection that is already open. The property is set so that the event handler is called after every 50 rows copied to the table. + The following console application demonstrates how to bulk load data using a connection that is already open. The property is set so that the event handler is called after every 50 rows copied to the table. In this example, the connection is first used to read data from a SQL Server table to a instance. Note that the source data does not have to be located on SQL Server; you can use any data source that can be read to an or loaded to a . diff --git a/xml/System.Data.SqlClient/SqlBulkCopyColumnMapping.xml b/xml/System.Data.SqlClient/SqlBulkCopyColumnMapping.xml index 732448f2c31..4c95c85abd1 100644 --- a/xml/System.Data.SqlClient/SqlBulkCopyColumnMapping.xml +++ b/xml/System.Data.SqlClient/SqlBulkCopyColumnMapping.xml @@ -33,28 +33,28 @@ Defines the mapping between a column in a instance's data source and a column in the instance's destination table. - collection is empty - the columns are mapped implicitly based on ordinal position. For this to work, source and target schemas must match. If they do not, an will be thrown. - - If the collection is not empty, not every column present in the data source has to be specified. Those not mapped by the collection are ignored. - - You can refer to source and target columns by either name or ordinal. You can also mix by-name and by-ordinal column references in the same mappings collection. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, and each destination column is in the same ordinal position as its corresponding source column, the column names do not match. objects are used to create a column map for the bulk copy. - + collection is empty - the columns are mapped implicitly based on ordinal position. For this to work, source and target schemas must match. If they do not, an will be thrown. + + If the collection is not empty, not every column present in the data source has to be specified. Those not mapped by the collection are ignored. + + You can refer to source and target columns by either name or ordinal. You can also mix by-name and by-ordinal column references in the same mappings collection. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, and each destination column is in the same ordinal position as its corresponding source column, the column names do not match. objects are used to create a column map for the bulk copy. + > [!IMPORTANT] -> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. - +> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMapping/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/Overview/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -96,22 +96,22 @@ Parameterless constructor that initializes a new object. - property or the property, and define the destination for the mapping using the property or the property. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. - + property or the property, and define the destination for the mapping using the property or the property. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. + > [!IMPORTANT] -> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. - +> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMapping/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/Overview/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -149,17 +149,17 @@ The ordinal position of the destination column within the destination table. Creates a new column mapping, using column ordinals to refer to source and destination columns. - objects are used to create a column map for the bulk copy based on the ordinal positions of the columns. - + objects are used to create a column map for the bulk copy based on the ordinal positions of the columns. + > [!IMPORTANT] -> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. - +> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingOrdinal/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/.ctor/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/.ctor/source1.vb" id="Snippet1"::: + ]]> ADO.NET Overview @@ -196,17 +196,17 @@ The name of the destination column within the destination table. Creates a new column mapping, using a column ordinal to refer to the source column and a column name for the target column. - objects are used to create a column map for the bulk copy. - + objects are used to create a column map for the bulk copy. + > [!IMPORTANT] -> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. - +> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingOrdinalName/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/.ctor/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/.ctor/source2.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -244,17 +244,17 @@ The ordinal position of the destination column within the destination table. Creates a new column mapping, using a column name to refer to the source column and a column ordinal for the target column. - objects are used to create a column map for the bulk copy. - + objects are used to create a column map for the bulk copy. + > [!IMPORTANT] -> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. - +> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingNameOrdinal/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/.ctor/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -292,17 +292,17 @@ The name of the destination column within the destination table. Creates a new column mapping, using column names to refer to source and destination columns. - objects are used to create a column map for the bulk copy. - + objects are used to create a column map for the bulk copy. + > [!IMPORTANT] -> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. - +> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMapping/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/Overview/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -338,22 +338,22 @@ Name of the column being mapped in the destination database table. The string value of the property. - and properties are mutually exclusive. The last value set takes precedence. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. - + and properties are mutually exclusive. The last value set takes precedence. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. + > [!IMPORTANT] -> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. - +> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingDestinationColumn/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/DestinationColumn/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/DestinationColumn/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -389,22 +389,22 @@ Ordinal value of the destination column within the destination table. The integer value of the property, or -1 if the property has not been set. - and properties are mutually exclusive. The last value set takes precedence. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. - + and properties are mutually exclusive. The last value set takes precedence. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. + > [!IMPORTANT] -> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. - +> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingDestinationOrdinal/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/DestinationOrdinal/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/DestinationOrdinal/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -440,22 +440,22 @@ Name of the column being mapped in the data source. The string value of the property. - and properties are mutually exclusive. The last value set takes precedence. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. - + and properties are mutually exclusive. The last value set takes precedence. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. + > [!IMPORTANT] -> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. - +> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingDestinationColumn/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/DestinationColumn/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/DestinationColumn/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server @@ -491,22 +491,22 @@ The ordinal position of the source column within the data source. The integer value of the property. - and properties are mutually exclusive. The last value set takes precedence. - - - -## Examples - The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. - + and properties are mutually exclusive. The last value set takes precedence. + + + +## Examples + The following example bulk copies data from a source table in the **AdventureWorks** sample database to a destination table in the same database. Although the number of columns in the destination matches the number of columns in the source, the column names and ordinal positions do not match. objects are used to create a column map for the bulk copy. + > [!IMPORTANT] -> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. - +> This sample will not run unless you have created the work tables as described in [Bulk Copy Example Setup](/dotnet/framework/data/adonet/sql/bulk-copy-example-setup). This code is provided to demonstrate the syntax for using **SqlBulkCopy** only. If the source and destination tables are in the same SQL Server instance, it is easier and faster to use a Transact-SQL `INSERT … SELECT` statement to copy the data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlBulkCopy.ColumnMappingDestinationOrdinal/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/DestinationOrdinal/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlBulkCopyColumnMapping/DestinationOrdinal/source.vb" id="Snippet1"::: + ]]> Bulk Copy Operations in SQL Server diff --git a/xml/System.Data.SqlClient/SqlClientFactory.xml b/xml/System.Data.SqlClient/SqlClientFactory.xml index c2ceadfe962..6cf38b8c40d 100644 --- a/xml/System.Data.SqlClient/SqlClientFactory.xml +++ b/xml/System.Data.SqlClient/SqlClientFactory.xml @@ -72,7 +72,7 @@ class provides the property so that inheritors can indicate whether they can provide a data source enumerator. The displays this property, but its value is always `true`. + The class provides the property so that inheritors can indicate whether they can provide a data source enumerator. The displays this property, but its value is always `true`. diff --git a/xml/System.Data.SqlClient/SqlClientPermission.xml b/xml/System.Data.SqlClient/SqlClientPermission.xml index 14d9f92752b..27cf77d6167 100644 --- a/xml/System.Data.SqlClient/SqlClientPermission.xml +++ b/xml/System.Data.SqlClient/SqlClientPermission.xml @@ -52,7 +52,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - The property takes precedence over the property. Therefore, if you set to `false`, you must also set to `false` to prevent a user from making a connection using a blank password. + The property takes precedence over the property. Therefore, if you set to `false`, you must also set to `false` to prevent a user from making a connection using a blank password. > [!NOTE] > When using code access security permissions for ADO.NET, the correct pattern is to start with the most restrictive case (no permissions at all) and then add the specific permissions that are needed for the particular task that the code needs to perform. The opposite pattern, starting with all permissions and then denying a specific permission, is not secure, because there are many ways of expressing the same connection string. For example, if you start with all permissions and then attempt to deny the use of the connection string "server=someserver", the string "server=someserver.mycompany.com" would still be allowed. By always starting by granting no permissions at all, you reduce the chances that there are holes in the permission set. @@ -204,7 +204,7 @@ enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. For an example demonstrating how to use security demands, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). + The enumeration takes precedence over the property. Therefore, if you set to `false`, you must also set to `None` to prevent a user from making a connection using a blank password. For an example demonstrating how to use security demands, see [Code Access Security and ADO.NET](/dotnet/framework/data/adonet/code-access-security). ]]> diff --git a/xml/System.Data.SqlClient/SqlCommand.xml b/xml/System.Data.SqlClient/SqlCommand.xml index 4b61a4732c2..a232fd34b18 100644 --- a/xml/System.Data.SqlClient/SqlCommand.xml +++ b/xml/System.Data.SqlClient/SqlCommand.xml @@ -94,7 +94,7 @@ ||Retrieves a single value (for example, an aggregate value) from a database.| ||Sends the to the and builds an object.| - You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. + You can reset the property and reuse the object. However, you must close the before you can execute a new or previous command. If a is generated by the method executing a , the remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server ordinarily closes the . However, the user can reopen the connection and continue. @@ -749,9 +749,9 @@ class Program { Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. - Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . + Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . - This method ignores the property. + This method ignores the property. @@ -824,7 +824,7 @@ The closed or dropped durin ## Remarks The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that does not return rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. - The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `asyncStateObject` parameter, and your callback procedure can retrieve this information using the property. + The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `asyncStateObject` parameter, and your callback procedure can retrieve this information using the property. Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. @@ -832,7 +832,7 @@ The closed or dropped durin All errors that occur during the execution of the operation are thrown as exceptions in the callback procedure. You must handle the exception in the callback procedure, not in the main application. See the example in this topic for additional information on handling exceptions in the callback procedure. - This method ignores the property. + This method ignores the property. @@ -917,16 +917,16 @@ A other than **Xml Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. - Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . + Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. - This method ignores the property. + This method ignores the property. ## Examples - The following console application starts the process of retrieving a data reader asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. As soon as the process has completed, the code retrieves the and displays its contents. + The following console application starts the process of retrieving a data reader asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. As soon as the process has completed, the code retrieves the and displays its contents. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteReader/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlCommand/BeginExecuteReader/source.vb" id="Snippet1"::: @@ -996,15 +996,15 @@ A timeout occurred during a streaming operation. For more information about stre Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. - Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . + Because this overload does not support a callback procedure, developers must either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . If you use or to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. - This method ignores the property. + This method ignores the property. ## Examples - The following console application starts the process of retrieving a data reader asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. Once the process has completed, the code retrieves the and displays its contents. + The following console application starts the process of retrieving a data reader asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. Once the process has completed, the code retrieves the and displays its contents. This example also passes the `CommandBehavior.CloseConnection` and `CommandBehavior.SingleRow` values in the behavior parameter, causing the connection to be closed with the returned is closed, and to optimize for a single row result. @@ -1074,7 +1074,7 @@ A timeout occurred during a streaming operation. For more information about stre ## Remarks The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the returned by the command. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed cause the object to block until the execution is finished. - The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. + The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. This means that calls to may block if more data is required and the underlying network's read operation blocks. @@ -1084,7 +1084,7 @@ A timeout occurred during a streaming operation. For more information about stre If you use or to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. - This method ignores the property. + This method ignores the property. @@ -1163,7 +1163,7 @@ A other than **Xml ## Remarks The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the returned by the command. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. - The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. + The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. The `behavior` parameter lets you specify options that control the behavior of the command and its connection. These values can be combined together (using the programming language's `Or` operator); generally, developers use the `CloseConnection` value to make sure that the connection is closed by the runtime when the is closed. Developers can also optimize the behavior of the by specifying the `SingleRow` value when it is known in advance that the Transact-SQL statement or stored procedure only returns a single row. @@ -1175,7 +1175,7 @@ A other than **Xml If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. - This method ignores the property. + This method ignores the property. @@ -1260,7 +1260,7 @@ A other than **Xml ## Remarks The method starts the process of asynchronously executing a Transact-SQL statement that returns rows as XML, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the `EndExecuteXmlReader` method to finish the operation and retrieve the XML returned by the command. The method returns immediately, but until the code executes the corresponding `EndExecuteXmlReader` method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the `EndExecuteXmlReader` before the command's execution is completed causes the object to block until the execution is finished. - The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, `CommandText` can also specify a statement that returns `ntext` data that contains valid XML. + The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, `CommandText` can also specify a statement that returns `ntext` data that contains valid XML. A typical query can be formatted as in the following C# example: @@ -1274,16 +1274,16 @@ SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters are sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. Although command execution is asynchronous, value fetching is still synchronous. - Because this overload does not support a callback procedure, developers need to either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . + Because this overload does not support a callback procedure, developers need to either poll to determine whether the command has completed, using the property of the returned by the method; or wait for the completion of one or more commands using the property of the returned . If you use or to access XML data, SQL Server returns any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. - This method ignores the property. + This method ignores the property. ## Examples - The following console application starts the process of retrieving XML data asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. Once the process has completed, the code retrieves the XML and displays its contents. + The following console application starts the process of retrieving XML data asynchronously. While waiting for the results, this simple application sits in a loop, investigating the property value. Once the process has completed, the code retrieves the XML and displays its contents. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlCommand.BeginExecuteXmlReader/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlCommand/BeginExecuteXmlReader/source.vb" id="Snippet1"::: @@ -1351,7 +1351,7 @@ The closed or dropped durin ## Remarks The method starts the process of asynchronously executing a Transact-SQL statement or stored procedure that returns rows as XML, so that other tasks can run concurrently while the statement is executing. When the statement has completed, developers must call the method to finish the operation and retrieve the requested XML data. The method returns immediately, but until the code executes the corresponding method call, it must not execute any other calls that start a synchronous or asynchronous execution against the same object. Calling the before the command's execution is completed causes the object to block until the execution is finished. - The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, `CommandText` can also specify a statement that returns data that contains valid XML. This method can also be used to retrieve a single-row, single-column result set. In this case, if more than one row is returned, the method attaches the to the value on the first row, and discards the rest of the result set. + The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, `CommandText` can also specify a statement that returns data that contains valid XML. This method can also be used to retrieve a single-row, single-column result set. In this case, if more than one row is returned, the method attaches the to the value on the first row, and discards the rest of the result set. A typical query can be formatted as in the following C# example: @@ -1363,7 +1363,7 @@ SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM The multiple active result set (MARS) feature lets multiple actions use the same connection. - The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. + The `callback` parameter lets you specify an delegate that is called when the statement has completed. You can call the method from within this delegate procedure, or from any other location within your application. In addition, you can pass any object in the `stateObject` parameter, and your callback procedure can retrieve this information using the property. Note that the command text and parameters are sent to the server synchronously. If a large command or many parameters is sent, this method may block during writes. After the command is sent, the method returns immediately without waiting for an answer from the server--that is, reads are asynchronous. @@ -1371,7 +1371,7 @@ SqlCommand command = new SqlCommand("SELECT ContactID, FirstName, LastName FROM If you use or to access XML data, SQL Server will return any XML results greater than 2,033 characters in length in multiple rows of 2,033 characters each. To avoid this behavior, use or to read FOR XML queries. - This method ignores the property. + This method ignores the property. @@ -1602,7 +1602,7 @@ The closed or dropped durin property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the `Execute` methods. + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command executes this stored procedure when you call one of the `Execute` methods. The Microsoft .NET Framework Data Provider for SQL Server does not support the question mark (?) placeholder for passing parameters to a Transact-SQL statement or a stored procedure called by a command of `CommandType.Text`. In this case, named parameters must be used. For example: @@ -1679,7 +1679,7 @@ SELECT * FROM dbo.Customers WHERE CustomerID = @CustomerID A value of 0 indicates no limit (an attempt to execute a command will wait indefinitely). > [!NOTE] -> The property will be ignored by older APM (Asynchronous Programming Model) asynchronous method calls such as . It will be honored by newer TAP (Task Asynchronous Programming) methods such as . +> The property will be ignored by older APM (Asynchronous Programming Model) asynchronous method calls such as . It will be honored by newer TAP (Task Asynchronous Programming) methods such as . has no effect when the command is executed against a context connection (a opened with "context connection=true" in the connection string). @@ -1775,7 +1775,7 @@ public class A { property to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods. + When you set the property to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods. The Microsoft .NET Framework Data Provider for SQL Server does not support the question mark (?) placeholder for passing parameters to a SQL Statement or a stored procedure called with a of . In this case, named parameters must be used. For example: @@ -1856,7 +1856,7 @@ public class A { ## Remarks If the command is enlisted in an existing transaction, and the connection is changed, trying to execute the command will throw an . - If the property is not null and the transaction has already been committed or rolled back, is set to null. + If the property is not null and the transaction has already been committed or rolled back, is set to null. @@ -2555,7 +2555,7 @@ The closed or dropped durin property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . > [!NOTE] > If a transaction is deadlocked, an exception may not be thrown until is called. @@ -2638,7 +2638,7 @@ The closed or dropped durin property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . > [!NOTE] > Use to retrieve large values and binary data. Otherwise, an might occur and the connection will be closed. @@ -3166,7 +3166,7 @@ A timeout occurred during a streaming operation. For more information about stre ## Remarks The **XmlReader** returned by this method does not support asynchronous operations. - The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, can also specify a statement that returns `ntext` or `nvarchar` data that contains valid XML, or the contents of a column defined with the `xml` data type. + The property ordinarily specifies a Transact-SQL statement with a valid FOR XML clause. However, can also specify a statement that returns `ntext` or `nvarchar` data that contains valid XML, or the contents of a column defined with the `xml` data type. A typical query can be formatted as in the following Microsoft Visual C# example: @@ -3567,12 +3567,12 @@ A timeout occurred during a streaming operation. For more information about stre ## Remarks If is set to `StoredProcedure`, the call to should succeed, although it may cause a no-op. - Before you call , specify the data type of each parameter in the statement to be prepared. For each parameter that has a variable length data type, you must set the property to the maximum size needed. returns an error if these conditions are not met. + Before you call , specify the data type of each parameter in the statement to be prepared. For each parameter that has a variable length data type, you must set the property to the maximum size needed. returns an error if these conditions are not met. > [!NOTE] > If the database context is changed by executing the Transact-SQL `USE ` statement, or by calling the method, then must be called a second time. - If you call an `Execute` method after calling , any parameter value that is larger than the value specified by the property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. + If you call an `Execute` method after calling , any parameter value that is larger than the value specified by the property is automatically truncated to the original specified size of the parameter, and no truncation errors are returned. Output parameters (whether prepared or not) must have a user-specified data type. If you specify a variable length data type, you must also specify the maximum . @@ -3841,7 +3841,7 @@ This member is an explicit interface member implementation. It can be used only property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to a object that is not connected to the same as the object, an exception is thrown the next time that you attempt to execute a statement. + You cannot set the property if it is already set to a specific value, and the command is in the process of executing. If you set the transaction property to a object that is not connected to the same as the object, an exception is thrown the next time that you attempt to execute a statement. ]]> diff --git a/xml/System.Data.SqlClient/SqlCommandBuilder.xml b/xml/System.Data.SqlClient/SqlCommandBuilder.xml index 23c76a5d3cf..cec4772d6ef 100644 --- a/xml/System.Data.SqlClient/SqlCommandBuilder.xml +++ b/xml/System.Data.SqlClient/SqlCommandBuilder.xml @@ -38,11 +38,11 @@ does not automatically generate the Transact-SQL statements required to reconcile changes made to a with the associated instance of SQL Server. However, you can create a object to automatically generate Transact-SQL statements for single-table updates if you set the property of the . Then, any additional Transact-SQL statements that you do not set are generated by the . + The does not automatically generate the Transact-SQL statements required to reconcile changes made to a with the associated instance of SQL Server. However, you can create a object to automatically generate Transact-SQL statements for single-table updates if you set the property of the . Then, any additional Transact-SQL statements that you do not set are generated by the . - The registers itself as a listener for events whenever you set the property. You can only associate one or object with each other at one time. + The registers itself as a listener for events whenever you set the property. You can only associate one or object with each other at one time. - To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata has been retrieved, such as after the first update, you should call the method to update the metadata. + To generate INSERT, UPDATE, or DELETE statements, the uses the property to retrieve a required set of metadata automatically. If you change the after the metadata has been retrieved, such as after the first update, you should call the method to update the metadata. The `SelectCommand` must also return at least one primary key or unique column. If none are present, an **InvalidOperation** exception is generated, and the commands are not generated. diff --git a/xml/System.Data.SqlClient/SqlConnection.xml b/xml/System.Data.SqlClient/SqlConnection.xml index 99a7c7c04d6..3e1cdf65591 100644 --- a/xml/System.Data.SqlClient/SqlConnection.xml +++ b/xml/System.Data.SqlClient/SqlConnection.xml @@ -159,7 +159,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. + When a new instance of is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. |Properties|Initial value| |----------------|-------------------| @@ -168,7 +168,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) ||empty string ("")| ||empty string ("")| - You can change the value for these properties only by using the property. The class provides functionality for creating and managing the contents of connection strings. + You can change the value for these properties only by using the property. The class provides functionality for creating and managing the contents of connection strings. @@ -218,7 +218,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. + When a new instance of is created, the read/write properties are set to the following initial values unless they are specifically set using their associated keywords in the property. |Properties|Initial value| |----------------|-------------------| @@ -227,7 +227,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) ||empty string ("")| ||empty string ("")| - You can change the value for these properties only by using the property. The class provides functionality for creating and managing the contents of connection strings. + You can change the value for these properties only by using the property. The class provides functionality for creating and managing the contents of connection strings. @@ -736,7 +736,7 @@ using (SqlConnection connection = new SqlConnection(connectionString)) The method changes the SQL Server password for the user indicated in the supplied `connectionString` parameter to the value supplied in the `newPassword` parameter. If the connection string includes the option for integrated security (that is, "Integrated Security=True" or the equivalent), an exception is thrown. - To determine that the password has expired, calling the method raises a . In order to indicate that the password that is contained within the connection string must be reset, the property for the exception contains the status value 18487 or 18488. The first value (18487) indicates that the password has expired and the second (18488) indicates that the password must be reset before logging in. + To determine that the password has expired, calling the method raises a . In order to indicate that the password that is contained within the connection string must be reset, the property for the exception contains the status value 18487 or 18488. The first value (18487) indicates that the password has expired and the second (18488) indicates that the password must be reset before logging in. This method opens its own connection to the server, requests the password change, and closes the connection as soon as it has completed. This connection is not retrieved from or returned to the SQL Server connection pool. @@ -1182,7 +1182,7 @@ The connection string contains . The is similar to an OLE DB connection string, but is not identical. Unlike OLE DB or ADO, the connection string that is returned is the same as the user-set , minus security information if the Persist Security Info value is set to `false` (default). The .NET Framework Data Provider for SQL Server does not persist or return the password in a connection string unless you set Persist Security Info to `true`. - You can use the property to connect to a database. The following example illustrates a typical connection string. + You can use the property to connect to a database. The following example illustrates a typical connection string. ```txt "Persist Security Info=False;Integrated Security=true;Initial Catalog=Northwind;server=(local)" @@ -1190,11 +1190,11 @@ The is similar to Use the new to construct valid connection strings at run time. For more information, see [Connection String Builders](/dotnet/framework/data/adonet/connection-string-builders). - The property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, these properties are updated, except when an error is detected. In this case, none of the properties are updated. properties return only those settings that are contained in the . + The property can be set only when the connection is closed. Many of the connection string values have corresponding read-only properties. When the connection string is set, these properties are updated, except when an error is detected. In this case, none of the properties are updated. properties return only those settings that are contained in the . To connect to a local computer, specify "(local)" for the server. If a server name is not specified, a connection will be attempted to the default instance on the local computer. - Resetting the on a closed connection resets all connection string values (and related properties) including the password. For example, if you set a connection string that includes "Database= AdventureWorks", and then reset the connection string to "Data Source=myserver;Integrated Security=true", the property is no longer set to "AdventureWorks". + Resetting the on a closed connection resets all connection string values (and related properties) including the password. For example, if you set a connection string that includes "Database= AdventureWorks", and then reset the connection string to "Data Source=myserver;Integrated Security=true", the property is no longer set to "AdventureWorks". The connection string is parsed immediately after being set. If errors in syntax are found when parsing, a runtime exception, such as , is generated. Other errors can be found only when an attempt is made to open the connection. @@ -1268,7 +1268,7 @@ The is similar to > Use caution when constructing a connection string based on user input (for example when retrieving user ID and password information from a dialog box, and appending it to the connection string). Make sure that a user cannot embed additional connection string parameters in these values (for example, entering a password as "validpassword;database=somedb" in an attempt to attach to a different database). If you need to construct connection strings based on user input, use , which validates the connection string and helps to eliminate this problem. For more information, see [Connection String Builders](/dotnet/framework/data/adonet/connection-string-builders). ## Examples - The following example creates a and sets the property before opening the connection. + The following example creates a and sets the property before opening the connection. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.ConnectionString Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnection/ConnectionString/source.vb" id="Snippet1"::: @@ -1337,7 +1337,7 @@ The is similar to ## Examples - The following example creates a and sets the `Connection Timeout` to 30 seconds in the connection string. The code opens the connection and displays the property in the console window. + The following example creates a and sets the `Connection Timeout` to 30 seconds in the connection string. The code opens the connection and displays the property in the console window. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.ConnectionTimeout Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnection/ConnectionTimeout/source.vb" id="Snippet1"::: @@ -1532,7 +1532,7 @@ The is similar to property updates dynamically. If you change the current database using a Transact-SQL statement or the method, an informational message is sent and the property is updated automatically. + The property updates dynamically. If you change the current database using a Transact-SQL statement or the method, an informational message is sent and the property is updated automatically. @@ -1601,7 +1601,7 @@ The is similar to ## Remarks > [!NOTE] -> The property returns `null` if the connection string for the is "context connection=true". +> The property returns `null` if the connection string for the is "context connection=true". @@ -2596,7 +2596,7 @@ SqlConnection.RegisterColumnEncryptionKeyStoreProviders(customKeyStoreProviders) ## Examples - The following example creates a and displays the property. + The following example creates a and displays the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ISqlConnection.ServerVersion Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnection/ServerVersion/source.vb" id="Snippet1"::: @@ -2931,12 +2931,12 @@ Once the transaction has completed, you must explicitly commit or roll back the property corresponds to the `Workstation ID` connection string property. + The string typically contains the network name of the client. The property corresponds to the `Workstation ID` connection string property. ## Examples - The following example creates a and displays the property. + The following example creates a and displays the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlConnection.WorkstationId Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnection/WorkstationId/source.vb" id="Snippet1"::: diff --git a/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml b/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml index 485ca51f1eb..90018d55a11 100644 --- a/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/xml/System.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -51,7 +51,7 @@ performs checks for valid key/value pairs. Therefore, you cannot use this class to create invalid connection strings; trying to add invalid pairs will throw an exception. The class maintains a fixed collection of synonyms and can translate from a synonym to the corresponding well-known key name. - For example, when you use the `Item` property to retrieve a value, you can specify a string that contains any synonym for the key you need. For example, you can specify "Network Address", "addr", or any other acceptable synonym for this key within a connection string when you use any member that requires a string that contains the key name, such as the property or the method. See the property for a full list of acceptable synonyms. + For example, when you use the `Item` property to retrieve a value, you can specify a string that contains any synonym for the key you need. For example, you can specify "Network Address", "addr", or any other acceptable synonym for this key within a connection string when you use any member that requires a string that contains the key name, such as the property or the method. See the property for a full list of acceptable synonyms. The property handles attempts to insert malicious entries. For example, the following code, using the default `Item` property (the indexer, in C#) correctly escapes the nested key/value pair: @@ -260,7 +260,7 @@ The class provides a fix ## Examples - The following example creates a new and assigns a connection string in the object's constructor. The code displays the parsed and recreated version of the connection string, and then modifies the property of the object. Finally, the code displays the new connection string, including the new key/value pair. + The following example creates a new and assigns a connection string in the object's constructor. The code displays the parsed and recreated version of the connection string, and then modifies the property of the object. Finally, the code displays the new connection string, including the new key/value pair. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlConnectionStringBuilder.ApplicationName/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnectionStringBuilder/ApplicationName/source.vb" id="Snippet1"::: @@ -472,7 +472,7 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security method removes all key/value pairs from the , and resets all corresponding properties. This includes setting the property to 0, and setting the property to an empty string. + The method removes all key/value pairs from the , and resets all corresponding properties. This includes setting the property to 0, and setting the property to an empty string. @@ -702,7 +702,7 @@ Modified: Data Source=(local);Initial Catalog=AdventureWorks;Integrated Security ## Examples - The following example first displays the contents of a connection string that does not specify the "Connect Timeout" value, sets the property, and then displays the new connection string. + The following example first displays the contents of a connection string that does not specify the "Connect Timeout" value, sets the property, and then displays the new connection string. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlConnectionStringBuilder.ConnectTimeout/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnectionStringBuilder/ConnectTimeout/source.vb" id="Snippet1"::: @@ -817,7 +817,7 @@ False This property corresponds to the "Context Connection" key within the connection string. > [!NOTE] -> The property returns `null` if the connection string for the is "context connection=true". +> The property returns `null` if the connection string for the is "context connection=true". ]]> @@ -1195,7 +1195,7 @@ False ## Examples - The following example creates a simple connection string and then uses the class to add the name of the database to the connection string. The code displays the contents of the property, just to verify that the class was able to convert from the synonym ("Database") to the appropriate property value. + The following example creates a simple connection string and then uses the class to add the name of the database to the connection string. The code displays the contents of the property, just to verify that the class was able to convert from the synonym ("Database") to the appropriate property value. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlConnectionStringBuilder.InitialCatalog/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnectionStringBuilder/InitialCatalog/source.vb" id="Snippet1"::: @@ -1325,7 +1325,7 @@ This property corresponds to the "Integrated Security" and "trusted_connection" ## Examples - The following code, in a console application, creates a new and adds key/value pairs to its connection string, using the property. + The following code, in a console application, creates a new and adds key/value pairs to its connection string, using the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlConnectionStringBuilder.Item/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnectionStringBuilder/Item/source.vb" id="Snippet1"::: @@ -1372,12 +1372,12 @@ This property corresponds to the "Integrated Security" and "trusted_connection" is unspecified, but it is the same order as the associated values in the returned by the property. + The order of the values in the is unspecified, but it is the same order as the associated values in the returned by the property. ## Examples - The following console application example creates a new . The code loops through the returned by the property displaying the key/value pairs. + The following console application example creates a new . The code loops through the returned by the property displaying the key/value pairs. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlConnectionStringBuilder.Keys/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlConnectionStringBuilder/Keys/source.vb" id="Snippet1"::: @@ -2167,11 +2167,11 @@ This property corresponds to the "Integrated Security" and "trusted_connection" ## Remarks The Transaction Binding keywords in a control how a binds to an enlisted . - The following table shows the possible values for the property: + The following table shows the possible values for the property: |Value|Description| |-----------|-----------------| -|Implicit Unbind|The default. Causes the connection to detach from the transaction when it ends. After detaching, additional requests on the connection are performed in autocommit mode. The property is not checked when executing requests while the transaction is active. After the transaction has ended, additional requests are performed in autocommit mode.| +|Implicit Unbind|The default. Causes the connection to detach from the transaction when it ends. After detaching, additional requests on the connection are performed in autocommit mode. The property is not checked when executing requests while the transaction is active. After the transaction has ended, additional requests are performed in autocommit mode.| |Explicit Unbind|Causes the connection to remain attached to the transaction until the connection is closed or until is called with a `null` (`Nothing` in Visual Basic) value. An is thrown if is not the enlisted transaction or if the enlisted transaction is not active. This behavior enforces the strict scoping rules required for support.| ]]> @@ -2569,7 +2569,7 @@ Unable to retrieve value for null key. is unspecified, but it is the same order as the associated keys in the returned by the property. Because each instance of the always contains the same fixed set of keys, the property always returns the values corresponding to the fixed set of keys, in the same order as the keys. + The order of the values in the is unspecified, but it is the same order as the associated keys in the returned by the property. Because each instance of the always contains the same fixed set of keys, the property always returns the values corresponding to the fixed set of keys, in the same order as the keys. diff --git a/xml/System.Data.SqlClient/SqlDataAdapter.xml b/xml/System.Data.SqlClient/SqlDataAdapter.xml index f606b8eba41..7ee7fd4c202 100644 --- a/xml/System.Data.SqlClient/SqlDataAdapter.xml +++ b/xml/System.Data.SqlClient/SqlDataAdapter.xml @@ -75,7 +75,7 @@ , serves as a bridge between a and SQL Server for retrieving and saving data. The provides this bridge by mapping , which changes the data in the to match the data in the data source, and , which changes the data in the data source to match the data in the , using the appropriate Transact-SQL statements against the data source. The update is performed on a by-row basis. For every inserted, modified, and deleted row, the method determines the type of change that has been performed on it (`Insert`, `Update`, or `Delete`). Depending on the type of change, the `Insert`, `Update`, or `Delete` command template executes to propagate the modified row to the data source. When the fills a , it creates the necessary tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using `FillSchema`. For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). + The , serves as a bridge between a and SQL Server for retrieving and saving data. The provides this bridge by mapping , which changes the data in the to match the data in the data source, and , which changes the data in the data source to match the data in the , using the appropriate Transact-SQL statements against the data source. The update is performed on a by-row basis. For every inserted, modified, and deleted row, the method determines the type of change that has been performed on it (`Insert`, `Update`, or `Delete`). Depending on the type of change, the `Insert`, `Update`, or `Delete` command template executes to propagate the modified row to the data source. When the fills a , it creates the necessary tables and columns for the returned data if they do not already exist. However, primary key information is not included in the implicitly created schema unless the property is set to . You may also have the create the schema of the , including primary key information, before filling it with data using `FillSchema`. For more information, see [Adding Existing Constraints to a DataSet](/dotnet/framework/data/adonet/adding-existing-constraints-to-a-dataset). is used in conjunction with and to increase performance when connecting to a SQL Server database. @@ -88,7 +88,7 @@ The , , and are generic templates that are automatically filled with individual values from every modified row through the parameters mechanism. - For every column that you propagate to the data source on , a parameter should be added to the `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The property of the object should be set to the name of the column. This setting indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. + For every column that you propagate to the data source on , a parameter should be added to the `InsertCommand`, `UpdateCommand`, or `DeleteCommand`. The property of the object should be set to the name of the column. This setting indicates that the value of the parameter is not set manually, but is taken from the particular column in the currently processed row. > [!NOTE] > An will occur if the method is called and the table contains a user-defined type that is not available on the client computer. For more information, see [CLR User-Defined Types](/sql/relational-databases/clr-integration-database-objects-user-defined-types/clr-user-defined-types). @@ -195,7 +195,7 @@ constructor sets the property to the value specified in the `selectCommand` parameter. + This implementation of the constructor sets the property to the value specified in the `selectCommand` parameter. When an instance of is created, the following read/write properties are set to the following initial values. @@ -309,7 +309,7 @@ constructor uses the `selectCommandText` parameter to set the property. The will create and maintain the connection created with the `selectConnectionString` parameter. + This overload of the constructor uses the `selectCommandText` parameter to set the property. The will create and maintain the connection created with the `selectConnectionString` parameter. When an instance of is created, the following read/write properties are set to the following initial values. @@ -515,7 +515,7 @@ , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. @@ -729,7 +729,7 @@ , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. @@ -1287,7 +1287,7 @@ ## Remarks Gets or sets a value that enables or disables batch processing support, and specifies the number of commands that can be executed in a batch. - Use the property to update a data source with changes from a . This can increase application performance by reducing the number of round-trips to the server. + Use the property to update a data source with changes from a . This can increase application performance by reducing the number of round-trips to the server. Executing an extremely large batch could decrease performance. Therefore, you should test for the optimum batch size setting before implementing your application. @@ -1350,7 +1350,7 @@ , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + During , if this property is not set and primary key information is present in the , the can be generated automatically if you set the property and use the . Then, any additional commands that you do not set are generated by the . This generation logic requires key column information to be present in the . For more information, see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. diff --git a/xml/System.Data.SqlClient/SqlDataReader.xml b/xml/System.Data.SqlClient/SqlDataReader.xml index 8fc0961b746..7bcb47aec6b 100644 --- a/xml/System.Data.SqlClient/SqlDataReader.xml +++ b/xml/System.Data.SqlClient/SqlDataReader.xml @@ -64,7 +64,7 @@ Changes made to a result set by another process or thread while data is being read may be visible to the user of the `SqlDataReader`. However, the precise behavior is timing dependent. - and are the only properties that you can call after the is closed. Although the property may be accessed while the exists, always call before returning the value of to guarantee an accurate return value. + and are the only properties that you can call after the is closed. Although the property may be accessed while the exists, always call before returning the value of to guarantee an accurate return value. When using sequential access (), an will be raised if the position is advanced and another read operation is attempted on the previous column. diff --git a/xml/System.Data.SqlClient/SqlDependency.xml b/xml/System.Data.SqlClient/SqlDependency.xml index a2fc4357eda..362aa533853 100644 --- a/xml/System.Data.SqlClient/SqlDependency.xml +++ b/xml/System.Data.SqlClient/SqlDependency.xml @@ -245,9 +245,9 @@ event, you can check the property to determine if the query results have changed. + If you are not using the event, you can check the property to determine if the query results have changed. - The property does not necessarily imply a change in the data. Other circumstances, such as time-out expired and failure to set the notification request, also generate a change event. + The property does not necessarily imply a change in the data. Other circumstances, such as time-out expired and failure to set the notification request, also generate a change event. ]]> @@ -282,7 +282,7 @@ property is used to uniquely identify a given instance. + The property is used to uniquely identify a given instance. ]]> @@ -316,7 +316,7 @@ occurs when the results for the associated command change. If you are not using , you can check the property to determine whether the query results have changed. + occurs when the results for the associated command change. If you are not using , you can check the property to determine whether the query results have changed. The event does not necessarily imply a change in the data. Other circumstances, such as time-out expired and failure to set the notification request, also generate . diff --git a/xml/System.Data.SqlClient/SqlException.xml b/xml/System.Data.SqlClient/SqlException.xml index 594de7b44f0..05f32b83d80 100644 --- a/xml/System.Data.SqlClient/SqlException.xml +++ b/xml/System.Data.SqlClient/SqlException.xml @@ -47,69 +47,69 @@ The exception that is thrown when SQL Server returns a warning or error. This class cannot be inherited. - always contains at least one instance of . - - Messages that have a severity level of 10 or less are informational and indicate problems caused by mistakes in information that a user has entered. Severity levels from 11 through 16 are generated by the user, and can be corrected by the user. Severity levels from 17 through 25 indicate software or hardware errors. When a level 17, 18, or 19 error occurs, you can continue working, although you might not be able to execute a particular statement. - - The remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server ordinarily closes the . However, the user can reopen the connection and continue. In both cases, a is generated by the method executing the command. - - For information about the warning and informational messages sent by SQL Server, see [Database Engine Events and Errors](/sql/relational-databases/errors-events/database-engine-events-and-errors). The class maps to SQL Server severity. - - The following is general information on handling exceptions. Your code should catch exceptions to prevent the application from crashing and to allow displaying a relevant error message to the user. You can use database transactions to ensure that the data is consistent regardless of what happens in the client application (including a crash). Features like System.Transaction.TransactionScope or the BeginTransaction method (in System.Data.OleDb.OleDbConnection, System.Data.ODBC.ODBCConnection, and System.Data.SqlClient.SqlConnection) ensure consistent data regardless of exceptions raised by a provider. Transactions can fail, so catch failures and retry the transaction. - - Note that beginning with .NET Framework 4.5, can return an inner . - - The exception class of a .NET Framework data provider reports provider-specific errors. For example System.Data.Odbc has OdbcException, System.Data.OleDb has OleDbException, and System.Data.SqlClient has SqlException. For the best level of error detail, catch these exceptions and use the members of these exception classes to get details of the error. - - In addition to the provider-specific errors, .NET Framework data provider types can raise .NET Framework exceptions such as System.OutOfMemoryException and System.Threading.ThreadAbortException. Recovery from these exceptions may not be possible. - - Bad input can cause a .NET Framework data provider type to raise an exception such as System.ArgumentException or System.IndexOutOfRangeException. Calling a method at the wrong time can raise System.InvalidOperationException. - - So, in general, write an exception handler that catches any provider specific exceptions as well as exceptions from the common language runtime. These can be layered as follows: - -```csharp -try { - // code here -} -catch (SqlException odbcEx) { - // Handle more specific SqlException exception here. -} -catch (Exception ex) { - // Handle generic ones here. -} - -``` - - Or: - -```csharp -try { - // code here -} -catch (Exception ex) { - if (ex is SqlException) { - // Handle more specific SqlException exception here. - } - else { - // Handle generic ones here. - } -} - -``` - - It is also possible for a .NET Framework data provider method call to fail on a thread pool thread with no user code on the stack. In this case, and when using asynchronous method calls, you must register the event to handle those exceptions and avoid application crash. - - - -## Examples - The following example generates a and then displays the exception. - + always contains at least one instance of . + + Messages that have a severity level of 10 or less are informational and indicate problems caused by mistakes in information that a user has entered. Severity levels from 11 through 16 are generated by the user, and can be corrected by the user. Severity levels from 17 through 25 indicate software or hardware errors. When a level 17, 18, or 19 error occurs, you can continue working, although you might not be able to execute a particular statement. + + The remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server ordinarily closes the . However, the user can reopen the connection and continue. In both cases, a is generated by the method executing the command. + + For information about the warning and informational messages sent by SQL Server, see [Database Engine Events and Errors](/sql/relational-databases/errors-events/database-engine-events-and-errors). The class maps to SQL Server severity. + + The following is general information on handling exceptions. Your code should catch exceptions to prevent the application from crashing and to allow displaying a relevant error message to the user. You can use database transactions to ensure that the data is consistent regardless of what happens in the client application (including a crash). Features like System.Transaction.TransactionScope or the BeginTransaction method (in System.Data.OleDb.OleDbConnection, System.Data.ODBC.ODBCConnection, and System.Data.SqlClient.SqlConnection) ensure consistent data regardless of exceptions raised by a provider. Transactions can fail, so catch failures and retry the transaction. + + Note that beginning with .NET Framework 4.5, can return an inner . + + The exception class of a .NET Framework data provider reports provider-specific errors. For example System.Data.Odbc has OdbcException, System.Data.OleDb has OleDbException, and System.Data.SqlClient has SqlException. For the best level of error detail, catch these exceptions and use the members of these exception classes to get details of the error. + + In addition to the provider-specific errors, .NET Framework data provider types can raise .NET Framework exceptions such as System.OutOfMemoryException and System.Threading.ThreadAbortException. Recovery from these exceptions may not be possible. + + Bad input can cause a .NET Framework data provider type to raise an exception such as System.ArgumentException or System.IndexOutOfRangeException. Calling a method at the wrong time can raise System.InvalidOperationException. + + So, in general, write an exception handler that catches any provider specific exceptions as well as exceptions from the common language runtime. These can be layered as follows: + +```csharp +try { + // code here +} +catch (SqlException odbcEx) { + // Handle more specific SqlException exception here. +} +catch (Exception ex) { + // Handle generic ones here. +} + +``` + + Or: + +```csharp +try { + // code here +} +catch (Exception ex) { + if (ex is SqlException) { + // Handle more specific SqlException exception here. + } + else { + // Handle generic ones here. + } +} + +``` + + It is also possible for a .NET Framework data provider method call to fail on a thread pool thread with no user code on the stack. In this case, and when using asynchronous method calls, you must register the event to handle those exceptions and avoid application crash. + + + +## Examples + The following example generates a and then displays the exception. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlException Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Overview/source.vb" id="Snippet1"::: + ]]> @@ -147,25 +147,25 @@ catch (Exception ex) { Gets the severity level of the error returned from the .NET Framework Data Provider for SQL Server. A value from 1 to 25 that indicates the severity level of the error. - remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server ordinarily closes the . However, the user can reopen the connection and continue. In both cases, a is generated by the method executing the command. - - For information about the warning and informational messages sent by SQL Server, see the Troubleshooting section of the SQL Server documentation. - - This is a wrapper for the property of the first in the property. - - - -## Examples - The following example displays each within the collection. - + remains open when the severity level is 19 or less. When the severity level is 20 or greater, the server ordinarily closes the . However, the user can reopen the connection and continue. In both cases, a is generated by the method executing the command. + + For information about the warning and informational messages sent by SQL Server, see the Troubleshooting section of the SQL Server documentation. + + This is a wrapper for the property of the first in the property. + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlException.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: + ]]> @@ -205,11 +205,11 @@ catch (Exception ex) { Represents the client connection ID. For more information, see Data Tracing in ADO.NET. The client connection ID. - . - + . + ]]> @@ -250,21 +250,21 @@ catch (Exception ex) { Gets a collection of one or more objects that give detailed information about exceptions generated by the .NET Framework Data Provider for SQL Server. The collected instances of the class. - class always contains at least one instance of the class. - - This is a wrapper for . For more information on SQL Server engine errors, see [Database Engine Events and Errors](/sql/relational-databases/errors-events/database-engine-events-and-errors). - - - -## Examples - The following example displays each within the collection. - + class always contains at least one instance of the class. + + This is a wrapper for . For more information on SQL Server engine errors, see [Database Engine Events and Errors](/sql/relational-databases/errors-events/database-engine-events-and-errors). + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlError Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlError/Overview/source.vb" id="Snippet1"::: + ]]> @@ -302,11 +302,11 @@ catch (Exception ex) { The that contains contextual information about the source or destination. Sets the with information about the exception. - The parameter is a null reference ( in Visual Basic). @@ -343,21 +343,21 @@ catch (Exception ex) { Gets the line number within the Transact-SQL command batch or stored procedure that generated the error. The line number within the Transact-SQL command batch or stored procedure that generated the error. - property of the first in the property. - - - -## Examples - The following example displays each within the collection. - + property of the first in the property. + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlException.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: + ]]> @@ -423,19 +423,19 @@ catch (Exception ex) { Gets a number that identifies the type of error. The number that identifies the type of error. - property of the first in the property. For more information on SQL Server engine errors, see [Database Engine Events and Errors](/sql/relational-databases/errors-events/database-engine-events-and-errors). - - - -## Examples - The following example displays each within the collection. - + property of the first in the property. For more information on SQL Server engine errors, see [Database Engine Events and Errors](/sql/relational-databases/errors-events/database-engine-events-and-errors). + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlException.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: + ]]> @@ -477,19 +477,19 @@ catch (Exception ex) { Gets the name of the stored procedure or remote procedure call (RPC) that generated the error. The name of the stored procedure or RPC. - property of the first in the property. - - - -## Examples - The following example displays each within the collection. - + property of the first in the property. + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlException.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: + ]]> @@ -531,19 +531,19 @@ catch (Exception ex) { Gets the name of the computer that is running an instance of SQL Server that generated the error. The name of the computer running an instance of SQL Server. - property of the first in the property. - - - -## Examples - The following example displays each within the collection. - + property of the first in the property. + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlException.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: + ]]> @@ -585,19 +585,19 @@ catch (Exception ex) { Gets the name of the provider that generated the error. The name of the provider that generated the error. - property of the first in the property. - - - -## Examples - The following example displays each within the collection. - + property of the first in the property. + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlException.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: + ]]> @@ -639,19 +639,19 @@ catch (Exception ex) { Gets a numeric error code from SQL Server that represents an error, warning or "no data found" message. For more information about how to decode these values, see Database Engine Events and Errors. The number representing the error code. - property of the first in the property. - - - -## Examples - The following example displays each within the collection. - + property of the first in the property. + + + +## Examples + The following example displays each within the collection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlException.State Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlClient/SqlException/Class/source.vb" id="Snippet1"::: + ]]> @@ -691,54 +691,54 @@ catch (Exception ex) { Returns a string that represents the current object, and includes the client connection ID (for more information, see ). A string that represents the current object.. - , which includes the client connection ID: - -```csharp -using System.Data.SqlClient; -using System; - -public class A { - public static void Main() { - SqlConnection connection = new SqlConnection(); - connection.ConnectionString = "Data Source=a_valid_server;Initial Catalog=Northwinda;Integrated Security=true"; - try { - connection.Open(); - } - catch (SqlException p) { - Console.WriteLine("{0}", p.ClientConnectionId); - Console.WriteLine("{0}", p.ToString()); - } - connection.Close(); - } -} -``` - - The following Visual Basic sample is functionally equivalent to the previous (C#) sample: - -```vb -Imports System.Data.SqlClient -Imports System - -Module Module1 - - Sub Main() - Dim connection As New SqlConnection() - connection.ConnectionString = "Data Source=a_valid_server;Initial Catalog=Northwinda;Integrated Security=true" - Try - connection.Open() - Catch p As SqlException - Console.WriteLine("{0}", p.ClientConnectionId) - Console.WriteLine("{0}", p.ToString()) - End Try - connection.Close() - End Sub - -End Module -``` - + , which includes the client connection ID: + +```csharp +using System.Data.SqlClient; +using System; + +public class A { + public static void Main() { + SqlConnection connection = new SqlConnection(); + connection.ConnectionString = "Data Source=a_valid_server;Initial Catalog=Northwinda;Integrated Security=true"; + try { + connection.Open(); + } + catch (SqlException p) { + Console.WriteLine("{0}", p.ClientConnectionId); + Console.WriteLine("{0}", p.ToString()); + } + connection.Close(); + } +} +``` + + The following Visual Basic sample is functionally equivalent to the previous (C#) sample: + +```vb +Imports System.Data.SqlClient +Imports System + +Module Module1 + + Sub Main() + Dim connection As New SqlConnection() + connection.ConnectionString = "Data Source=a_valid_server;Initial Catalog=Northwinda;Integrated Security=true" + Try + connection.Open() + Catch p As SqlException + Console.WriteLine("{0}", p.ClientConnectionId) + Console.WriteLine("{0}", p.ToString()) + End Try + connection.Close() + End Sub + +End Module +``` + ]]> diff --git a/xml/System.Data.SqlClient/SqlInfoMessageEventArgs.xml b/xml/System.Data.SqlClient/SqlInfoMessageEventArgs.xml index 4b0fada00d0..d48d4b1143b 100644 --- a/xml/System.Data.SqlClient/SqlInfoMessageEventArgs.xml +++ b/xml/System.Data.SqlClient/SqlInfoMessageEventArgs.xml @@ -34,13 +34,13 @@ Provides data for the event. - event contains a collection which contains the warnings sent from the server. - - An event is generated when a SQL Server message with a severity level of 10 or less occurs. - + event contains a collection which contains the warnings sent from the server. + + An event is generated when a SQL Server message with a severity level of 10 or less occurs. + ]]> ADO.NET Overview @@ -109,11 +109,11 @@ Gets the full text of the error sent from the database. The full text of the error. - property of the first in the collection. - + property of the first in the collection. + ]]> ADO.NET Overview @@ -149,11 +149,11 @@ Gets the name of the object that generated the error. The name of the object that generated the error. - property of the first in the collection. - + property of the first in the collection. + ]]> ADO.NET Overview diff --git a/xml/System.Data.SqlClient/SqlParameter.xml b/xml/System.Data.SqlClient/SqlParameter.xml index 2b83fc76d0f..6bb5fca2a05 100644 --- a/xml/System.Data.SqlClient/SqlParameter.xml +++ b/xml/System.Data.SqlClient/SqlParameter.xml @@ -844,7 +844,7 @@ If you do not perform this conversion, the compiler assumes that you are trying property. + The locale identifies conventions and language for a particular geographical region. The codepage used to encode a specific string (the character set) is based on the locale used by that string or the environment that produced it. This property sets (for input parameters) or gets (for output parameters) the locale to be attached to a string when exchanging data with the server. This property is typically used together with the property. ```csharp static void CreateSqlParameterLocaleId(){ @@ -1046,7 +1046,7 @@ static void CreateSqlParameterLocaleId(){ property is used by parameters that have a of `Decimal`. + The property is used by parameters that have a of `Decimal`. You do not need to specify values for the and properties for input parameters, as they can be inferred from the parameter value. `Precision` and `Scale` are required for output parameters and for scenarios where you need to specify complete metadata for a parameter without indicating a value, such as specifying a null value with a specific precision and scale. @@ -1204,10 +1204,10 @@ static void CreateSqlParameterLocaleId(){ property is used by parameters that have a of `Decimal`, `DateTime2`, `DateTimeOffset`, or `Time`. + The property is used by parameters that have a of `Decimal`, `DateTime2`, `DateTimeOffset`, or `Time`. > [!WARNING] -> Data may be truncated if the property is not explicitly specified and the data on the server does not fit in scale 0 (the default). +> Data may be truncated if the property is not explicitly specified and the data on the server does not fit in scale 0 (the default). > For the `DateTime2` type, scale 0 (the default) will be passed as datetime2(7). There is currently no way to send a parameter as datetime2(0). Scales 1-7 work as expected. > This problem applies to `DateTimeOffset` and `Time` as well. @@ -1289,9 +1289,9 @@ static void CreateSqlParameterLocaleId(){ For output parameters with a variable length type (nvarchar, for example), the size of the parameter defines the size of the buffer holding the output parameter. The output parameter can be truncated to a size specified with . For character types, the size specified with is in characters. - The property is used for binary and string types. For parameters of type `SqlType.String`, `Size` means length in Unicode characters. For parameters of type `SqlType.Xml`, `Size` is ignored. + The property is used for binary and string types. For parameters of type `SqlType.String`, `Size` means length in Unicode characters. For parameters of type `SqlType.Xml`, `Size` is ignored. - For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. + For nonstring data types and ANSI string data, the property refers to the number of bytes. For Unicode string data, refers to the number of characters. The count for strings does not include the terminating character. For variable-length data types, describes the maximum amount of data to transmit to the server. For example, for a Unicode string value, could be used to limit the amount of data sent to the server to the first one hundred characters. @@ -1371,7 +1371,7 @@ static void CreateSqlParameterLocaleId(){ ## Remarks When is set to anything other than an empty string, the value of the parameter is retrieved from the column with the name. If is set to `Input`, the value is taken from the . If is set to `Output`, the value is taken from the data source. A of `InputOutput` is a combination of both. - For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). + For more information about how to use the property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters) and [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). @@ -1626,9 +1626,9 @@ FieldName = @OriginalFieldName Both the and properties can be inferred by setting the . - The property is overwritten by `SqlDataAdapter.UpdateCommand`. + The property is overwritten by `SqlDataAdapter.UpdateCommand`. - Use the property to return parameter values as common language runtime (CLR) types. + Use the property to return parameter values as common language runtime (CLR) types. For information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). @@ -1878,7 +1878,7 @@ FieldName = @OriginalFieldName Both the and properties can be inferred by setting the Value. - The property is overwritten by `SqlDataAdapter.UpdateCommand`. + The property is overwritten by `SqlDataAdapter.UpdateCommand`. For information about streaming, see [SqlClient Streaming Support](/dotnet/framework/data/adonet/sqlclient-streaming-support). diff --git a/xml/System.Data.SqlClient/SqlParameterCollection.xml b/xml/System.Data.SqlClient/SqlParameterCollection.xml index e143afb9c53..8bf614be7ca 100644 --- a/xml/System.Data.SqlClient/SqlParameterCollection.xml +++ b/xml/System.Data.SqlClient/SqlParameterCollection.xml @@ -1012,7 +1012,7 @@ This member is an explicit interface member implementation. It can be used only Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. The method 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 . + Initially, the enumerator is positioned before the first element in the collection. The method 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 . returns the same object until either or is called. sets to the next element. @@ -1524,7 +1524,7 @@ This member is an explicit interface member implementation. It can be used only Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - The following code example shows how to lock the collection using the property during the entire enumeration. + The following code example shows how to lock the collection using the property during the entire enumeration. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/ICollection/IsSynchronized/remarks.cs" id="Snippet1"::: @@ -2019,7 +2019,7 @@ This member is an explicit interface member implementation. It can be used only This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. In the absence of a `Synchronized` method on a collection, the expected usage for looks as follows: @@ -2031,7 +2031,7 @@ This member is an explicit interface member implementation. It can be used only ## Examples - The following code example shows how to lock the collection using the property during the entire enumeration. + The following code example shows how to lock the collection using the property during the entire enumeration. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.collections.icollection/cpp/remarks.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Collections/ICollection/IsSynchronized/remarks.cs" id="Snippet1"::: diff --git a/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml b/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml index d4040f860a8..8149f1dea13 100644 --- a/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml +++ b/xml/System.Data.SqlClient/SqlRowsCopiedEventArgs.xml @@ -65,11 +65,11 @@ An that indicates the number of rows copied during the current bulk copy operation. Creates a new instance of the object. - ADO.NET Overview @@ -105,15 +105,15 @@ if the bulk copy operation should be aborted; otherwise . - property to cancel a bulk copy operation. Set to `true` to abort the bulk copy operation. - - If you call the **Close** method from , an exception is generated, and the object state does not change. - - If an application specifically creates a object in the constructor, the transaction is not rolled back. The application is responsible for determining whether it is required to rollback the operation, and if so, it must call the method. If the application does not create a transaction, the internal transaction corresponding to the current batch is automatically rolled back. However, changes related to previous batches within the bulk copy operation are retained, because the transactions for them already have been committed. - + property to cancel a bulk copy operation. Set to `true` to abort the bulk copy operation. + + If you call the **Close** method from , an exception is generated, and the object state does not change. + + If an application specifically creates a object in the constructor, the transaction is not rolled back. The application is responsible for determining whether it is required to rollback the operation, and if so, it must call the method. If the application does not create a transaction, the internal transaction corresponding to the current batch is automatically rolled back. However, changes related to previous batches within the bulk copy operation are retained, because the transactions for them already have been committed. + ]]> ADO.NET Overview @@ -149,11 +149,11 @@ that returns the number of rows copied. - property is reset on each call to any of the `SqlBulkCopy.WriteToServer` methods. - + property is reset on each call to any of the `SqlBulkCopy.WriteToServer` methods. + ]]> ADO.NET Overview diff --git a/xml/System.Data.SqlTypes/INullable.xml b/xml/System.Data.SqlTypes/INullable.xml index e8575836989..a871c729970 100644 --- a/xml/System.Data.SqlTypes/INullable.xml +++ b/xml/System.Data.SqlTypes/INullable.xml @@ -48,11 +48,11 @@ All the objects and structures implement the interface. - Handling Null Values @@ -105,26 +105,26 @@ if the value of this object is null. Otherwise, . - instance is null. Use property to test for null values. - - - -## Examples - The following code example creates a with two columns defined as and . The code adds one row of known values, one row of null values and then iterates through the , assigning the values to variables and displaying the output in the console window. - + instance is null. Use property to test for null values. + + + +## Examples + The following code example creates a with two columns defined as and . The code adds one row of known values, one row of null values and then iterates through the , assigning the values to variables and displaying the output in the console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks SqlTypes.IsNull/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlTypes/INullable/IsNull/source.vb" id="Snippet1"::: - - This example displays the following results: - -``` -isColumnNull=False, ID=123, Description=Side Mirror -isColumnNull=True, ID=Null, Description=Null -``` - + :::code language="vb" source="~/snippets/visualbasic/System.Data.SqlTypes/INullable/IsNull/source.vb" id="Snippet1"::: + + This example displays the following results: + +``` +isColumnNull=False, ID=123, Description=Side Mirror +isColumnNull=True, ID=Null, Description=Null +``` + ]]> Handling Null Values diff --git a/xml/System.Data.SqlTypes/SqlBinary.xml b/xml/System.Data.SqlTypes/SqlBinary.xml index 706cf4d95d9..53e802945e7 100644 --- a/xml/System.Data.SqlTypes/SqlBinary.xml +++ b/xml/System.Data.SqlTypes/SqlBinary.xml @@ -187,11 +187,11 @@ Concatenates two specified values to create a new structure. A that is the concatenated value of x and y. - , followed by `y`. - + , followed by `y`. + ]]> SQL Server Data Types and ADO.NET @@ -205,11 +205,11 @@ Compares this instance to a specified object and returns an indication of their relative values. - interface. - + interface. + ]]> SQL Server Data Types and ADO.NET @@ -260,24 +260,24 @@ The object to be compared to this structure. Compares this object to the supplied object and returns an indication of their relative values. - A signed number that indicates the relative values of this structure and the object. - - Return value - - Condition - - Less than zero - - The value of this object is less than the object. - - Zero - - This object is the same as object. - - Greater than zero - - This object is greater than object, or the object is a null reference. - + A signed number that indicates the relative values of this structure and the object. + + Return value + + Condition + + Less than zero + + The value of this object is less than the object. + + Zero + + This object is the same as object. + + Greater than zero + + This object is greater than object, or the object is a null reference. + To be added. SQL Server Data Types and ADO.NET @@ -333,24 +333,24 @@ The object to be compared to this structure. Compares this object to the supplied object and returns an indication of their relative values. - A signed number that indicates the relative values of this structure and the object. - - Return value - - Condition - - Less than zero - - The value of this object is less than the object. - - Zero - - This object is the same as object. - - Greater than zero - - This object is greater than object, or the object is a null reference. - + A signed number that indicates the relative values of this structure and the object. + + Return value + + Condition + + Less than zero + + The value of this object is less than the object. + + Zero + + This object is the same as object. + + Greater than zero + + This object is greater than object, or the object is a null reference. + To be added. SQL Server Data Types and ADO.NET @@ -817,11 +817,11 @@ if ; otherwise, . - SQL Server Data Types and ADO.NET @@ -875,17 +875,17 @@ Gets the single byte from the property located at the position indicated by the integer parameter, . If indicates a position beyond the end of the byte array, a will be raised. This property is read-only. The byte located at the position indicated by the integer parameter. - , always examine the property and the property before reading this property. - + , always examine the property and the property before reading this property. + ]]> - The property is read when the property contains - + The property is read when the property contains + -or- - + The parameter indicates a position beyond the length of the byte array as indicated by the property. SQL Server Data Types and ADO.NET @@ -934,11 +934,11 @@ Gets the length in bytes of the property. This property is read-only. The length of the binary data in the property. - , always examine the property before reading the property. - + , always examine the property before reading the property. + ]]> The property is read when the property contains . @@ -1147,11 +1147,11 @@ Represents a that can be assigned to this instance of the structure. - structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). - + structure. For more information, see [Handling Null Values](/dotnet/framework/data/adonet/sql/handling-null-values). + ]]> @@ -1208,11 +1208,11 @@ Concatenates the two parameters to create a new structure. The concatenated values of the and parameters. - , followed by `y`. - + , followed by `y`. + The equivalent method for this operator is ]]> SQL Server Data Types and ADO.NET @@ -1759,11 +1759,11 @@ For a description of this member, see . An instance. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1813,11 +1813,11 @@ A . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -1867,11 +1867,11 @@ A . For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2016,11 +2016,11 @@ Gets the value of the structure. This property is read-only. The value of the structure. - property before reading the property. - + property before reading the property. + ]]> The property is read when the property contains . @@ -2057,11 +2057,11 @@ Converts an array of bytes into a structure. A structure created from an array of bytes. - structure directly from the array of bytes passed, without making a copy of them. - + structure directly from the array of bytes passed, without making a copy of them. + ]]> diff --git a/xml/System.Data.SqlTypes/SqlBytes.xml b/xml/System.Data.SqlTypes/SqlBytes.xml index 73989363de3..50ce9100da2 100644 --- a/xml/System.Data.SqlTypes/SqlBytes.xml +++ b/xml/System.Data.SqlTypes/SqlBytes.xml @@ -179,11 +179,11 @@ The array of unsigned bytes. Initializes a new instance of the class based on the specified byte array. - SQL Server Data Types and ADO.NET @@ -232,11 +232,11 @@ A value. Initializes a new instance of the class based on the specified value. - SQL Server Data Types and ADO.NET @@ -286,11 +286,11 @@ A . Initializes a new instance of the class based on the specified value. - SQL Server Data Types and ADO.NET @@ -346,13 +346,13 @@ Returns a reference to the internal buffer. A reference to the internal buffer. For instances created on top of unmanaged pointers, it returns a managed copy of the internal buffer. - . - - Throws an for stream-wrapped instances of . - + . + + Throws an for stream-wrapped instances of . + ]]> SQL Server Data Types and ADO.NET @@ -451,11 +451,11 @@ if the is null, otherwise. - SQL Server Data Types and ADO.NET @@ -552,17 +552,17 @@ Gets the length of the value that is contained in the instance. - A value representing the length of the value that is contained in the instance. - - Returns -1 if no buffer is available to the instance or if the value is null. - + A value representing the length of the value that is contained in the instance. + + Returns -1 if no buffer is available to the instance or if the value is null. + Returns a for a stream-wrapped instance. - SQL Server Data Types and ADO.NET @@ -611,11 +611,11 @@ Gets the maximum length of the value of the internal buffer of this . A long representing the maximum length of the value of the internal buffer. Returns -1 for a stream-wrapped . - SQL Server Data Types and ADO.NET @@ -834,17 +834,17 @@ Copies bytes from this instance to the passed-in buffer and returns the number of copied bytes. An long value representing the number of copied bytes. - , an exception is thrown. - - If `count` specifies more bytes to be copied than are available from the `offset` to the end of the value, only the available bytes are copied. - - An exception is thrown if the destination buffer is a null reference. - - An exception is thrown if the destination buffer cannot receive as many characters as requested. - + , an exception is thrown. + + If `count` specifies more bytes to be copied than are available from the `offset` to the end of the value, only the available bytes are copied. + + An exception is thrown if the destination buffer is a null reference. + + An exception is thrown if the destination buffer cannot receive as many characters as requested. + ]]> SQL Server Data Types and ADO.NET @@ -896,11 +896,11 @@ The long value representing the length. Sets the length of this instance. - SQL Server Data Types and ADO.NET @@ -1037,11 +1037,11 @@ Gets or sets the data of this as a stream. The stream that contains the SqlBytes data. - property loads all the data into memory. Using it with large value data can cause an . - + property loads all the data into memory. Using it with large value data can cause an . + ]]> SQL Server Data Types and ADO.NET @@ -1340,11 +1340,11 @@ This member is an explicit interface member implementation. It can be used only Returns a managed copy of the value held by this . The value of this as an array of bytes. - . - + . + ]]> SQL Server Data Types and ADO.NET @@ -1402,15 +1402,15 @@ This member is an explicit interface member implementation. It can be used only An integer representing the number of bytes to copy. Copies bytes from the passed-in buffer to this instance. - but within , is updated to reflect the new ending position. - - The value of `offsetInBuffer` must be less than or equal to . An exception is thrown otherwise. Only a value of 0 can be specified when writing to a null value instance. - - If an attempt is made to write beyond , an exception is thrown. - + but within , is updated to reflect the new ending position. + + The value of `offsetInBuffer` must be less than or equal to . An exception is thrown otherwise. Only a value of 0 can be specified when writing to a null value instance. + + If an attempt is made to write beyond , an exception is thrown. + ]]> SQL Server Data Types and ADO.NET diff --git a/xml/System.Data.SqlTypes/SqlFileStream.xml b/xml/System.Data.SqlTypes/SqlFileStream.xml index 5d381593b80..e5dfef71459 100644 --- a/xml/System.Data.SqlTypes/SqlFileStream.xml +++ b/xml/System.Data.SqlTypes/SqlFileStream.xml @@ -239,7 +239,7 @@ property to determine whether the current instance supports reading. + Use the property to determine whether the current instance supports reading. ]]> @@ -286,7 +286,7 @@ property to determine whether the current instance supports writing. + Use the property to determine whether the current instance supports writing. ]]> @@ -677,7 +677,7 @@ This method calls . property to determine whether the current instance supports writing. + Use the property to determine whether the current instance supports writing. ]]> @@ -713,7 +713,7 @@ This method calls . property to determine whether the current instance supports reading. + Use the property to determine whether the current instance supports reading. ]]> @@ -817,7 +817,7 @@ This method calls . property to determine whether the current instance supports reading. + Use the property to determine whether the current instance supports reading. ]]> @@ -886,7 +886,7 @@ This method calls . property to determine whether the current instance supports writing. + Use the property to determine whether the current instance supports writing. ]]> @@ -924,7 +924,7 @@ This method calls . property to determine whether the current instance supports writing. + Use the property to determine whether the current instance supports writing. ]]> diff --git a/xml/System.Data.SqlTypes/SqlNullValueException.xml b/xml/System.Data.SqlTypes/SqlNullValueException.xml index 5699d875813..3d206871e70 100644 --- a/xml/System.Data.SqlTypes/SqlNullValueException.xml +++ b/xml/System.Data.SqlTypes/SqlNullValueException.xml @@ -67,11 +67,11 @@ The exception that is thrown when the property of a structure is set to null. - @@ -125,18 +125,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -187,16 +187,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -290,7 +290,7 @@ . ]]> diff --git a/xml/System.Data/CommandType.xml b/xml/System.Data/CommandType.xml index e40bc9d2d0b..c73ce752901 100644 --- a/xml/System.Data/CommandType.xml +++ b/xml/System.Data/CommandType.xml @@ -47,18 +47,18 @@ Specifies how a command string is interpreted. - property is set to `StoredProcedure`, the property should be set to the name of the stored procedure to be accessed. The user may be required to use escape character syntax or include qualifying characters if any of the specified tables named contain any special characters. All rows and columns of the named table or tables will be returned when you call one of the Execute methods of a Command object. - - When the property is set to `TableDirect`, the property should be set to the name of the table to be accessed. The user may be required to use escape character syntax or include qualifying characters if any of the tables named contain any special characters. All rows and columns of the named table will be returned when you call one of the Execute methods. - - In order to access multiple tables, use a comma delimited list, without spaces or padding, containing the names of the tables to access. When the `CommandText` property names multiple tables, a join of the specified tables is returned. - + property is set to `StoredProcedure`, the property should be set to the name of the stored procedure to be accessed. The user may be required to use escape character syntax or include qualifying characters if any of the specified tables named contain any special characters. All rows and columns of the named table or tables will be returned when you call one of the Execute methods of a Command object. + + When the property is set to `TableDirect`, the property should be set to the name of the table to be accessed. The user may be required to use escape character syntax or include qualifying characters if any of the tables named contain any special characters. All rows and columns of the named table will be returned when you call one of the Execute methods. + + In order to access multiple tables, use a comma delimited list, without spaces or padding, containing the names of the tables to access. When the `CommandText` property names multiple tables, a join of the specified tables is returned. + > [!NOTE] -> `TableDirect` is only supported by the .NET Framework Data Provider for OLE DB. Multiple table access is not supported when is set to `TableDirect`. - +> `TableDirect` is only supported by the .NET Framework Data Provider for OLE DB. Multiple table access is not supported when is set to `TableDirect`. + ]]> diff --git a/xml/System.Data/Constraint.xml b/xml/System.Data/Constraint.xml index bac7c380e5e..ba9bbdec94d 100644 --- a/xml/System.Data/Constraint.xml +++ b/xml/System.Data/Constraint.xml @@ -277,7 +277,7 @@ is returned by the property of the class. + The is returned by the property of the class. diff --git a/xml/System.Data/ConstraintCollection.xml b/xml/System.Data/ConstraintCollection.xml index c1b6ae3cf28..555bbd7d655 100644 --- a/xml/System.Data/ConstraintCollection.xml +++ b/xml/System.Data/ConstraintCollection.xml @@ -76,30 +76,30 @@ Represents a collection of constraints for a . - is accessed through the property. - - The can contain both and objects for the . A object makes sure that data in a specific column is always unique to preserve the data integrity. The determines what will occur in related tables when data in the is either updated or deleted. For example, if a row is deleted, the will determine whether the related rows are also deleted (a cascade), or some other course of action. - + is accessed through the property. + + The can contain both and objects for the . A object makes sure that data in a specific column is always unique to preserve the data integrity. The determines what will occur in related tables when data in the is either updated or deleted. For example, if a row is deleted, the will determine whether the related rows are also deleted (a cascade), or some other course of action. + > [!NOTE] -> When you add a that creates a relationship between two tables to a , both a and a are created automatically. The is applied to the primary key column in the parent , and the constraint is added to that table's . The is applied to the primary key column and the foreign key column, and the constraint is added to the child table's . - - The uses standard collection methods such as , , and . In addition, the method can be used to look for the existence of a particular constraint in the collection. - - A is created when a with its property set to `true` is added to a object's . - - A is created when a is added to a object's . - - - -## Examples - The first example creates a , and adds a (with its property set to `true`) to the . The second example creates a , two objects, four columns, and a . The count of constraints is then printed to show that a and a are created when a is added to the object's . - +> When you add a that creates a relationship between two tables to a , both a and a are created automatically. The is applied to the primary key column in the parent , and the constraint is added to that table's . The is applied to the primary key column and the foreign key column, and the constraint is added to the child table's . + + The uses standard collection methods such as , , and . In addition, the method can be used to look for the existence of a particular constraint in the collection. + + A is created when a with its property set to `true` is added to a object's . + + A is created when a is added to a object's . + + + +## Examples + The first example creates a , and adds a (with its property set to `true`) to the . The second example creates a , two objects, four columns, and a . The count of constraints is then printed to show that a and a are created when a is added to the object's . + :::code language="csharp" source="~/snippets/csharp/System.Data/ConstraintCollection/Overview/constraintcollection.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Overview/source.vb" id="Snippet1"::: + ]]> This type is safe for multithreaded read operations. You must synchronize any write operations. @@ -161,19 +161,19 @@ The to add. Adds the specified object to the collection. - event occurs. - - - -## Examples - The following example adds a to the of a . - + event occurs. + + + +## Examples + The following example adds a to the of a . + :::code language="csharp" source="~/snippets/csharp/System.Data/ConstraintCollection/Add/add.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source.vb" id="Snippet1"::: + ]]> The argument is null. @@ -244,25 +244,25 @@ Constructs a new with the specified name, , and value that indicates whether the column is a primary key, and adds it to the collection. A new . - event occurs if the constraint is added successfully. - - - -## Examples - The following example uses the method to create and add a new to a . - + event occurs if the constraint is added successfully. + + + +## Examples + The following example uses the method to create and add a new to a . + :::code language="csharp" source="~/snippets/csharp/System.Data/ConstraintCollection/Add/add2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source2.vb" id="Snippet1"::: + ]]> - The constraint already belongs to this collection. - - -Or- - + The constraint already belongs to this collection. + + -Or- + The constraint belongs to another collection. The collection already has a constraint with the specified name. (The comparison is not case-sensitive.) @@ -329,19 +329,19 @@ Constructs a new with the specified name, parent column, and child column, and adds the constraint to the collection. A new . - event occurs if the constraint is added successfully. - - - -## Examples - The following example adds a new to the of a . - + event occurs if the constraint is added successfully. + + + +## Examples + The following example adds a new to the of a . + :::code language="csharp" source="~/snippets/csharp/System.Data/ConstraintCollection/Add/add3.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source3.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source3.vb" id="Snippet1"::: + ]]> @@ -407,25 +407,25 @@ Constructs a new with the specified name, array of objects, and value that indicates whether the column is a primary key, and adds it to the collection. A new . - event occurs if the constraint is added successfully. - - - -## Examples - The following example creates an array of objects that are used to create a new in a specific . - + event occurs if the constraint is added successfully. + + + +## Examples + The following example creates an array of objects that are used to create a new in a specific . + :::code language="csharp" source="~/snippets/csharp/System.Data/ConstraintCollection/Add/add1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source1.vb" id="Snippet1"::: + ]]> - The constraint already belongs to this collection. - - -Or- - + The constraint already belongs to this collection. + + -Or- + The constraint belongs to another collection. The collection already has a constraint with the specified name. (The comparison is not case-sensitive.) @@ -492,19 +492,19 @@ Constructs a new , with the specified arrays of parent columns and child columns, and adds the constraint to the collection. A new . - event occurs if the constraint is added successfully. - - - -## Examples - The following example creates two arrays of objects, and then creates two relationships between two tables in a dataset. - + event occurs if the constraint is added successfully. + + + +## Examples + The following example creates two arrays of objects, and then creates two relationships between two tables in a dataset. + :::code language="csharp" source="~/snippets/csharp/System.Data/ConstraintCollection/Add/add4.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source4.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Add/source4.vb" id="Snippet1"::: + ]]> @@ -560,19 +560,19 @@ An array of objects to add to the collection. Copies the elements of the specified array to the end of the collection. - has been called, `AddRange` does not add any objects to the collection until is called. At the time that `EndInit` is called, the collection will be populated with the items specified in the most recent call to `AddRange`. If `AddRange` is called multiple times within a `BeginInit` / `EndInit` sequence, only those items specified in the most recent call to `AddRange` are added. - - - -## Examples - The following example creates primary and foreign key constraints, and adds them to the . - + has been called, `AddRange` does not add any objects to the collection until is called. At the time that `EndInit` is called, the collection will be populated with the items specified in the most recent call to `AddRange`. If `AddRange` is called multiple times within a `BeginInit` / `EndInit` sequence, only those items specified in the most recent call to `AddRange` are added. + + + +## Examples + The following example creates primary and foreign key constraints, and adds them to the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.AddRange Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/AddRange/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/AddRange/source.vb" id="Snippet1"::: + ]]> @@ -622,19 +622,19 @@ if the can be removed from collection; otherwise, . - is added to a , is to add a to the parent table and a to the child table. The is applied to the primary key column of the parent table, and the is applied to the foreign key column of the child table. Because trying to remove the before removing the causes an exception to be thrown, you should always use the method before calling Remove, to make sure that the can be removed. - - - -## Examples - The following example uses the method to determine whether a can be removed, before trying to remove it. - + is added to a , is to add a to the parent table and a to the child table. The is applied to the primary key column of the parent table, and the is applied to the foreign key column of the child table. Because trying to remove the before removing the causes an exception to be thrown, you should always use the method before calling Remove, to make sure that the can be removed. + + + +## Examples + The following example uses the method to determine whether a can be removed, before trying to remove it. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.CanRemove Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/CanRemove/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/CanRemove/source.vb" id="Snippet1"::: + ]]> @@ -679,19 +679,19 @@ Clears the collection of any objects. - event occurs if this action is successful. - - - -## Examples - The following example clears all constraints from the . - + event occurs if this action is successful. + + + +## Examples + The following example clears all constraints from the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.Clear Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Clear/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Clear/source.vb" id="Snippet1"::: + ]]> @@ -742,19 +742,19 @@ Occurs whenever the is changed because of objects being added or removed. - event. - + event. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.CollectionChanged Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/CollectionChanged/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/CollectionChanged/source.vb" id="Snippet1"::: + ]]> @@ -805,19 +805,19 @@ if the collection contains the specified constraint; otherwise, . - method to determine whether the specified exists before trying to remove it from the collection. You can also use the method to determine whether a can be removed. - - - -## Examples - The following example determines whether the specified exists in the before its deletion. - + method to determine whether the specified exists before trying to remove it from the collection. You can also use the method to determine whether a can be removed. + + + +## Examples + The following example determines whether the specified exists in the before its deletion. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.Contains Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Contains/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Contains/source.vb" id="Snippet1"::: + ]]> @@ -924,19 +924,19 @@ Gets the index of the specified . The zero-based index of the if it is in the collection; otherwise, -1. - method to return an index to be used with either the or method. - - - -## Examples - The following example uses the method to return the index of a . The index is passed to the method, before it is removed, to determine whether the collection contains the constraint. - + method to return an index to be used with either the or method. + + + +## Examples + The following example uses the method to return the index of a . The index is passed to the method, before it is removed, to determine whether the collection contains the constraint. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.IndexOf1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/IndexOf/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/IndexOf/source1.vb" id="Snippet1"::: + ]]> @@ -994,19 +994,19 @@ Gets the index of the specified by name. The index of the if it is in the collection; otherwise, -1. - method to return an index to be used with either the or method. - - - -## Examples - The following example uses the method to return the index of a . The index is passed to the method to determine whether the collection contains the constraint, before removing it. - + method to return an index to be used with either the or method. + + + +## Examples + The following example uses the method to return the index of a . The index is passed to the method to determine whether the collection contains the constraint, before removing it. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.IndexOf Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/IndexOf/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/IndexOf/source.vb" id="Snippet1"::: + ]]> @@ -1071,19 +1071,19 @@ Gets the from the collection at the specified index. The at the specified index. - method to test for the existence of a specific constraint. - - - -## Examples - The following example gets each from the . - + method to test for the existence of a specific constraint. + + + +## Examples + The following example gets each from the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.this Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Item/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Item/source.vb" id="Snippet1"::: + ]]> The index value is greater than the number of items in the collection. @@ -1144,19 +1144,19 @@ Gets the from the collection with the specified name. The with the specified name; otherwise a null value if the does not exist. - method to test for the existence of a specific constraint. - - - -## Examples - The following example gets the named . - + method to test for the existence of a specific constraint. + + + +## Examples + The following example gets the named . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.this1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Item/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Item/source1.vb" id="Snippet1"::: + ]]> @@ -1286,19 +1286,19 @@ The to remove. Removes the specified from the collection. - method to determine whether the collection contains the target , and the method to determine whether a can be removed. - - The event occurs if the constraint is successfully removed. - - - -## Examples + method to determine whether the collection contains the target , and the method to determine whether a can be removed. + + The event occurs if the constraint is successfully removed. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.Remove Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Remove/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Remove/source.vb" id="Snippet1"::: + ]]> The argument is . @@ -1351,21 +1351,21 @@ The name of the to remove. Removes the object specified by name from the collection. - method to determine whether the collection contains the target , and the method to determine whether a can be removed. - - The event occurs if the constraint is successfully removed. - - - -## Examples - The following example removes a from a after testing for its presence with the method, and whether it can be removed with the method. - + method to determine whether the collection contains the target , and the method to determine whether a can be removed. + + The event occurs if the constraint is successfully removed. + + + +## Examples + The following example removes a from a after testing for its presence with the method, and whether it can be removed with the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.Remove1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Remove/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/Remove/source1.vb" id="Snippet1"::: + ]]> @@ -1416,23 +1416,23 @@ The index of the to remove. Removes the object at the specified index from the collection. - method returns the index of a specific . - - Before using the `RemoveAt` method, you can use the method to determine whether the collection contains the target , and the method to determine whether a can be removed. - - The event occurs if the constraint is successfully removed. - - - -## Examples - The following example uses the method together with the method to remove a constraint from the . - + method returns the index of a specific . + + Before using the `RemoveAt` method, you can use the method to determine whether the collection contains the target , and the method to determine whether a can be removed. + + The event occurs if the constraint is successfully removed. + + + +## Examples + The following example uses the method together with the method to remove a constraint from the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData ConstraintCollection.RemoveAt Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/RemoveAt/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ConstraintCollection/RemoveAt/source.vb" id="Snippet1"::: + ]]> The collection does not have a constraint at this index. diff --git a/xml/System.Data/DBConcurrencyException.xml b/xml/System.Data/DBConcurrencyException.xml index 2c30aed14f8..5d1624e0e51 100644 --- a/xml/System.Data/DBConcurrencyException.xml +++ b/xml/System.Data/DBConcurrencyException.xml @@ -57,11 +57,11 @@ The exception that is thrown by the during an insert, update, or delete operation if the number of rows affected equals zero. - examines the number of rows affected by the execution of each insert, update, or delete operation, and throws this exception if the number equals zero. This exception is generally caused by a concurrency violation. - + examines the number of rows affected by the execution of each insert, update, or delete operation, and throws this exception if the number equals zero. This exception is generally caused by a concurrency violation. + ]]> DataAdapters and DataReaders @@ -114,11 +114,11 @@ Initializes a new instance of the class. - DataAdapters and DataReaders @@ -211,11 +211,11 @@ A reference to an inner exception. Initializes a new instance of the class. - DataAdapters and DataReaders @@ -328,11 +328,11 @@ The one-dimensional array of objects to copy the objects into. Copies the objects whose update failure generated this exception, to the specified array of objects. - property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . - + property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . + ]]> DataAdapters and DataReaders @@ -382,11 +382,11 @@ The destination array index to start copying into. Copies the objects whose update failure generated this exception, to the specified array of objects, starting at the specified destination array index. - property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . - + property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . + ]]> DataAdapters and DataReaders @@ -499,15 +499,15 @@ Gets or sets the value of the that generated the . The value of the . - to retrieve the value of the row that generated the . Setting the value of the has no effect. - - When performing batch updates with the property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . - - Serialization support does not exist for objects. Therefore, if you serialize a object, the value of the property in the serialized version of the object is set to a null value. - + to retrieve the value of the row that generated the . Setting the value of the has no effect. + + When performing batch updates with the property of the set to `true`, this exception is thrown if all row updates fail. In this case, this contains objects for all rows whose update failed, rather than just the one object in , and the affected objects can be retrieved by calling . + + Serialization support does not exist for objects. Therefore, if you serialize a object, the value of the property in the serialized version of the object is set to a null value. + ]]> DataAdapters and DataReaders diff --git a/xml/System.Data/DataColumn.xml b/xml/System.Data/DataColumn.xml index 3f29968360f..0106aea503b 100644 --- a/xml/System.Data/DataColumn.xml +++ b/xml/System.Data/DataColumn.xml @@ -85,7 +85,7 @@ ## Remarks The is the fundamental building block for creating the schema of a . You build the schema by adding one or more objects to the . For more information, see [Adding Columns to a DataTable](/dotnet/framework/data/adonet/dataset-datatable-dataview/adding-columns-to-a-datatable). - Each has a property that determines the kind of data the contains. For example, you can restrict the data type to integers, or strings, or decimals. Because data that is contained by the is typically merged back into its original data source, you must match the data types to those in the data source. For more information, see [Data Type Mappings in ADO.NET](/dotnet/framework/data/adonet/data-type-mappings-in-ado-net). + Each has a property that determines the kind of data the contains. For example, you can restrict the data type to integers, or strings, or decimals. Because data that is contained by the is typically merged back into its original data source, you must match the data types to those in the data source. For more information, see [Data Type Mappings in ADO.NET](/dotnet/framework/data/adonet/data-type-mappings-in-ado-net). Properties such as , , and put restrictions on the entry and updating of data, thereby helping to guarantee data integrity. You can also use the , , and properties to control automatic data generation. For more information about columns, see [Creating AutoIncrement Columns](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-autoincrement-columns). For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). @@ -93,7 +93,7 @@ To create a relation between objects, create a object and add it to the of a . - You can use the property of the object to calculate the values in a column, or create an aggregate column. For more information, see [Creating Expression Columns](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-expression-columns). + You can use the property of the object to calculate the values in a column, or create an aggregate column. For more information, see [Creating Expression Columns](/dotnet/framework/data/adonet/dataset-datatable-dataview/creating-expression-columns). @@ -233,7 +233,7 @@ property value. + By default, the name specific to a column becomes the property value. @@ -478,11 +478,11 @@ property. The property specifies how a is mapped when a is transformed into an XML document. For example, if the column is named "fName," and the value it contains is "Bob," and `type` is set to `MappingType.Attribute`, the XML element would be as follows: + The `type` argument sets the property. The property specifies how a is mapped when a is transformed into an XML document. For example, if the column is named "fName," and the value it contains is "Bob," and `type` is set to `MappingType.Attribute`, the XML element would be as follows: \ - For more information about how columns are mapped to elements or attributes, see the property. + For more information about how columns are mapped to elements or attributes, see the property. @@ -558,7 +558,7 @@ and sets its property to `true`. + The following example creates a new and sets its property to `true`. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.AllowDBNull Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/AllowDBNull/source.vb" id="Snippet1"::: @@ -627,9 +627,9 @@ property is coerced to Int32. An exception is generated if this is a computed column. The property is set. The incremented value is used only if the row's value for this column, when added to the columns collection, is equal to the default value. + If the type of this column is not Int16, Int32, or Int64 when this property is set, the property is coerced to Int32. An exception is generated if this is a computed column. The property is set. The incremented value is used only if the row's value for this column, when added to the columns collection, is equal to the default value. - You can create a new row using the property of the class and passing in an array of values. This is a potential problem for a column with its set to `true`, because its value is generated automatically. To use the property, place `null` in the column's position in the array. For more information, see the property of the class. + You can create a new row using the property of the class and passing in an array of values. This is a potential problem for a column with its set to `true`, because its value is generated automatically. To use the property, place `null` in the column's position in the array. For more information, see the property of the class. If the type of the column is or , will not work. Use Int16 or Int32 instead. @@ -840,12 +840,12 @@ property to display a descriptive or friendly name for a . + You can use the property to display a descriptive or friendly name for a . ## Examples - The following example creates a new . It then adds three objects to a and sets the property for each . + The following example creates a new . It then adds three objects to a and sets the property for each . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.Caption Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/Caption/source.vb" id="Snippet1"::: @@ -993,9 +993,9 @@ property determines how a is mapped when a is saved as an XML document using the method. + The property determines how a is mapped when a is saved as an XML document using the method. - For example, if a is named "customerID," and its property is set to `MappingType.Element`, the column value will produce the following XML: + For example, if a is named "customerID," and its property is set to `MappingType.Element`, the column value will produce the following XML: ```xml @@ -1021,7 +1021,7 @@ Use the constructor that contains the `type` argument to specify how the is mapped when its is transformed to an XML document. - The property corresponds to the constructor argument `type`. + The property corresponds to the constructor argument `type`. @@ -1180,7 +1180,7 @@ ## Remarks Setting the value is very important for guaranteeing the correct creation and updating of data in a data source. - The property supports the following base .NET Framework data types: + The property supports the following base .NET Framework data types: - @@ -1226,7 +1226,7 @@ An exception is generated when changing this property after the column has begun storing data. - If is set to `true` before setting the property, and you try to set the type to anything except an integer type, an exception is generated. + If is set to `true` before setting the property, and you try to set the type to anything except an integer type, an exception is generated. > [!NOTE] > A column of data type `Byte[]` requires special treatment in certain cases since, unlike the base .NET Framework data types, it is a reference data type. If a column of data type `Byte[]` is used as a , or as a or key for a , any change to the column value must involve assigning the `Byte[]` column value to a separately instantiated `Byte[]` object. This assignment is required to trigger the update of the internal indexes used by sorting, filtering, and primary key operations. This is illustrated by the following example: @@ -1383,7 +1383,7 @@ myDataTable.Rows[0][0] = newValue; When is set to true, there can be no default value. - You can create a new row using the property of the class and passing the method an array of values. This is a potential problem for a column with a default value because its value is generated automatically. To use the property with such a column, place `null` in the column's position in the array. For more information, see the property. + You can create a new row using the property of the class and passing the method an array of values. This is a potential problem for a column with a default value because its value is generated automatically. To use the property with such a column, place `null` in the column's position in the array. For more information, see the property. @@ -1533,14 +1533,14 @@ The following example creates three columns in a . T property lets you store custom information with the object. For example, you may store a time when the data should be refreshed. + The property lets you store custom information with the object. For example, you may store a time when the data should be refreshed. Extended properties must be of type . Properties that are not of type are not 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. + 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/System.Data/DataColumn/ExtendedProperties/source.vb" id="Snippet1"::: @@ -1604,7 +1604,7 @@ The following example creates three columns in a . T property is ignored for non-text columns. A exception is raised if you assign to a non-string column. + The property is ignored for non-text columns. A exception is raised if you assign to a non-string column. ]]> @@ -1660,7 +1660,7 @@ The following example creates three columns in a . T property is used when reading and writing an XML document into a in the using the , , , or methods. + The property is used when reading and writing an XML document into a in 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, a contains a schema read from a document that has the namespace "myCompany," and an attempt is made to read data (with the method) from a document that has the namespace "theirCompany." Any data that does not correspond to the existing schema will be ignored. @@ -1839,7 +1839,7 @@ The following example creates three columns in a . T is used throughout an XML document to identify elements which belong to the namespace for a object (as set by the property). + The is used throughout an XML document to identify elements which belong to the namespace for a object (as set by the property). ]]> @@ -1945,7 +1945,7 @@ The following example creates three columns in a . T and sets its property `true`. + The following example creates a and sets its property `true`. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.ReadOnly Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/ReadOnly/source.vb" id="Snippet1"::: @@ -2074,7 +2074,7 @@ The following example creates three columns in a . T through its property. + The following example returns the parent table of a through its property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.Table Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/Table/source.vb" id="Snippet1"::: @@ -2129,7 +2129,7 @@ The following example creates three columns in a . T property to return the default string of each member of a collection of objects. + The following example uses the property to return the default string of each member of a collection of objects. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumn.ToString Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumn/ToString/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataColumnCollection.xml b/xml/System.Data/DataColumnCollection.xml index 80cf60a8da3..a5b45e13da6 100644 --- a/xml/System.Data/DataColumnCollection.xml +++ b/xml/System.Data/DataColumnCollection.xml @@ -79,9 +79,9 @@ defines the schema of a , and determines what kind of data each can contain. You can access the through the property of the object. + The defines the schema of a , and determines what kind of data each can contain. You can access the through the property of the object. - The uses the and methods to insert and delete objects. Use the property to determine how many objects are in the collection. Use the method to verify whether a specified index or column name exists in the collection. + The uses the and methods to insert and delete objects. Use the property to determine how many objects are in the collection. Use the method to verify whether a specified index or column name exists in the collection. @@ -1072,7 +1072,7 @@ Another column's expression depends on this column.
## Examples - The following example uses the property to print the value of a object specified by index. The example uses the that is contained by a System.Windows.Forms.DataGrid control. + The following example uses the property to print the value of a object specified by index. The example uses the that is contained by a System.Windows.Forms.DataGrid control. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnCollection.this Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/Item/source.vb" id="Snippet1"::: @@ -1147,7 +1147,7 @@ Another column's expression depends on this column.
## Examples - The following example uses the property to print the value of a object specified by index. + The following example uses the property to print the value of a object specified by index. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnCollection.this1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/Item/source1.vb" id="Snippet1"::: @@ -1322,7 +1322,7 @@ Another column's expression depends on this column.
## Examples - The following example uses the method to determine whether a named column exists. If so, the property returns the column. The method then checks whether the column can be removed; if so, the method removes it. + The following example uses the method to determine whether a named column exists. If so, the property returns the column. The method then checks whether the column can be removed; if so, the method removes it. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnCollection.Remove Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataColumnCollection/Remove/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataRelation.xml b/xml/System.Data/DataRelation.xml index ef299cdcb8c..8409794e9dc 100644 --- a/xml/System.Data/DataRelation.xml +++ b/xml/System.Data/DataRelation.xml @@ -77,30 +77,30 @@ Represents a parent/child relationship between two objects. - is used to relate two objects to each other through objects. For example, in a Customer/Orders relationship, the Customers table is the parent and the Orders table is the child of the relationship. This is similar to a primary key/foreign key relationship. For more information, see [Navigating DataRelations](/dotnet/framework/data/adonet/dataset-datatable-dataview/navigating-datarelations). - - Relationships are created between matching columns in the parent and child tables. That is, the value for both columns must be identical. - - Relationships can also cascade various changes from the parent to its child rows. To control how values are changed in child rows, add a to the of the object. The determines what action to take when a value in a parent table is deleted or updated. - - When a is created, it first verifies that the relationship can be established. After it is added to the , the relationship is maintained by disallowing any changes that would invalidate it. Between the period when a is created and added to the , it is possible for additional changes to be made to the parent or child rows. An exception is generated if this causes a relationship that is no longer valid. - + is used to relate two objects to each other through objects. For example, in a Customer/Orders relationship, the Customers table is the parent and the Orders table is the child of the relationship. This is similar to a primary key/foreign key relationship. For more information, see [Navigating DataRelations](/dotnet/framework/data/adonet/dataset-datatable-dataview/navigating-datarelations). + + Relationships are created between matching columns in the parent and child tables. That is, the value for both columns must be identical. + + Relationships can also cascade various changes from the parent to its child rows. To control how values are changed in child rows, add a to the of the object. The determines what action to take when a value in a parent table is deleted or updated. + + When a is created, it first verifies that the relationship can be established. After it is added to the , the relationship is maintained by disallowing any changes that would invalidate it. Between the period when a is created and added to the , it is possible for additional changes to be made to the parent or child rows. An exception is generated if this causes a relationship that is no longer valid. + > [!NOTE] -> Data corruption can occur if a bi-directional relation is defined between two tables. A bi-directional relation consists of two `DataRelation` objects that use the same columns, with the parent-child roles switched. No exception is raised when the `DataRelation` objects are saved; however, data corruption can occur. - - objects are contained in a , which you can access through the property of the , and the and properties of the . - - - -## Examples - The following example creates a new and adds it to the of a . - +> Data corruption can occur if a bi-directional relation is defined between two tables. A bi-directional relation consists of two `DataRelation` objects that use the same columns, with the parent-child roles switched. No exception is raised when the `DataRelation` objects are saved; however, data corruption can occur. + + objects are contained in a , which you can access through the property of the , and the and properties of the . + + + +## Examples + The following example creates a new and adds it to the of a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRelation Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/Overview/source.vb" id="Snippet1"::: + ]]> This type is safe for multithreaded read operations. You must synchronize any write operations. @@ -175,21 +175,21 @@ The child in the relationship. Initializes a new instance of the class using the specified name, and parent and child objects. - and adds it to the of a . - + and adds it to the of a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRelation.DataRelation/CS/datarelation.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/.ctor/datarelation.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/.ctor/datarelation.vb" id="Snippet1"::: + ]]> One or both of the objects contains . - The columns have different data types - - -Or- - + The columns have different data types + + -Or- + The tables do not belong to the same . @@ -247,24 +247,24 @@ An array of child objects. Initializes a new instance of the class using the specified name and matched arrays of parent and child objects. - and adds it to the of a . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/.ctor/source1.vb" id="Snippet1"::: - + and adds it to the of a . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/.ctor/source1.vb" id="Snippet1"::: + ]]> One or both of the objects contains . - The objects have different data types - - -Or- - - One or both of the arrays are not composed of distinct columns from the same table. - - -Or- - + The objects have different data types + + -Or- + + One or both of the arrays are not composed of distinct columns from the same table. + + -Or- + The tables do not belong to the same . @@ -325,20 +325,20 @@ A value that indicates whether constraints are created. , if constraints are created. Otherwise, . Initializes a new instance of the class using the specified name, parent and child objects, and a value that indicates whether to create constraints. - and adds it to the of a . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/.ctor/source.vb" id="Snippet1"::: - + and adds it to the of a . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/.ctor/source.vb" id="Snippet1"::: + ]]> One or both of the objects contains . - The columns have different data types - - -Or- - + The columns have different data types + + -Or- + The tables do not belong to the same . @@ -399,20 +399,20 @@ A value that indicates whether to create constraints. , if constraints are created. Otherwise, . Initializes a new instance of the class using the specified name, matched arrays of parent and child objects, and value that indicates whether to create constraints. - and adds it to the of a . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/.ctor/source2.vb" id="Snippet1"::: - + and adds it to the of a . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/.ctor/source2.vb" id="Snippet1"::: + ]]> One or both of the objects is . - The columns have different data types - - -Or- - + The columns have different data types + + -Or- + The tables do not belong to the same . @@ -497,11 +497,11 @@ A value that indicates whether relationships are nested. This constructor is provided for design time support in the Visual Studio environment. - object created by using this constructor must be added to the collection with the method inside of a and block. If this constructor is not called between and a will occur. In addition, the tables and columns with the specified names must exist at the time the constructor is called. - + object created by using this constructor must be added to the collection with the method inside of a and block. If this constructor is not called between and a will occur. In addition, the tables and columns with the specified names must exist at the time the constructor is called. + ]]> @@ -587,11 +587,11 @@ A value that indicates whether relationships are nested. This constructor is provided for design time support in the Visual Studio environment. - object created by using this constructor must then be added to the collection with . Tables and columns with the specified names must exist at the time the method is called, or if has been called before calling this constructor, the tables and columns with the specified names must exist at the time that is called. - + object created by using this constructor must then be added to the collection with . Tables and columns with the specified names must exist at the time the method is called, or if has been called before calling this constructor, the tables and columns with the specified names must exist at the time that is called. + ]]> @@ -636,14 +636,14 @@ This method supports .NET infrastructure and is not intended to be used directly from your code. To be added. - The parent and child tables belong to different objects. - - -Or- - - One or more pairs of parent and child objects have mismatched data types. - - -Or- - + The parent and child tables belong to different objects. + + -Or- + + One or more pairs of parent and child objects have mismatched data types. + + -Or- + The parent and child objects are identical. @@ -693,13 +693,13 @@ Gets the child objects of this relation. An array of objects. - objects of a . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ChildColumns/source.vb" id="Snippet1"::: - + objects of a . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ChildColumns/source.vb" id="Snippet1"::: + ]]> @@ -753,18 +753,18 @@ Gets the for the relation. A . - exists for this relationship, it will be created automatically, and pointed to by the `ChildKeyConstraint`, when the relation is added to the collection of relations. - - - -## Examples - The following example sets the `UpdateRule`, `DeleteRule`, and `AcceptReject` rule for the `ForeignKeyConstraint` associated with the `DataRelation`. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ChildKeyConstraint/source.vb" id="Snippet1"::: - + exists for this relationship, it will be created automatically, and pointed to by the `ChildKeyConstraint`, when the relation is added to the collection of relations. + + + +## Examples + The following example sets the `UpdateRule`, `DeleteRule`, and `AcceptReject` rule for the `ForeignKeyConstraint` associated with the `DataRelation`. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ChildKeyConstraint/source.vb" id="Snippet1"::: + ]]> @@ -812,13 +812,13 @@ Gets the child table of this relation. A that is the child table of the relation. - of a . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ChildTable/source.vb" id="Snippet1"::: - + of a . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ChildTable/source.vb" id="Snippet1"::: + ]]> @@ -880,18 +880,18 @@ Gets the to which the belongs. A to which the belongs. - associated with a is accessed through the property of the object. - - - -## Examples - The following example gets the of a . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/DataSet/source.vb" id="Snippet1"::: - + associated with a is accessed through the property of the object. + + + +## Examples + The following example gets the of a . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/DataSet/source.vb" id="Snippet1"::: + ]]> @@ -949,13 +949,13 @@ Gets the collection that stores customized properties. A that contains customized properties. - to add custom information to a object. Add information with the Add method. Retrieve information with the Item method. - - Extended properties must be of type . Properties that are not of type String are not persisted when the is written as XML. - + to add custom information to a object. Add information with the Add method. Retrieve information with the Item method. + + Extended properties must be of type . Properties that are not of type String are not persisted when the is written as XML. + ]]> @@ -1011,14 +1011,14 @@ , if objects are nested; otherwise, . - objects to define hierarchical relationships, such as those specified in XML. For more information, see [Nesting DataRelations](/dotnet/framework/data/adonet/dataset-datatable-dataview/nesting-datarelations). - + objects to define hierarchical relationships, such as those specified in XML. For more information, see [Nesting DataRelations](/dotnet/framework/data/adonet/dataset-datatable-dataview/nesting-datarelations). + > [!NOTE] -> If the of the child table in the relation matches the of a column in the parent table in the relation, the property must be `false`. - +> If the of the child table in the relation matches the of a column in the parent table in the relation, the property must be `false`. + ]]> @@ -1114,13 +1114,13 @@ Gets an array of objects that are the parent columns of this . An array of objects that are the parent columns of this . - objects that function as parent columns for the relation. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ParentColumns/source.vb" id="Snippet1"::: - + objects that function as parent columns for the relation. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ParentColumns/source.vb" id="Snippet1"::: + ]]> @@ -1174,13 +1174,13 @@ Gets the that guarantees that values in the parent column of a are unique. A that makes sure that values in a parent column are unique. - of a object. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ParentKeyConstraint/source.vb" id="Snippet1"::: - + of a object. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ParentKeyConstraint/source.vb" id="Snippet1"::: + ]]> @@ -1227,13 +1227,13 @@ Gets the parent of this . A that is the parent table of this relation. - of a . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ParentTable/source.vb" id="Snippet1"::: - + of a . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ParentTable/source.vb" id="Snippet1"::: + ]]> @@ -1335,18 +1335,18 @@ Gets or sets the name used to retrieve a from the . The name of the a . - property to retrieve a from the . - - - -## Examples - The following example uses the property to retrieve a from a . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/RelationName/source.vb" id="Snippet1"::: - + property to retrieve a from the . + + + +## Examples + The following example uses the property to retrieve a from a . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/RelationName/source.vb" id="Snippet1"::: + ]]> @@ -1398,14 +1398,14 @@ Gets the , if one exists. The value of the property. - property to return the name of the object. - + property to return the name of the object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRelation.ToString Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ToString/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRelation/ToString/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/DataRelationCollection.xml b/xml/System.Data/DataRelationCollection.xml index e8ded0771fd..1d3016f11ca 100644 --- a/xml/System.Data/DataRelationCollection.xml +++ b/xml/System.Data/DataRelationCollection.xml @@ -82,9 +82,9 @@ ## Remarks A object enables navigation between related parent/child objects. - You create a object by defining it as a property of either the or the , instead of by directly using a constructor. (Use the property of the , or the property of the .) + You create a object by defining it as a property of either the or the , instead of by directly using a constructor. (Use the property of the , or the property of the .) - To access the collection, use the property of the object. + To access the collection, use the property of the object. As soon as the collection exists you can manage the objects it contains by using methods such as , , and . diff --git a/xml/System.Data/DataRow.xml b/xml/System.Data/DataRow.xml index 78ef5fbc9a1..174855c7c92 100644 --- a/xml/System.Data/DataRow.xml +++ b/xml/System.Data/DataRow.xml @@ -60,7 +60,7 @@ and objects are primary components of a . Use the object and its properties and methods to retrieve and evaluate; and insert, delete, and update the values in the . The represents the actual objects in the , and the contains the objects that describe the schema of the . Use the overloaded property to return or set the value of a . + The and objects are primary components of a . Use the object and its properties and methods to retrieve and evaluate; and insert, delete, and update the values in the . The represents the actual objects in the , and the contains the objects that describe the schema of the . Use the overloaded property to return or set the value of a . Use the and properties to determine the status of a particular row value, and the property to determine the state of the row relative to its parent . @@ -256,7 +256,7 @@ ## Remarks Use the method to put a into edit mode. In this mode, events are temporarily suspended, letting the user make changes to more than one row without triggering validation rules. For example, if you must make sure that the value of the column for a total amount is equal to the values for the debit and credit columns in a row, you can put each row into edit mode to suspend the validation of the row values until the user tries to commit the values. - The method is called implicitly when the user changes the value of a data-bound control; the method is called implicitly when you invoke the method for the object. While in this edit mode, the stores representations of the original and new proposed values. Therefore, as long as the method has not been called, you can retrieve either the original or proposed version by passing either `DataRowVersion.Original` or `DataRowVersion.Proposed` for the `version` parameter of the property. You can also cancel any edits at this point by invoking the method. + The method is called implicitly when the user changes the value of a data-bound control; the method is called implicitly when you invoke the method for the object. While in this edit mode, the stores representations of the original and new proposed values. Therefore, as long as the method has not been called, you can retrieve either the original or proposed version by passing either `DataRowVersion.Original` or `DataRowVersion.Proposed` for the `version` parameter of the property. You can also cancel any edits at this point by invoking the method. To see if the row contains an original or proposed value, call the method. @@ -401,7 +401,7 @@ ## Remarks Use and to set and return errors for individual columns. - Set the property to set an error that applies to the whole row. + Set the property to set an error that applies to the whole row. To determine whether any errors exist for the columns collection, use the method. Consequently, you can use the method to retrieve all the columns with errors. @@ -635,7 +635,7 @@ also contains a collection of objects that is returned by the property. + The also contains a collection of objects that is returned by the property. @@ -713,7 +713,7 @@ also contains a collection of objects that is returned by the property. + The also contains a collection of objects that is returned by the property. ]]> @@ -778,9 +778,9 @@ also contains a collection of objects that is returned by the property. + The also contains a collection of objects that is returned by the property. - Use the property to determine whether the that you want exists. + Use the property to determine whether the that you want exists. If is specified, the version that is used depends on the of the row on which `GetChildRows` is invoked. If the row on which `GetChildRows` is invoked has a `RowState` of `Modified`, `New`, or `Unchanged`, the version of the row is used for fetching related child rows with matching values in their Current versions. If the row on which `GetChildRows` is invoked has a `RowState` of `Deleted`, the version of the row is used for fetching related child rows with matching values in their original versions. @@ -864,9 +864,9 @@ also contains a collection of objects that is returned by the property. + The also contains a collection of objects that is returned by the property. - Use the property to determine whether the that you want exists. + Use the property to determine whether the that you want exists. If is specified, the version that is used depends on the of the row on which `GetChildRows` is invoked. If the row on which `GetChildRows` is invoked has a `RowState` of `Modified`, `New`, or `Unchanged`, the version of the row is used for fetching related child rows with matching values in their Current versions. If the row on which `GetChildRows` is invoked has a `RowState` of `Deleted`, the version of the row is used for fetching related child rows with matching values in their original versions. @@ -1152,7 +1152,7 @@ lets you reduce the number of objects that must be processed for errors by returning only those columns that have an error. Errors can be set to individual columns with the method. To further reduce the number of processing, examine the property of the class to determine whether a has errors before invoking . + The lets you reduce the number of objects that must be processed for errors by returning only those columns that have an error. Errors can be set to individual columns with the method. To further reduce the number of processing, examine the property of the class to determine whether a has errors before invoking . Use the method to clear all errors on the row. This includes the . @@ -1234,7 +1234,7 @@ ## Remarks In a , the collection of all parent objects for the data set is returned by the method. - The also contains a collection of objects, returned by the property. + The also contains a collection of objects, returned by the property. @@ -1311,7 +1311,7 @@ ## Remarks In a , the collection of all parent objects for the data set is returned by the method. - The also contains a collection of objects, returned by the property. + The also contains a collection of objects, returned by the property. @@ -1380,9 +1380,9 @@ ## Remarks In a , the collection of all parent objects for the data set is returned by the method. - The also contains a collection of objects, returned by the property. + The also contains a collection of objects, returned by the property. - Use the property to determine whether the that you want exists. + Use the property to determine whether the that you want exists. @@ -1463,9 +1463,9 @@ ## Remarks In a , the collection of all parent objects for the data set is returned by the method. - The also contains a collection of objects, returned by the property. + The also contains a collection of objects, returned by the property. - Use the property to determine whether the that you want exists. + Use the property to determine whether the that you want exists. @@ -1550,7 +1550,7 @@ ## Remarks In a , the collection of all parent objects for the data set is returned by the method. - The also contains a collection of objects, returned by the property. + The also contains a collection of objects, returned by the property. @@ -1629,7 +1629,7 @@ ## Remarks In a , the collection of all parent objects for the data set is returned by the method. - The also contains a collection of objects, returned by the property. + The also contains a collection of objects, returned by the property. ]]> @@ -1696,9 +1696,9 @@ ## Remarks In a , the collection of all parent objects for the data set is returned by the method. - The also contains a collection of objects, returned by the property. + The also contains a collection of objects, returned by the property. - Use the property to determine whether the that you want exists. + Use the property to determine whether the that you want exists. @@ -1780,9 +1780,9 @@ ## Remarks In a , the collection of all parent objects for the data set is returned by the method. - The also contains a collection of objects, returned by the property. + The also contains a collection of objects, returned by the property. - Use the property to determine whether the that you want exists. + Use the property to determine whether the that you want exists. ]]> @@ -1835,7 +1835,7 @@ object in the row contains an error, or if the property of the is not an empty string. + `HasErrors` returns `true` if any object in the row contains an error, or if the property of the is not an empty string. When validating data, you can set an error on any column in a row. Such a column, when displayed in the control, is marked with a red exclamation point to signal to the user that the column is in error. @@ -2235,7 +2235,7 @@ ## Examples - The following examples demonstrate the use of the property to get and set the value of a specific column index. The first example gets the value of the first column in any row that a user clicks in a control. The second sets a value passed as an argument to the method. + The following examples demonstrate the use of the property to get and set the value of a specific column index. The first example gets the value of the first column in any row that a user clicks in a control. The second sets a value passed as an argument to the method. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/Item/source2.vb" id="Snippet1"::: @@ -2301,7 +2301,7 @@ ## Examples - The following examples demonstrate the use of the property to get and set the value of a specific column index. The first example gets the value of the first column in any row that a user clicks in a control. + The following examples demonstrate the use of the property to get and set the value of a specific column index. The first example gets the value of the first column in any row that a user clicks in a control. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.this Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/Item/source.vb" id="Snippet1"::: @@ -2367,7 +2367,7 @@ ## Examples - The following examples demonstrate the use of the property to get and set the value of a specific column index. The first example gets the value of the first column in any row that a user clicks in a control. The second sets a value passed as an argument to the method. + The following examples demonstrate the use of the property to get and set the value of a specific column index. The first example gets the value of the first column in any row that a user clicks in a control. The second sets a value passed as an argument to the method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.this1 Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/Item/source1.vb" id="Snippet1"::: @@ -2516,7 +2516,7 @@ ## Examples - The following example gets the current value of a column through the property of the object. + The following example gets the current value of a column through the property of the object. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/Item/source3.vb" id="Snippet1"::: @@ -2657,7 +2657,7 @@ ## Examples - The following examples show how to get and set values using the property. + The following examples show how to get and set values using the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.ItemArray Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/ItemArray/source.vb" id="Snippet1"::: @@ -2778,7 +2778,7 @@ property to first determine whether a contains errors. + Uses the property to first determine whether a contains errors. @@ -2980,11 +2980,11 @@ ## Remarks To examine error descriptions, use the method. - To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. + To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. - If `null` or an empty string is passed in as the `error` parameter, the behaves as if no error was set and the property will return false. + If `null` or an empty string is passed in as the `error` parameter, the behaves as if no error was set and the property will return false. - To set a custom error description on the whole row, use the property. + To set a custom error description on the whole row, use the property. To determine whether any errors exist for the columns collection, use the method. @@ -3062,15 +3062,15 @@ To examine error descriptions, use the method. - To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. + To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. - If `null` or an empty string is passed in as the `error` parameter, the behaves as if no error was set and the property will return false. + If `null` or an empty string is passed in as the `error` parameter, the behaves as if no error was set and the property will return false. - To set a custom error description on the whole row, use the property. + To set a custom error description on the whole row, use the property. To clear all errors for the columns collection, use the method. - To set error text that applies to a whole row, set the property. + To set error text that applies to a whole row, set the property. @@ -3148,15 +3148,15 @@ property of the class. + The name of a column is set with the property of the class. To examine error descriptions, use the method. - To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. + To determine whether any errors exist for the columns collection, use the property. Consequently, you can use the method to retrieve all the columns with errors. - If `null` or an empty string is passed in as the `error` parameter, the behaves as if no error was set and the property will return false. + If `null` or an empty string is passed in as the `error` parameter, the behaves as if no error was set and the property will return false. - To set a custom error description on the whole row, use the property. + To set a custom error description on the whole row, use the property. To determine whether any errors exist for the columns collection, use the method. @@ -3448,7 +3448,7 @@ ## Examples - The following example uses the property to return a reference to the columns collection of the . + The following example uses the property to return a reference to the columns collection of the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRow.Table Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRow/Table/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataRowCollection.xml b/xml/System.Data/DataRowCollection.xml index 188f0371050..c6e83cf0c8e 100644 --- a/xml/System.Data/DataRowCollection.xml +++ b/xml/System.Data/DataRowCollection.xml @@ -60,23 +60,23 @@ Represents a collection of rows for a . - is a major component of the . While the defines the schema of the table, the contains the actual data for the table, where each in the represents a single row. - - You can call the and methods to insert and delete objects from the . You can also call the method to search for objects that contain specific values in primary key columns, and the method to search character-based data for single words or phrases. - - For other operations, such as sorting or filtering the , use methods on the 's associated . - - - -## Examples - The first example in this section prints the value of column 1 for every row in a . The second example adds a new row created by using the method to the . - + is a major component of the . While the defines the schema of the table, the contains the actual data for the table, where each in the represents a single row. + + You can call the and methods to insert and delete objects from the . You can also call the method to search for objects that contain specific values in primary key columns, and the method to search character-based data for single words or phrases. + + For other operations, such as sorting or filtering the , use methods on the 's associated . + + + +## Examples + The first example in this section prints the value of column 1 for every row in a . The second example adds a new row created by using the method to the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Add/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Add/source.vb" id="Snippet1"::: + ]]> This type is safe for multithreaded read operations. You must synchronize any write operations. @@ -138,21 +138,21 @@ The to add. Adds the specified to the object. - , you must use the method of the class. When you use the method, a new object is returned using the schema of parent . After you create the object and set the values for each of its columns, use the method to add the object to the collection. - - Generates an exception if the user generates an exception in the event. If an exception occurs, the row is not added to the table. - - - -## Examples - The following example uses the method to add a new to a object. - + , you must use the method of the class. When you use the method, a new object is returned using the schema of parent . After you create the object and set the values for each of its columns, use the method to add the object to the collection. + + Generates an exception if the user generates an exception in the event. If an exception occurs, the row is not added to the table. + + + +## Examples + The following example uses the method to add a new to a object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection.Add Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Overview/source.vb" id="Snippet1"::: + ]]> The row is null. @@ -227,21 +227,21 @@ Creates a row using specified values and adds it to the . The new row. - object has its set to True, null should be passed to get the default value for that column. - - Exceptions can also occur if you generate an exception during either a or event. If an exception occurs, the row is not added to the table. - - - -## Examples - The following example uses the method to create and add a new object to a . - + object has its set to True, null should be passed to get the default value for that column. + + Exceptions can also occur if you generate an exception during either a or event. If an exception occurs, the row is not added to the table. + + + +## Examples + The following example uses the method to create and add a new object to a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection.Add1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Add/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Add/source1.vb" id="Snippet1"::: + ]]> The array is larger than the number of columns in the table. @@ -356,20 +356,20 @@ if the collection contains a with the specified primary key value; otherwise, . - method, the object to which the object belongs to must have at least one column designated as a primary key column. See the property for more information about how to create a primary key column. - - As soon as you have determined that a row contains the specified value, you can use the method to return the specific object that has the value. - - - -## Examples - The following Visual Basic example uses the method to determine whether a object contains a specific value. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Contains/source.vb" id="Snippet1"::: - + method, the object to which the object belongs to must have at least one column designated as a primary key column. See the property for more information about how to create a primary key column. + + As soon as you have determined that a row contains the specified value, you can use the method to return the specific object that has the value. + + + +## Examples + The following Visual Basic example uses the method to determine whether a object contains a specific value. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Contains/source.vb" id="Snippet1"::: + ]]> The table does not have a primary key. @@ -430,20 +430,20 @@ if the contains a with the specified key values; otherwise, . - method with an array of values, the object to which the object belongs must have an array of columns designated as primary keys. See the property for more information about how to create an array of primary key columns. The number of array elements must correspond to the number of primary key columns in the . - - As soon as you have determined that a row contains the specified value, use the method to return the specific object that has the value. - - - -## Examples - The following Visual Basic example uses the method to find a particular row in a object. The example creates an array of values, one element for each primary key in the table, and then passes the array to the method to return a `true` or `false`. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Contains/source1.vb" id="Snippet1"::: - + method with an array of values, the object to which the object belongs must have an array of columns designated as primary keys. See the property for more information about how to create an array of primary key columns. The number of array elements must correspond to the number of primary key columns in the . + + As soon as you have determined that a row contains the specified value, use the method to return the specific object that has the value. + + + +## Examples + The following Visual Basic example uses the method to find a particular row in a object. The example creates an array of values, one element for each primary key in the table, and then passes the array to the method to return a `true` or `false`. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Contains/source1.vb" id="Snippet1"::: + ]]> The table does not have a primary key. @@ -650,19 +650,19 @@ Gets the row specified by the primary key value. A that contains the primary key value specified; otherwise a null value if the primary key value does not exist in the . - object to which the object belongs must have at least one column designated as a primary key column. See the property for more information about how to create a primary key column. - - - -## Examples - The following example uses the method to find the primary key value "2" in a collection of objects. The method returns the specific object letting you change its values, as needed. - + object to which the object belongs must have at least one column designated as a primary key column. See the property for more information about how to create a primary key column. + + + +## Examples + The following example uses the method to find the primary key value "2" in a collection of objects. The method returns the specific object letting you change its values, as needed. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection.Find Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Find/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Find/source.vb" id="Snippet1"::: + ]]> The table does not have a primary key. @@ -723,19 +723,19 @@ Gets the row that contains the specified primary key values. A object that contains the primary key values specified; otherwise a null value if the primary key value does not exist in the . - method, the object to which the object belongs must have at least one column designated as a primary key column. When two or more rows have the same primary key value, then the first row found is returned. This occurs when is set to false. See the property for more information about how to create a column, or an array of objects when the table has more than one primary key. - - - -## Examples - The following example uses the values of an array to find a specific row in a collection of objects. The method assumes that a exists with three primary key columns. After creating an array of the values, the code uses the method with the array to get the particular object that you want. - + method, the object to which the object belongs must have at least one column designated as a primary key column. When two or more rows have the same primary key value, then the first row found is returned. This occurs when is set to false. See the property for more information about how to create a column, or an array of objects when the table has more than one primary key. + + + +## Examples + The following example uses the values of an array to find a specific row in a collection of objects. The method assumes that a exists with three primary key columns. After creating an array of the values, the code uses the method with the array to get the particular object that you want. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection.Find1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Find/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Find/source1.vb" id="Snippet1"::: + ]]> No row corresponds to that index value. @@ -878,13 +878,13 @@ The (zero-based) location in the collection where you want to add the . Inserts a new row into the collection at the specified location. - is reflected by the order of rows in the only. If more than one row is returned in a array, the inserted row may not be returned in the location specified by . For example, the property returns the row in the specified insert position. and may not. When you write the contents of the as XML, for example, , the rows are written according to the order specified by the . - - If the value specified for the `pos` parameter is greater than the number of rows in the collection, the new row is added to the end. - + is reflected by the order of rows in the only. If more than one row is returned in a array, the inserted row may not be returned in the location specified by . For example, the property returns the row in the specified insert position. and may not. When you write the contents of the as XML, for example, , the rows are written according to the order specified by the . + + If the value specified for the `pos` parameter is greater than the number of rows in the collection, the new row is added to the end. + ]]> The is less than 0. @@ -934,19 +934,19 @@ Gets the row at the specified index. The specified . - method to determine whether a specific value exists in the key column of a row. - - - -## Examples - The following example prints the value of column 1 of each row in a . - + method to determine whether a specific value exists in the key column of a row. + + + +## Examples + The following example prints the value of column 1 of each row in a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowCollection.this Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Item/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Item/source.vb" id="Snippet1"::: + ]]> The index value is greater than the number of items in the collection. @@ -1023,22 +1023,22 @@ The to remove. Removes the specified from the collection. - method of the class to just mark a row for removal. Calling `Remove` is the same as calling and then calling . - - should not be called in a foreach loop while iterating through a object. modifies the state of the collection. - - You can also use the method to remove all members of the collection at one time. - - - -## Examples - The following example uses the method to delete a found row in a object. The example first uses the method to determine whether the rows collection contains a row. If it does, the method is used to find the specific row, and the method is then used to remove the row. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Remove/source.vb" id="Snippet1"::: - + method of the class to just mark a row for removal. Calling `Remove` is the same as calling and then calling . + + should not be called in a foreach loop while iterating through a object. modifies the state of the collection. + + You can also use the method to remove all members of the collection at one time. + + + +## Examples + The following example uses the method to delete a found row in a object. The example first uses the method to determine whether the rows collection contains a row. If it does, the method is used to find the specific row, and the method is then used to remove the row. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/Remove/source.vb" id="Snippet1"::: + ]]> @@ -1090,20 +1090,20 @@ The index of the row to remove. Removes the row at the specified index from the collection. - method of the class to just mark a row for removal. Calling `RemoveAt` is the same as calling and then calling . - - You can use the method to remove all members of the collection at one time. - - - -## Examples - The following example removes the last row in a by calling the method. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/RemoveAt/source.vb" id="Snippet1"::: - + method of the class to just mark a row for removal. Calling `RemoveAt` is the same as calling and then calling . + + You can use the method to remove all members of the collection at one time. + + + +## Examples + The following example removes the last row in a by calling the method. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowCollection/RemoveAt/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/DataRowComparer.xml b/xml/System.Data/DataRowComparer.xml index d99d0431d96..215e93f0ffb 100644 --- a/xml/System.Data/DataRowComparer.xml +++ b/xml/System.Data/DataRowComparer.xml @@ -57,15 +57,15 @@ Returns a singleton instance of the class. - class is used to compare the values of the objects and does not compare the object references. - - This class cannot be directly instantiated. Instead, the property must be used to return a singleton instance of the class. - - This class is stateless. - + class is used to compare the values of the objects and does not compare the object references. + + This class cannot be directly instantiated. Instead, the property must be used to return a singleton instance of the class. + + This class is stateless. + ]]> Comparing DataRows @@ -108,11 +108,11 @@ Gets a singleton instance of . This property is read-only. An instance of a . - Comparing DataRows diff --git a/xml/System.Data/DataRowComparer`1.xml b/xml/System.Data/DataRowComparer`1.xml index 41d23dda56a..24de3891a22 100644 --- a/xml/System.Data/DataRowComparer`1.xml +++ b/xml/System.Data/DataRowComparer`1.xml @@ -75,17 +75,17 @@ The type of objects to be compared, typically . Compares two objects for equivalence by using value-based comparison. - interface and uses value-based semantics to compare objects. This class is required because the default implementations of some set-based operations (such as , , , and ) use reference-based semantics to compare object references, instead of comparing the object values. The class is used to compare the values of the objects and does not compare the object references. - - This class cannot be directly instantiated. Instead, the property must be used to return a singleton instance of the class. - - This class is stateless. - - This class is sealed and cannot be derived from. - + interface and uses value-based semantics to compare objects. This class is required because the default implementations of some set-based operations (such as , , , and ) use reference-based semantics to compare object references, instead of comparing the object values. The class is used to compare the values of the objects and does not compare the object references. + + This class cannot be directly instantiated. Instead, the property must be used to return a singleton instance of the class. + + This class is stateless. + + This class is sealed and cannot be derived from. + ]]> Comparing DataRows @@ -134,11 +134,11 @@ Gets a singleton instance of . This property is read-only. An instance of a . - Comparing DataRows @@ -192,15 +192,15 @@ if the two objects have ordered sets of column values that are equal; otherwise, . - objects is not checked. If both objects have exactly the same ordered set of column values, they are considered equal. - - Only the current values of the objects are checked. The state of the objects is not checked. - - The method is the value-based comparison implementation of the method. - + objects is not checked. If both objects have exactly the same ordered set of column values, they are considered equal. + + Only the current values of the objects are checked. The state of the objects is not checked. + + The method is the value-based comparison implementation of the method. + ]]> One or both of the source objects are . @@ -251,11 +251,11 @@ Returns a hash code for the specified object. An value representing the hash code of the row. - method is the value-based comparison implementation of the method. - + method is the value-based comparison implementation of the method. + ]]> The source objects does not belong to a . diff --git a/xml/System.Data/DataRowState.xml b/xml/System.Data/DataRowState.xml index 0481b3ff669..750a78dde12 100644 --- a/xml/System.Data/DataRowState.xml +++ b/xml/System.Data/DataRowState.xml @@ -51,19 +51,19 @@ Gets the state of a object. - enumeration is returned by the property of the class. - - - -## Examples - The following example first creates a new with one column, then creates a single . As the is created, added, modified, and deleted, its is printed. - + enumeration is returned by the property of the class. + + + +## Examples + The following example first creates a new with one column, then creates a single . As the is created, added, modified, and deleted, its is printed. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowState Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowState/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowState/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/DataRowView.xml b/xml/System.Data/DataRowView.xml index ba58814ce6a..66e92a9c753 100644 --- a/xml/System.Data/DataRowView.xml +++ b/xml/System.Data/DataRowView.xml @@ -83,7 +83,7 @@ ## Examples - The following example uses the property to determine the state of a row in the . (See for another example using .) + The following example uses the property to determine the state of a row in the . (See for another example using .) :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataRowView.RowVersion1/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowView/Overview/source.vb" id="Snippet1"::: @@ -1027,7 +1027,7 @@ The doesn't allow edits and property to print the value of the third column in each modified row of a . + The following example uses the property to print the value of the third column in each modified row of a . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataRowView.Row Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowView/Row/source.vb" id="Snippet1"::: @@ -1081,12 +1081,12 @@ The doesn't allow edits and property specifies both and settings. For more information, see , , and . + The property specifies both and settings. For more information, see , , and . ## Examples - The following example uses the property to display the . + The following example uses the property to display the . :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataRowView.RowVersion1/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataRowView/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Data/DataSet.xml b/xml/System.Data/DataSet.xml index 71d5a43a435..f7b565d3252 100644 --- a/xml/System.Data/DataSet.xml +++ b/xml/System.Data/DataSet.xml @@ -448,7 +448,7 @@ The following example consists of several methods that, combined, create and fil ## Remarks Both the 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. + 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. @@ -577,14 +577,14 @@ The following example consists of several methods that, combined, create and fil property affects how sorting, searching, and filtering operations are performed on each object contained in a when using the method. + The 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. + 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. + The following example toggles the property. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/CaseSensitive/source.vb" id="Snippet1"::: @@ -1046,9 +1046,9 @@ If these classes have been subclassed, the copy will also be of the same subclas returned by the property allows you to create custom settings for each in the . + The 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. + When you obtain a from a , the sort order, filtering, and are configured according to the settings in the property. @@ -1296,12 +1296,12 @@ If these classes have been subclassed, the copy will also be of the same subclas level ( property). For more information about creating constraints, see [DataTable Constraints](/dotnet/framework/data/adonet/dataset-datatable-dataview/datatable-constraints). + Constraints are set at the 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. + 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/System.Data/DataSet/EnforceConstraints/source.vb" id="Snippet1"::: @@ -1365,14 +1365,14 @@ If these classes have been subclassed, the copy will also be of the same subclas property enables you to store custom information with the `DataSet`. For example, you might store a time when the data should be refreshed. + The 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. + 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/System.Data/DataColumn/ExtendedProperties/source.vb" id="Snippet1"::: @@ -2315,7 +2315,7 @@ class Program { property of the `DataSet` before invoking the method. + Examine the property of the `DataSet` before invoking the method. @@ -2384,12 +2384,12 @@ class Program { 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. + Each 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. + 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/System.Data/DataSet/HasErrors/source.vb" id="Snippet1"::: @@ -3183,7 +3183,7 @@ class Program { 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 `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. @@ -3251,7 +3251,7 @@ class Program { property specifies the locale for which sorting applies. + The 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. @@ -3339,7 +3339,7 @@ class Program { 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`. + 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`. ]]> @@ -3404,7 +3404,7 @@ class Program { 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`. + 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`. @@ -3482,7 +3482,7 @@ class Program { 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`. + 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`. @@ -3559,7 +3559,7 @@ class Program { 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`. + 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`. @@ -3641,7 +3641,7 @@ class Program { 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`. + 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`. ]]> @@ -3713,7 +3713,7 @@ class Program { 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`. + 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`. @@ -3792,7 +3792,7 @@ class Program { 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`. + 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`. @@ -3929,7 +3929,7 @@ class Program { property is used when reading and writing an XML document into the using the , , , or methods. + 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. @@ -4178,7 +4178,7 @@ class Program { property is used throughout an XML document to identify elements which belong to the namespace of the object (as set by the property). + The property is used throughout an XML document to identify elements which belong to the namespace of the object (as set by the property). @@ -5554,7 +5554,7 @@ class Program { property. + The following example prints the column name of all child tables through the property. :::code language="vb" source="~/snippets/visualbasic/System.Data/DataSet/Relations/source.vb" id="Snippet1"::: @@ -5707,7 +5707,7 @@ class Program { 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. + 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 . diff --git a/xml/System.Data/DataSetDateTime.xml b/xml/System.Data/DataSetDateTime.xml index 0f4518c74cc..5b9918af127 100644 --- a/xml/System.Data/DataSetDateTime.xml +++ b/xml/System.Data/DataSetDateTime.xml @@ -44,13 +44,13 @@ Describes the serialization format for columns in a . - cannot be set on non- columns. Setting the property with the default value UnspecifiedLocal on non- columns is permitted. Modifying the column data type from to any other type resets the to the default value UnspecifiedLocal. - - Checking schema for merging, Relations, and ForeignKeyConstraints can be performed between columns with matching properties. Otherwise the columns should be considered as non-matching on schema. The only exception is between Unspecified and UnspecifiedLocal. It is permitted to have a relation or a `ForeignKeyConstraint` between two `DateTime` columns with one in `Unspecified` and other in `UnspecifiedLocal` . - + cannot be set on non- columns. Setting the property with the default value UnspecifiedLocal on non- columns is permitted. Modifying the column data type from to any other type resets the to the default value UnspecifiedLocal. + + Checking schema for merging, Relations, and ForeignKeyConstraints can be performed between columns with matching properties. Otherwise the columns should be considered as non-matching on schema. The only exception is between Unspecified and UnspecifiedLocal. It is permitted to have a relation or a `ForeignKeyConstraint` between two `DateTime` columns with one in `Unspecified` and other in `UnspecifiedLocal` . + ]]> diff --git a/xml/System.Data/DataTable.xml b/xml/System.Data/DataTable.xml index 1197c66b653..4b89630a607 100644 --- a/xml/System.Data/DataTable.xml +++ b/xml/System.Data/DataTable.xml @@ -193,7 +193,7 @@ The following example creates two objects and one < |--------------|-------------------| |**CaseSensitive**|Same as the parent , if it belongs to one. Otherwise, `false`.| |**DisplayExpression**|Empty string ("")| -|**Locale**|Same as the parent object's (returned by the property); if no parent exists, the default is the current system .| +|**Locale**|Same as the parent object's (returned by the property); if no parent exists, the default is the current system .| |**MinimumCapacity**|50 rows.| You can change the value for any of these properties through a separate call to the property. @@ -596,12 +596,12 @@ The following example creates two objects and one < property affects string comparisons in sorting, searching, and filtering. + The property affects string comparisons in sorting, searching, and filtering. ## Examples - The following example calls the method twice on a . The first time, the property is set to `false`, the second, to `true`. + The following example calls the method twice on a . The first time, the property is set to `false`, the second, to `true`. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.CaseSensitive Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/CaseSensitive/source.vb" id="Snippet1"::: @@ -672,7 +672,7 @@ The following example creates two objects and one < A defines the relationship between two tables. Typically, two tables are linked through a single field that contains the same data. For example, a table that contains address data may have a single field containing codes that represent countries/regions. A second table that contains country/region data will have a single field that contains the code that identifies the country/region, and it is this code that is inserted into the corresponding field in the first table. A , then, contains at least four pieces of information: (1) the name of the first table, (2) the column name in the first table, (3) the name of the second table, and (4) the column name in the second table. ## Examples - The following example uses the property to return each child in a . Each relation is then used as an argument in the method of the to return an array of rows. The value of each column in the row is then printed. + The following example uses the property to return each child in a . Each relation is then used as an argument in the method of the to return an array of rows. The value of each column in the row is then printed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.ChildRelations Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/ChildRelations/source.vb" id="Snippet1"::: @@ -1500,7 +1500,7 @@ class Program { ## Examples - The following example prints each value of each row in a table using the property. + The following example prints each value of each row in a table using the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.Columns Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/Columns/source.vb" id="Snippet1"::: @@ -1580,7 +1580,7 @@ class Program { `Sum (Quantity * UnitPrice)` - If you must perform an operation on two or more columns, you should create a , set its property to an appropriate expression, and use an aggregate expression on the resulting column. In that case, given a with the name "total", and the property set to this: + If you must perform an operation on two or more columns, you should create a , set its property to an appropriate expression, and use an aggregate expression on the resulting column. In that case, given a with the name "total", and the property set to this: `"Quantity * UnitPrice"` @@ -1592,7 +1592,7 @@ class Program { `colDate > 1/1/99 AND colDate < 17/1/99` - For rules on creating expressions for both parameters, see the property. + For rules on creating expressions for both parameters, see the property. @@ -1919,7 +1919,7 @@ class Program { ## Examples - The following example returns the parent of a given table through the property. + The following example returns the parent of a given table through the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.DataSet Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/DataSet/source.vb" id="Snippet1"::: @@ -1982,12 +1982,12 @@ class Program { property returns a you can use to sort, filter, and search a . + The property returns a you can use to sort, filter, and search a . ## Examples - The following example sets a property of the object's through the property. The example also shows the binding of a control to a named "Suppliers" that includes a column named "CompanyName." + The following example sets a property of the object's through the property. The example also shows the binding of a control to a named "Suppliers" that includes a column named "CompanyName." :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.DefaultView Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/DefaultView/source.vb" id="Snippet1"::: @@ -2220,7 +2220,7 @@ class Program { ## Examples - The following example adds a timestamp value to the through the property. + The following example adds a timestamp value to the through the property. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.ExtendedProperties Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/ExtendedProperties/source.vb" id="Snippet1"::: @@ -2733,16 +2733,16 @@ class Program { , you can mark each change with an error if the change causes some validation failure. You can mark an entire with an error message using the property. You can also set errors on each column of the row with the method. + As users work on a set of data contained in a , you can mark each change with an error if the change causes some validation failure. You can mark an entire with an error message using the property. You can also set errors on each column of the row with the method. - Before updating a data source with a , it's recommended that you first invoke the method on the target . The method results in a that contains only the changes made to the original. Before sending the to the data source for updating, check the property of each table to see if any errors have been attached to the rows or columns in the rows. + Before updating a data source with a , it's recommended that you first invoke the method on the target . The method results in a that contains only the changes made to the original. Before sending the to the data source for updating, check the property of each table to see if any errors have been attached to the rows or columns in the rows. After reconciling each error, clear the errors with the method of the `DataRow`. ## Examples - The following example uses the property to check if a table contains errors. + The following example uses the property to check if a table contains errors. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.HasErrors Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/HasErrors/source.vb" id="Snippet1"::: @@ -3050,7 +3050,7 @@ class Program { This version of the `Load` method attempts to preserve the current values in each row, leaving the original value intact. (If you want finer control over the behavior of incoming data, see .) If the existing row and the incoming row contain corresponding primary key values, the row is processed using its current row state value, otherwise it's treated as a new row. - In terms of event operations, the event occurs before each row is changed, and the event occurs after each row has been changed. In each case, the property of the instance passed to the event handler contains information about the particular action associated with the event. This action value depends on the state of the row before the load operation. In each case, both events occur, and the action is the same for each. The action may be applied to either the current or original version of each row, or both, depending on the current row state. + In terms of event operations, the event occurs before each row is changed, and the event occurs after each row has been changed. In each case, the property of the instance passed to the event handler contains information about the particular action associated with the event. This action value depends on the state of the row before the load operation. In each case, both events occur, and the action is the same for each. The action may be applied to either the current or original version of each row, or both, depending on the current row state. The following table displays behavior for the `Load` method. The final row (labeled "(Not present)") describes the behavior for incoming rows that don't match any existing row. Each cell in this table describes the current and original value for a field within a row, along with the for the value after the `Load` method has completed. In this case, the method doesn't allow you to indicate the load option, and uses the default, `PreserveChanges`. @@ -3150,7 +3150,7 @@ class Program { If the existing row and the incoming row contain corresponding primary key values, the row is processed using its current row state value, otherwise it's treated as a new row. - In terms of event operations, the event occurs before each row is changed, and the event occurs after each row has been changed. In each case, the property of the instance passed to the event handler contains information about the particular action associated with the event. This action value varies, depending on the state of the row before the load operation. In each case, both events occur, and the action is the same for each. The action may be applied to either the current or original version of each row, or both, depending on the current row state. + In terms of event operations, the event occurs before each row is changed, and the event occurs after each row has been changed. In each case, the property of the instance passed to the event handler contains information about the particular action associated with the event. This action value varies, depending on the state of the row before the load operation. In each case, both events occur, and the action is the same for each. The action may be applied to either the current or original version of each row, or both, depending on the current row state. The following table displays behavior for the Load method when called with each of the `LoadOption` values, and also shows how the values interact with the row state for the row being loaded. The final row (labeled "(Not present)") describes the behavior for incoming rows that don't match any existing row. Each cell in this table describes the current and original value for a field within a row, along with the for the value after the `Load` method has completed. @@ -3266,7 +3266,7 @@ Not present)|Current = \

Original = \
If the existing row and the incoming row contain corresponding primary key values, the row is processed using its current row state value, otherwise it's treated as a new row. - In terms of event operations, the event occurs before each row is changed, and the event occurs after each row has been changed. In each case, the property of the instance passed to the event handler contains information about the particular action associated with the event. This action value varies, depending on the state of the row before the load operation. In each case, both events occur, and the action is the same for each. The action may be applied to either the current or original version of each row, or both, depending on the current row state. + In terms of event operations, the event occurs before each row is changed, and the event occurs after each row has been changed. In each case, the property of the instance passed to the event handler contains information about the particular action associated with the event. This action value varies, depending on the state of the row before the load operation. In each case, both events occur, and the action is the same for each. The action may be applied to either the current or original version of each row, or both, depending on the current row state. The following table displays behavior for the Load method when called with each of the `LoadOption` values, and also shows how the values interact with the row state for the row being loaded. The final row (labeled "(Not present)") describes the behavior for incoming rows that don't match any existing row. Each cell in this table describes the current and original value for a field within a row, along with the for the value after the `Load` method has completed. @@ -3288,7 +3288,7 @@ Not present)|Current = \

Original = \
|`PreserveChanges`|Original version, if it exists, otherwise Current version| |`Upsert`|Current version, if it exists, otherwise Original version| - 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 `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. @@ -3373,7 +3373,7 @@ Not present)|Current = \

Original = \
## Remarks The method takes an array of values and finds the matching value(s) in the primary key column(s). - If a column has a default value, pass a null value in the array to set the default value for that column. Similarly, if a column has its property set to true, pass a null value in the array to set the automatically generated value for the row. + If a column has a default value, pass a null value in the array to set the default value for that column. Similarly, if a column has its property set to true, pass a null value in the array to set the automatically generated value for the row. If the `fAcceptChanges` parameter is `true` or not specified, the new data is added and then is called to accept all changes in the ; if the argument is `false`, newly added rows are marked as insertions, and changes to existing rows are marked as modifications. @@ -3457,7 +3457,7 @@ Not present)|Current = \

Original = \
## Remarks The method takes an array of values and finds the matching value(s) in the primary key column(s). - If a column has a default value, pass a null value in the array to set the default value for that column. Similarly, if a column has its property set to true, pass a null value in the array to set the automatically generated value for the row. + If a column has a default value, pass a null value in the array to set the default value for that column. Similarly, if a column has its property set to true, pass a null value in the array to set the automatically generated value for the row. The value of the `loadOption` parameter is used to determine how the values in the array are applied to an existing row. For example, if `loadOption` is set to `OverwriteChanges`, the `Original` and `Current` values of each column are replaced with the values in the incoming row and the `RowState` property is set to `Unchanged`. @@ -3958,7 +3958,7 @@ Not present)|Current = \

Original = \
method to create new objects with the same schema as the . After creating a , you can add it to the , through the object's property. When you use to create new rows, the rows must be added to or deleted from the data table before you call . + You must use the method to create new objects with the same schema as the . After creating a , you can add it to the , through the object's property. When you use to create new rows, the rows must be added to or deleted from the data table before you call . @@ -4761,7 +4761,7 @@ Not present)|Current = \

Original = \
property to return each parent in a . Each relation is then used as an argument in the method of the to return an array of rows. The value of each column in the row is then printed. + The following example uses the property to return each parent in a . Each relation is then used as an argument in the method of the to return an array of rows. The value of each column in the row is then printed. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.ParentRelations Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/ParentRelations/source.vb" id="Snippet1"::: @@ -4893,7 +4893,7 @@ Not present)|Current = \

Original = \
property consists of an array of objects. + The primary key of a table must be unique to identify the record in the table. It's also possible to have a table with a primary key made up of two or more columns. This occurs when a single column can't contain enough unique values. For example, a two column primary key might consist of an "OrderNumber" and "ProductID" column. Because primary keys can be made up of more than one column, the property consists of an array of objects. ## Examples The first example shows how to return the primary key columns for a displayed in a `DataGrid`. The second example demonstrates how to set the primary key columns for a . @@ -6181,7 +6181,7 @@ public class A { ## Examples - The following shows two examples of returning and setting rows. The first example uses the property and prints the value of each column for every row. The second example uses the object's method to create a new object with the schema of the . After setting the row values, the row is added to the through the `Add` method. + The following shows two examples of returning and setting rows. The first example uses the property and prints the value of each column for every row. The second example uses the object's method to create a new object with the schema of the . After setting the row values, the row is added to the through the `Add` method. :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTable.Rows Example/CS/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTable/Rows/source.vb" id="Snippet1"::: @@ -6328,7 +6328,7 @@ public class A { class's property value for creating filters. + To create the `filterExpression` argument, use the same rules that apply to the class's property value for creating filters. To ensure the proper sort order, specify sort criteria with or . @@ -6409,7 +6409,7 @@ To ensure the proper sort order, specify sort criteria with class's property value. The `Sort` argument also uses the same rules for creating class's strings. + To form the `filterExpression` argument, use the same rules for creating the class's property value. The `Sort` argument also uses the same rules for creating class's strings. If the column on the filter contains a null value, it will not be part of the result. @@ -6490,7 +6490,7 @@ To ensure the proper sort order, specify sort criteria with class's property value. The `Sort` argument also uses the same rules for creating class's strings. + To form the `filterExpression` argument, use the same rules for creating the class's property value. The `Sort` argument also uses the same rules for creating class's strings. If the column on the filter contains a null value, it will not be part of the result. @@ -7040,7 +7040,7 @@ To ensure the proper sort order, specify sort criteria with is used to return this table from the parent object's (returned by the property). + The is used to return this table from the parent object's (returned by the property). diff --git a/xml/System.Data/DataTableCollection.xml b/xml/System.Data/DataTableCollection.xml index 0953fe6730a..dc8a39461b3 100644 --- a/xml/System.Data/DataTableCollection.xml +++ b/xml/System.Data/DataTableCollection.xml @@ -80,25 +80,25 @@ Represents the collection of tables for the . - contains all the objects for a particular . To access the of a , use the property. - - The uses methods such as , , and to manage the items in the collection. - - Use the method to determine whether a particular table (specified by either index or name) is in the collection. - - To navigate from one table to another, use the or property of the to access its collection of objects. You can also use the property to navigate through the parent/child relationships of the `DataTables` in a particular collection. - - - -## Examples - The first procedure in this example retrieves the of a and prints the value of each column, in each row, of each table. The second procedure creates a new with two columns, and adds it to the . - + contains all the objects for a particular . To access the of a , use the property. + + The uses methods such as , , and to manage the items in the collection. + + Use the method to determine whether a particular table (specified by either index or name) is in the collection. + + To navigate from one table to another, use the or property of the to access its collection of objects. You can also use the property to navigate through the parent/child relationships of the `DataTables` in a particular collection. + + + +## Examples + The first procedure in this example retrieves the of a and prints the value of each column, in each row, of each table. The second procedure creates a new with two columns, and adds it to the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Overview/source.vb" id="Snippet1"::: + ]]> This type is safe for multithreaded read operations. You must synchronize any write operations. @@ -164,21 +164,21 @@ Creates a new object by using a default name and adds it to the collection. The newly created . - event occurs when a table is successfully added to the collection. - - - -## Examples - The following example adds three new objects to the using the method without arguments. - + event occurs when a table is successfully added to the collection. + + + +## Examples + The following example adds three new objects to the using the method without arguments. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Add2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Add/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Add/source1.vb" id="Snippet1"::: + ]]> @@ -234,18 +234,18 @@ The object to add. Adds the specified to the collection. - event occurs when a table is successfully added to the collection. - - - -## Examples - The following example creates a and adds it to the of a . - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Add Example/CS/source.cs" id="Snippet1"::: - + event occurs when a table is successfully added to the collection. + + + +## Examples + The following example creates a and adds it to the of a . + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Add Example/CS/source.cs" id="Snippet1"::: + ]]> The value specified for the table is . @@ -313,21 +313,21 @@ Creates a object by using the specified name and adds it to the collection. The newly created . - event occurs if the table is successfully added to the collection. - - - -## Examples - The following example adds a with the given name to the . - + event occurs if the table is successfully added to the collection. + + + +## Examples + The following example adds a with the given name to the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Add1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Add/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Add/source.vb" id="Snippet1"::: + ]]> A table in the collection has the same name. (The comparison is not case sensitive.) @@ -388,21 +388,21 @@ Creates a object by using the specified name and adds it to the collection. The newly created . - event occurs if the table is successfully added to the collection. - - - -## Examples - The following example adds a with the given name to the . - + event occurs if the table is successfully added to the collection. + + + +## Examples + The following example adds a with the given name to the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Add1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Add/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Add/source.vb" id="Snippet1"::: + ]]> A table in the collection has the same name. (The comparison is not case sensitive.) @@ -455,14 +455,14 @@ The array of objects to add to the collection. Copies the elements of the specified array to the end of the collection. - objects and adds them to the of a . - + objects and adds them to the of a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.AddRange Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/AddRange/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/AddRange/source.vb" id="Snippet1"::: + ]]> @@ -513,14 +513,14 @@ if the table can be removed; otherwise . - to test whether each table can be removed from a . If so, the method is called to remove the table. - + to test whether each table can be removed from a . If so, the method is called to remove the table. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.CanRemove Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/CanRemove/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/CanRemove/source.vb" id="Snippet1"::: + ]]> @@ -568,19 +568,19 @@ Clears the collection of all objects. - method. - - - -## Examples - The following example gets the of a , and then clears the collection of all tables. - + method. + + + +## Examples + The following example gets the of a , and then clears the collection of all tables. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Clear Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Clear/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Clear/source.vb" id="Snippet1"::: + ]]> @@ -625,19 +625,19 @@ Occurs after the is changed because of objects being added or removed. - event. - + event. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.CollectionChanged Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/CollectionChanged/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/CollectionChanged/source.vb" id="Snippet1"::: + ]]> @@ -682,19 +682,19 @@ Occurs while the is changing because of objects being added or removed. - event. - + event. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.CollectionChanging Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/CollectionChanging/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/CollectionChanging/source.vb" id="Snippet1"::: + ]]> @@ -755,24 +755,24 @@ if the specified table exists; otherwise . - object by using the property. If you add a to the collection with the method, passing no arguments, the table is given a default name, based on the order in which the table was added ("Table1", "Table2", and so on). - - To get the index of a , use the method. - + object by using the property. If you add a to the collection with the method, passing no arguments, the table is given a default name, based on the order in which the table was added ("Table1", "Table2", and so on). + + To get the index of a , use the method. + > [!NOTE] -> Returns `false` when two or more tables have the same name but different namespaces. The call does not succeed if there is any ambiguity when matching a table name to exactly one table. - - - -## Examples - The following example tests whether a table with the name "Suppliers" exists in the . - +> Returns `false` when two or more tables have the same name but different namespaces. The call does not succeed if there is any ambiguity when matching a table name to exactly one table. + + + +## Examples + The following example tests whether a table with the name "Suppliers" exists in the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Contains Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Contains/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Contains/source.vb" id="Snippet1"::: + ]]> @@ -827,24 +827,24 @@ if the specified table exists; otherwise . - object by using the property. If you add a to the collection with the method, passing no arguments, the table is given a default name, based on the order in which the table was added ("Table1", "Table2", and so on). - + object by using the property. If you add a to the collection with the method, passing no arguments, the table is given a default name, based on the order in which the table was added ("Table1", "Table2", and so on). + > [!NOTE] -> Returns `false` when two or more tables have the same name but different namespaces. The call does not succeed if there is any ambiguity when matching a table name to exactly one table. - - To get the index of a , use the method. - - - -## Examples - The following example tests whether a table with the name "Suppliers" exists in the . - +> Returns `false` when two or more tables have the same name but different namespaces. The call does not succeed if there is any ambiguity when matching a table name to exactly one table. + + To get the index of a , use the method. + + + +## Examples + The following example tests whether a table with the name "Suppliers" exists in the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Contains Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Contains/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Contains/source.vb" id="Snippet1"::: + ]]> @@ -897,11 +897,11 @@ The destination index to start copying into. Copies all the elements of the current to a one-dimensional , starting at the specified destination array index. -
@@ -966,21 +966,21 @@ Gets the index of the specified object. The zero-based index of the table, or -1 if the table is not found in the collection. - method to determine the exact index of a given table. - - Before calling , you can test for the existence of a table (specified by either index or name) by using the method. - - - -## Examples - The following example returns the index of each table in the . - + method to determine the exact index of a given table. + + Before calling , you can test for the existence of a table (specified by either index or name) by using the method. + + + +## Examples + The following example returns the index of each table in the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.IndexOf Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/IndexOf/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/IndexOf/source.vb" id="Snippet1"::: + ]]> @@ -1038,20 +1038,20 @@ Gets the index in the collection of the object with the specified name. The zero-based index of the with the specified name, or -1 if the table does not exist in the collection. - property. +You specify the name of the `DataTable` object by using the property. This method returns -1 when two or more tables have the same name but different namespaces. The call does not succeed if there is any ambiguity when matching a table name to exactly one table. - -## Examples - The following example returns the index of a named table in the . - + +## Examples + The following example returns the index of a named table in the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.IndexOf1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/IndexOf/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/IndexOf/source1.vb" id="Snippet1"::: + ]]> @@ -1104,19 +1104,19 @@ This method returns -1 when two or more tables have the same name but different Gets the index in the collection of the specified object. The zero-based index of the with the specified name, or -1 if the table does not exist in the collection. - object by using the property. - - - -## Examples - The following example returns the index of a named table in the . - + object by using the property. + + + +## Examples + The following example returns the index of a named table in the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.IndexOf1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/IndexOf/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/IndexOf/source1.vb" id="Snippet1"::: + ]]> @@ -1184,21 +1184,21 @@ This method returns -1 when two or more tables have the same name but different Gets the object at the specified index. A with the specified index; otherwise if the does not exist. - method to determine whether a table with a specific index exists. - - If you have the name of a table, but not its index, use the method to return the index. - - - -## Examples - The following example retrieves a by its index. - + method to determine whether a table with a specific index exists. + + If you have the name of a table, but not its index, use the method to return the index. + + + +## Examples + The following example retrieves a by its index. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.this Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Item/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Item/source.vb" id="Snippet1"::: + ]]> The index value is greater than the number of items in the collection. @@ -1252,21 +1252,21 @@ This method returns -1 when two or more tables have the same name but different Gets the object with the specified name. A with the specified name; otherwise if the does not exist. - name exists that matches the case of the search string, it is returned. Otherwise a case-insensitive search is performed, and if a name is found that matches this search, it is returned. - - Use the method to determine whether a table with a specific name or index exists. - - - -## Examples - The following example retrieves a single table by name from the . - + name exists that matches the case of the search string, it is returned. Otherwise a case-insensitive search is performed, and if a name is found that matches this search, it is returned. + + Use the method to determine whether a table with a specific name or index exists. + + + +## Examples + The following example retrieves a single table by name from the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.this1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Item/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Item/source1.vb" id="Snippet1"::: + ]]>
@@ -1487,28 +1487,28 @@ This method returns -1 when two or more tables have the same name but different The to remove. Removes the specified object from the collection. - event occurs when a table is successfully removed. - - To determine whether a given table exists and can be removed before invoking , use the and the methods. - - - -## Examples - The following example uses the method to test whether each table can be removed from a . If so, the method is called to remove the table. - + event occurs when a table is successfully removed. + + To determine whether a given table exists and can be removed before invoking , use the and the methods. + + + +## Examples + The following example uses the method to test whether each table can be removed from a . If so, the method is called to remove the table. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Remove Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Remove/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Remove/source.vb" id="Snippet1"::: + ]]> The value specified for the table is . - The table does not belong to this collection. - - -or- - + The table does not belong to this collection. + + -or- + The table is part of a relationship. @@ -1557,21 +1557,21 @@ This method returns -1 when two or more tables have the same name but different The name of the object to remove. Removes the object with the specified name from the collection. - event occurs when a table is successfully removed. - - To determine whether a given table exists and can be removed before invoking , use the and the methods. - - - -## Examples - The following example uses the and methods to test whether a named table exists and can be removed. If so, the method is called to remove the table. - + event occurs when a table is successfully removed. + + To determine whether a given table exists and can be removed before invoking , use the and the methods. + + + +## Examples + The following example uses the and methods to test whether a named table exists and can be removed. If so, the method is called to remove the table. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Remove1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Remove/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Remove/source1.vb" id="Snippet1"::: + ]]> The collection does not have a table with the specified name. @@ -1623,21 +1623,21 @@ This method returns -1 when two or more tables have the same name but different The name of the namespace to look in. Removes the object with the specified name from the collection. - event occurs when a table is successfully removed. - - To determine whether a given table exists and can be removed before invoking , use the and the methods. - - - -## Examples - The following example uses the and methods to test whether a named table exists and can be removed. If so, the method is called to remove the table. - + event occurs when a table is successfully removed. + + To determine whether a given table exists and can be removed before invoking , use the and the methods. + + + +## Examples + The following example uses the and methods to test whether a named table exists and can be removed. If so, the method is called to remove the table. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.Remove1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Remove/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/Remove/source1.vb" id="Snippet1"::: + ]]> The collection does not have a table with the specified name. @@ -1688,19 +1688,19 @@ This method returns -1 when two or more tables have the same name but different The index of the to remove. Removes the object at the specified index from the collection. - event occurs when a table is successfully removed. - - - -## Examples - The following example uses the and methods to test whether a table exists with the index 10. If so, the method is called to remove the table. - + event occurs when a table is successfully removed. + + + +## Examples + The following example uses the and methods to test whether a table exists with the index 10. If so, the method is called to remove the table. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableCollection.RemoveAt/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/RemoveAt/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableCollection/RemoveAt/source.vb" id="Snippet1"::: + ]]> The collection does not have a table at the specified index. diff --git a/xml/System.Data/DataTableExtensions.xml b/xml/System.Data/DataTableExtensions.xml index 41aaabdefa4..8caab8c9e6b 100644 --- a/xml/System.Data/DataTableExtensions.xml +++ b/xml/System.Data/DataTableExtensions.xml @@ -530,13 +530,13 @@ If an exception is thrown during the copy of a data row into the target table, such as a constraint exception, the `errorHandler` delegate is called. A is passed to the `errorHandler` delegate with the following values: -- The property is set to a copy of the source data. +- The property is set to a copy of the source data. -- The property is set to the target . +- The property is set to the target . -- The property is set to the caught exception. +- The property is set to the caught exception. - The property is read after the delegate call returns. If the property is `true`, the source sequence continues to be enumerated and loaded into the data table. If the property is `false`, the original exception is thrown from the method. + The property is read after the delegate call returns. If the property is `true`, the source sequence continues to be enumerated and loaded into the data table. If the property is `false`, the original exception is thrown from the method. For more information, see [Creating a DataTable From a Query](/dotnet/framework/data/adonet/creating-a-datatable-from-a-query-linq-to-dataset). diff --git a/xml/System.Data/DataTableReader.xml b/xml/System.Data/DataTableReader.xml index 7c7ec8aa3c4..a0dd0272fad 100644 --- a/xml/System.Data/DataTableReader.xml +++ b/xml/System.Data/DataTableReader.xml @@ -51,17 +51,17 @@ The obtains the contents of one or more objects in the form of one or more read-only, forward-only result sets. - works much like any other data reader, such as the , except that the provides for iterating over rows in a . In other words, it provides for iterating over rows in a cache. The cached data can be modified while the is active, and the reader automatically maintains its position. - - When you create a from a , the resulting object contains one result set with the same data as the from which it was created, except for any rows that have been marked as deleted. The columns appear in the same order as in the original . The structure of the returned result is identical in schema and data to the original . A that was created by calling the method of a object contains multiple result sets if the contains more than one table. The results are in the same sequence as the objects in the of the object. - - The returned result set contains only the current version of each ; rows that are marked for deletion are skipped. - - The `DataTableReader` provides a stable iterator; that is, the contents of the `DataTableReader` are not invalidated if the size of the underlying collection is modified during iteration. For example, if one or more rows in the collection are deleted or removed during iteration, the current position within the `DataTableReader` is maintained appropriately and it does not invalidate the iterator. - + works much like any other data reader, such as the , except that the provides for iterating over rows in a . In other words, it provides for iterating over rows in a cache. The cached data can be modified while the is active, and the reader automatically maintains its position. + + When you create a from a , the resulting object contains one result set with the same data as the from which it was created, except for any rows that have been marked as deleted. The columns appear in the same order as in the original . The structure of the returned result is identical in schema and data to the original . A that was created by calling the method of a object contains multiple result sets if the contains more than one table. The results are in the same sequence as the objects in the of the object. + + The returned result set contains only the current version of each ; rows that are marked for deletion are skipped. + + The `DataTableReader` provides a stable iterator; that is, the contents of the `DataTableReader` are not invalidated if the size of the underlying collection is modified during iteration. For example, if one or more rows in the collection are deleted or removed during iteration, the current position within the `DataTableReader` is maintained appropriately and it does not invalidate the iterator. + ]]> @@ -156,32 +156,32 @@ The array of objects that supplies the results for the new object. Initializes a new instance of the class using the supplied array of objects. - based on all or a subset of the tables within a specific , call the `DataSet`'s method. If you want to create a new instance based on a group of `DataTable` instances that are not otherwise related, use this constructor. You can also take advantage of this constructor to rearrange the ordering of the `DataTables` within the `DataTableReader`, if their ordering within their source `DataSet` does not meet your needs. - - - -## Examples - In the following example, the TestConstructor method creates two instances. In order to demonstrate this constructor for the class, the sample creates a new `DataTableReader` based on an array that contains the two `DataTables`, and performs a simple operation, printing the contents from the first few columns to the console window. In order to test this application, create a new Console application, and paste the sample code into the newly created file. - + based on all or a subset of the tables within a specific , call the `DataSet`'s method. If you want to create a new instance based on a group of `DataTable` instances that are not otherwise related, use this constructor. You can also take advantage of this constructor to rearrange the ordering of the `DataTables` within the `DataTableReader`, if their ordering within their source `DataSet` does not meet your needs. + + + +## Examples + In the following example, the TestConstructor method creates two instances. In order to demonstrate this constructor for the class, the sample creates a new `DataTableReader` based on an array that contains the two `DataTables`, and performs a simple operation, printing the contents from the first few columns to the console window. In order to test this application, create a new Console application, and paste the sample code into the newly created file. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.ctor/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/.ctor/source.vb" id="Snippet1"::: - - The Console window displays the following results: - -``` -1 Mary -2 Andy -3 Peter -4 Russ -1 Wireless Network Card -2 Hard Drive -3 Monitor -4 CPU -``` - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/.ctor/source.vb" id="Snippet1"::: + + The Console window displays the following results: + +``` +1 Mary +2 Andy +3 Peter +4 Russ +1 Wireless Network Card +2 Hard Drive +3 Monitor +4 CPU +``` + ]]>
@@ -225,11 +225,11 @@ Closes the current . - @@ -273,11 +273,11 @@ The depth of nesting for the current row of the . The depth of nesting for the current row; always zero. - @@ -367,21 +367,21 @@ Gets the value of the specified column as a . The value of the specified column. - to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not the correct type, the example displays an error message for each row. - + to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetBoolean/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetBoolean/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetBoolean/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -433,21 +433,21 @@ Gets the value of the specified column as a byte. The value of the specified column. - to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. - + to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetByte/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetByte/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetByte/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -508,23 +508,23 @@ Reads a stream of bytes starting at the specified column offset into the buffer as an array starting at the specified buffer offset. The actual number of bytes read. - is reading a large data structure into a buffer - - If you pass a buffer that is `null` (`Nothing` in Visual Basic), `GetBytes` returns the length of the entire field in bytes, not the remaining size based on the buffer offset parameter. - - No conversions are performed; therefore the data retrieved must already be a byte array or coercible to a byte array. - - - -## Examples - The following example creates a based on data in the AdventureWorks sample database, and saves each image retrieved to a separate file in the C:\ folder. In order to test this application, create a new Console application, reference the System.Drawing.dll assembly, and paste the sample code into the newly created file. - + is reading a large data structure into a buffer + + If you pass a buffer that is `null` (`Nothing` in Visual Basic), `GetBytes` returns the length of the entire field in bytes, not the remaining size based on the buffer offset parameter. + + No conversions are performed; therefore the data retrieved must already be a byte array or coercible to a byte array. + + + +## Examples + The following example creates a based on data in the AdventureWorks sample database, and saves each image retrieved to a separate file in the C:\ folder. In order to test this application, create a new Console application, reference the System.Drawing.dll assembly, and paste the sample code into the newly created file. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetBytes/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetBytes/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetBytes/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -577,21 +577,21 @@ Gets the value of the specified column as a character. The value of the column. - to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in DataTableReader. If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. - + to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in DataTableReader. If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetChar/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetChar/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetChar/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -652,25 +652,25 @@ Returns the value of the specified column as a character array. The actual number of characters read. - The index passed was outside the range of 0 to - 1. @@ -722,26 +722,26 @@ Gets a string representing the data type of the specified column. A string representing the column's data type. - method always returns the type of the underlying instead of a provider-specific type. - - - -## Examples - The following console application displays a list of fields and their type names from a simple : - + method always returns the type of the underlying instead of a provider-specific type. + + + +## Examples + The following console application displays a list of fields and their type names from a simple : + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetDataTypeName/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetDataTypeName/source.vb" id="Snippet1"::: - - The Console window displays the following results: - -``` -ID: Int32 -Name: String -``` - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetDataTypeName/source.vb" id="Snippet1"::: + + The Console window displays the following results: + +``` +ID: Int32 +Name: String +``` + ]]> The index passed was outside the range of 0 to - 1. @@ -791,21 +791,21 @@ Name: String Gets the value of the specified column as a object. The value of the specified column. - or coercible to a `DataTime`. - - Call to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. - + or coercible to a `DataTime`. + + Call to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetDateTime/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetDateTime/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetDateTime/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -857,21 +857,21 @@ Name: String Gets the value of the specified column as a . The value of the specified column. - or coercible to a `Decimal`. - - Call to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. - + or coercible to a `Decimal`. + + Call to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetDecimal/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetDecimal/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetDecimal/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -923,21 +923,21 @@ Name: String Gets the value of the column as a double-precision floating point number. The value of the specified column. - to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. - + to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetDouble/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetDouble/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetDouble/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -986,35 +986,35 @@ Name: String Returns an enumerator that can be used to iterate through the item collection. An object that represents the item collection. - . Enumerators cannot be used to modify the underlying collection. - - At first, the enumerator is positioned before the first element in the collection. At this position, calling throws an exception. Therefore, you must call `MoveNext` to advance the enumerator to the first element of the collection before reading the value of `Current`. - - `Current` returns a , and returns the same object until either or is called. `MoveNext` sets `Current` to the next element. - - After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling `MoveNext` returns false. If the last call to `MoveNext` returned `false`, calling `Current` throws an exception. In addition, because the provides forward-only access to its data, calling the method of the IEnumerator throws a . - - The provides a stable enumerator. This means that even if row deletions or additions occur within the underlying data, the enumerator returned by a call to is still valid. - - - -## Examples - The following example demonstrates the use of the method. This includes the behavior of the enumerator when rows are deleted from the underlying while the enumerator is active. - + . Enumerators cannot be used to modify the underlying collection. + + At first, the enumerator is positioned before the first element in the collection. At this position, calling throws an exception. Therefore, you must call `MoveNext` to advance the enumerator to the first element of the collection before reading the value of `Current`. + + `Current` returns a , and returns the same object until either or is called. `MoveNext` sets `Current` to the next element. + + After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling `MoveNext` returns false. If the last call to `MoveNext` returned `false`, calling `Current` throws an exception. In addition, because the provides forward-only access to its data, calling the method of the IEnumerator throws a . + + The provides a stable enumerator. This means that even if row deletions or additions occur within the underlying data, the enumerator returned by a call to is still valid. + + + +## Examples + The following example demonstrates the use of the method. This includes the behavior of the enumerator when rows are deleted from the underlying while the enumerator is active. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetEnumerator/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetEnumerator/source.vb" id="Snippet1"::: - - The procedure displays the following text in the Console window: - -``` -Peter -Mary -Russ -``` - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetEnumerator/source.vb" id="Snippet1"::: + + The procedure displays the following text in the Console window: + +``` +Peter +Mary +Russ +``` + ]]> An attempt was made to read or access a column in a closed . @@ -1069,14 +1069,14 @@ Russ Gets the that is the data type of the object. The that is the data type of the object. - instance in order to display a list of all the fields and the full name for each type in the Console window. - + instance in order to display a list of all the fields and the full name for each type in the Console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetFieldType/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetFieldType/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetFieldType/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -1126,21 +1126,21 @@ Russ Gets the value of the specified column as a single-precision floating point number. The value of the column. - to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. - + to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetFloat/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetFloat/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetFloat/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -1192,21 +1192,21 @@ Russ Gets the value of the specified column as a globally-unique identifier (GUID). The value of the specified column. - or coercible to a `Guid`. - - Call to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in DataTableReader. If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. - + or coercible to a `Guid`. + + Call to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in DataTableReader. If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetGuid/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetGuid/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetGuid/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -1258,21 +1258,21 @@ Russ Gets the value of the specified column as a 16-bit signed integer. The value of the specified column. - or coercible to an `Int16`. - - Call to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. - + or coercible to an `Int16`. + + Call to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetInt16/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetInt16/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetInt16/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -1324,21 +1324,21 @@ Russ Gets the value of the specified column as a 32-bit signed integer. The value of the specified column. - or coercible to an `Int32`. - - Call to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. - + or coercible to an `Int32`. + + Call to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetInt32/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetInt32/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetInt32/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -1390,21 +1390,21 @@ Russ Gets the value of the specified column as a 64-bit signed integer. The value of the specified column. - or coercible to an `Int64`. - - Call to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. - + or coercible to an `Int64`. + + Call to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column is not of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetInt64/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetInt64/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetInt64/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -1456,19 +1456,19 @@ Russ Gets the value of the specified column as a . The name of the specified column. - methods provide inverse functionality. That is, calling `GetOrdinal` on the return value of calling `GetName` should return the original parameter passed to `GetName`; the same applies to calling the procedures in the opposite order. - - - -## Examples - The following simple example includes a procedure that lists the names of all the columns within the specified `DataTableReader`, and the column's ordinal position, to the Console window. - + methods provide inverse functionality. That is, calling `GetOrdinal` on the return value of calling `GetName` should return the original parameter passed to `GetName`; the same applies to calling the procedures in the opposite order. + + + +## Examples + The following simple example includes a procedure that lists the names of all the columns within the specified `DataTableReader`, and the column's ordinal position, to the Console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetName/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetName/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetName/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -1518,25 +1518,25 @@ Russ Gets the column ordinal, given the name of the column. The zero-based column ordinal. - class must be provided with an ordinal column number, you can use the `GetOrdinal` method to retrieve the column number, given the name of the column. - - `GetOrdinal` performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. If the column number is not found an `ArgumentException` is thrown. - - `GetOrdinal` is kana-width insensitive. - - Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call `GetOrdinal` within a loop. Save time by calling `GetOrdinal` one time and assigning the results to an integer variable for use within the loop - - - -## Examples - If you have only a column name, in which case the column name is user supplied, and you must retrieve information from the column, you can use a procedure like the following to extract the required information. In this example, the procedure accepts a column name and returns the data that is contained within that column for the current row in the : - + class must be provided with an ordinal column number, you can use the `GetOrdinal` method to retrieve the column number, given the name of the column. + + `GetOrdinal` performs a case-sensitive lookup first. If it fails, a second case-insensitive search is made. If the column number is not found an `ArgumentException` is thrown. + + `GetOrdinal` is kana-width insensitive. + + Because ordinal-based lookups are more efficient than named lookups, it is inefficient to call `GetOrdinal` within a loop. Save time by calling `GetOrdinal` one time and assigning the results to an integer variable for use within the loop + + + +## Examples + If you have only a column name, in which case the column name is user supplied, and you must retrieve information from the column, you can use a procedure like the following to extract the required information. In this example, the procedure accepts a column name and returns the data that is contained within that column for the current row in the : + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetOrdinal/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetOrdinal/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetOrdinal/source.vb" id="Snippet1"::: + ]]> An attempt was made to read or access a column in a closed . @@ -1592,11 +1592,11 @@ Russ Gets the type of the specified column in provider-specific format. The that is the data type of the object. - always returns the type stored within the underlying , the value returned by calling the method always returns the same type as the type stored within the . When you work with the class, calling the method returns the same type as calling the method. - + always returns the type stored within the underlying , the value returned by calling the method always returns the same type as the type stored within the . When you work with the class, calling the method returns the same type as calling the method. + ]]> The index passed was outside the range of 0 to - 1. @@ -1647,11 +1647,11 @@ Russ Gets the value of the specified column in provider-specific format. The value of the specified column in provider-specific format. - always returns the type stored within the underlying , the value returned by calling the method always returns data of the same type as the data stored within the . When you work with the class, calling the method returns the same value and type as calling the method. - + always returns the type stored within the underlying , the value returned by calling the method always returns data of the same type as the data stored within the . When you work with the class, calling the method returns the same value and type as calling the method. + ]]> The index passed was outside the range of 0 to - 1. @@ -1703,11 +1703,11 @@ Russ Fills the supplied array with provider-specific type information for all the columns in the . The number of column values copied into the array. - always returns the data of the type stored within the underlying , the values returned by calling the method is always of the same types as the data stored within the . When you work with the class, calling the method returns the same values and types as calling the method. - + always returns the data of the type stored within the underlying , the values returned by calling the method is always of the same types as the data stored within the . When you work with the class, calling the method returns the same values and types as calling the method. + ]]> An attempt was made to retrieve data from a deleted row. @@ -1755,47 +1755,47 @@ Russ Returns a that describes the column metadata of the . A that describes the column metadata. - .| -|ColumnOrdinal|The ordinal of the column| -|ColumnSize|-1 if the (or ) property of the cannot be determined or is not relevant; otherwise, 0 or a positive integer that contains the `MaxLength` value.| -|NumericPrecision|If the column type is a numeric type, this is the maximum precision of the column. If the column type is not a numeric data type, this is a null value.| -|NumericScale|If column data type has a scale component, return the number of digits to the right of the decimal point. Otherwise, return a null value.| -|DataType|The underlying type of the column.| -|ProviderType|The indicator of the column's data type. If the data type of the column varies from row to row, this value is . This column cannot contain a null value.| -|IsLong|`true` if the data type of the column is and its property is -1. Otherwise, `false`.| -|AllowDBNull|`true` if the AllowDbNull constraint is set to true for the column; otherwise, `false`.| -|IsReadOnly|`true` if the column cannot be modified; otherwise `false`.| -|IsRowVersion|`false`, for every column.| -|IsUnique|`true`: No two rows in the can have the same value in this column. `IsUnique` is guaranteed to be true if the column represents a key by itself or if there is a constraint of type UNIQUE that applies only to this column. `false`: The column can contain duplicate values in the `DataTable`. The default of this column is `false`.| -|IsKey|`true`: The column is one of a set of columns that, taken together, uniquely identify the row in the . The set of columns with `IsKey` set to `true` must uniquely identify a row in the `DataTable`. There is no requirement that this set of columns is a minimal set of columns. This set of columns may be generated from a `DataTable` primary key, a unique constraint or a unique index. `false`: The column is not required to uniquely identify the row. This value is `true` if the column participates in a single or composite primary key. Otherwise, its value is `false`.| -|IsAutoIncrement|`true`: The column assigns values to new rows in fixed increments. `false`: The column does not assign values to new rows in fixed increments. The default of this column is `false`.| -|BaseCatalogName|The name of the catalog in the data store that contains the column. `Null` if the base catalog name cannot be determined. The default value for this column is a `null` value.| -|BaseSchemaName|This value is always `Null`.| -|BaseTableName|The name of the .| -|BaseColumnName|The name of the column in the .| -|AutoIncrementSeed|The value of the 's property.| -|AutoIncrementStep|The value of the 's property.| -|DefaultValue|The value of the 's property.| -|Expression|The expression string, if the current column is an expression column and all columns used in the expression belong to the same `T:System.Data.DataTable` that contains the expression column; otherwise `null`.| -|ColumnMapping|The value associated with the . The type can be one of `Attribute`, `Element`, `Hidden`, or `SimpleContent`. The default value is `Element`.| -|BaseTableNamespace|The value of the 's property.| -|BaseColumnNamespace|The value of the 's property.| - - - -## Examples - The following console application example retrieves schema information about the specified column. Pass the `DisplaySchemaTableInfo` procedure a and an integer representing the ordinal position of a column within the `DataTableReader`, and the procedure outputs schema information to the console window. - + .| +|ColumnOrdinal|The ordinal of the column| +|ColumnSize|-1 if the (or ) property of the cannot be determined or is not relevant; otherwise, 0 or a positive integer that contains the `MaxLength` value.| +|NumericPrecision|If the column type is a numeric type, this is the maximum precision of the column. If the column type is not a numeric data type, this is a null value.| +|NumericScale|If column data type has a scale component, return the number of digits to the right of the decimal point. Otherwise, return a null value.| +|DataType|The underlying type of the column.| +|ProviderType|The indicator of the column's data type. If the data type of the column varies from row to row, this value is . This column cannot contain a null value.| +|IsLong|`true` if the data type of the column is and its property is -1. Otherwise, `false`.| +|AllowDBNull|`true` if the AllowDbNull constraint is set to true for the column; otherwise, `false`.| +|IsReadOnly|`true` if the column cannot be modified; otherwise `false`.| +|IsRowVersion|`false`, for every column.| +|IsUnique|`true`: No two rows in the can have the same value in this column. `IsUnique` is guaranteed to be true if the column represents a key by itself or if there is a constraint of type UNIQUE that applies only to this column. `false`: The column can contain duplicate values in the `DataTable`. The default of this column is `false`.| +|IsKey|`true`: The column is one of a set of columns that, taken together, uniquely identify the row in the . The set of columns with `IsKey` set to `true` must uniquely identify a row in the `DataTable`. There is no requirement that this set of columns is a minimal set of columns. This set of columns may be generated from a `DataTable` primary key, a unique constraint or a unique index. `false`: The column is not required to uniquely identify the row. This value is `true` if the column participates in a single or composite primary key. Otherwise, its value is `false`.| +|IsAutoIncrement|`true`: The column assigns values to new rows in fixed increments. `false`: The column does not assign values to new rows in fixed increments. The default of this column is `false`.| +|BaseCatalogName|The name of the catalog in the data store that contains the column. `Null` if the base catalog name cannot be determined. The default value for this column is a `null` value.| +|BaseSchemaName|This value is always `Null`.| +|BaseTableName|The name of the .| +|BaseColumnName|The name of the column in the .| +|AutoIncrementSeed|The value of the 's property.| +|AutoIncrementStep|The value of the 's property.| +|DefaultValue|The value of the 's property.| +|Expression|The expression string, if the current column is an expression column and all columns used in the expression belong to the same `T:System.Data.DataTable` that contains the expression column; otherwise `null`.| +|ColumnMapping|The value associated with the . The type can be one of `Attribute`, `Element`, `Hidden`, or `SimpleContent`. The default value is `Element`.| +|BaseTableNamespace|The value of the 's property.| +|BaseColumnNamespace|The value of the 's property.| + + + +## Examples + The following console application example retrieves schema information about the specified column. Pass the `DisplaySchemaTableInfo` procedure a and an integer representing the ordinal position of a column within the `DataTableReader`, and the procedure outputs schema information to the console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetSchemaTable/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetSchemaTable/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetSchemaTable/source.vb" id="Snippet1"::: + ]]> The is closed. @@ -1844,19 +1844,19 @@ Russ Gets the value of the specified column as a string. The value of the specified column. - to see if there are null values before calling this method. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column of the correct type, the example displays an error message for each row. - + to see if there are null values before calling this method. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetString/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetString/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetString/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -1908,19 +1908,19 @@ Russ Gets the value of the specified column in its native format. The value of the specified column. This method returns for null columns. - to see if there are null values before calling this method, you do not have to do this. - - - -## Examples - The following example iterates through all the columns within the current row in a , displaying the contents of each column and the column name. Generally, if your intent is to work with all the columns within a row retrieved by a , consider using the method instead, because it is more efficient. - + to see if there are null values before calling this method, you do not have to do this. + + + +## Examples + The following example iterates through all the columns within the current row in a , displaying the contents of each column and the column name. Generally, if your intent is to work with all the columns within a row retrieved by a , consider using the method instead, because it is more efficient. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetValue/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetValue/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetValue/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -1971,23 +1971,23 @@ Russ Populates an array of objects with the column values of the current row. The number of column values copied into the array. - , the `GetValues` method provides the most efficient solution. - - You can pass an array that contains fewer than the number of columns that are contained in the resulting row. Only the amount of data the `Object` array can hold is copied to the array. You can also pass an `Object` array whose length is more than the number of columns that are contained in the resulting row, in which case the additional array elements remains unchanged by the method call. - - This method places `DBNull` in the output array for null columns. - - - -## Examples - The following example demonstrates using an array that is the correct size, to read all values from the current row in the supplied . In addition, the sample demonstrates using a fixed-sized array that could be either smaller or larger than the number of available columns. - + , the `GetValues` method provides the most efficient solution. + + You can pass an array that contains fewer than the number of columns that are contained in the resulting row. Only the amount of data the `Object` array can hold is copied to the array. You can also pass an `Object` array whose length is more than the number of columns that are contained in the resulting row, in which case the additional array elements remains unchanged by the method call. + + This method places `DBNull` in the output array for null columns. + + + +## Examples + The following example demonstrates using an array that is the correct size, to read all values from the current row in the supplied . In addition, the sample demonstrates using a fixed-sized array that could be either smaller or larger than the number of available columns. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.GetValueObject/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetValues/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/GetValues/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -2035,21 +2035,21 @@ Russ if the contains one or more rows; otherwise . - contains multiple result sets, you can examine the value of the `HasRows` property immediately after you call the method in order to determine whether the new result set contains rows. - - Use the `HasRows` property to avoid the requirement to call the method of the if there are no rows within the current result set. - - - -## Examples - The following example fills two instances with data. The first contains one row, and the second contains no rows. The example then creates a that contains both objects, and calls the PrintData method to display the contents of each, checking the value of the property of each before it makes the call to PrintData. - + contains multiple result sets, you can examine the value of the `HasRows` property immediately after you call the method in order to determine whether the new result set contains rows. + + Use the `HasRows` property to avoid the requirement to call the method of the if there are no rows within the current result set. + + + +## Examples + The following example fills two instances with data. The first contains one row, and the second contains no rows. The example then creates a that contains both objects, and calls the PrintData method to display the contents of each, checking the value of the property of each before it makes the call to PrintData. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.HasRows/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/HasRows/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/HasRows/source.vb" id="Snippet1"::: + ]]> An attempt was made to retrieve information about a closed . @@ -2097,11 +2097,11 @@ Russ if the is closed; otherwise, . - is the only method and `IsClosed` and are the only properties that can be accessed after the has been closed. - + is the only method and `IsClosed` and are the only properties that can be accessed after the has been closed. + ]]> @@ -2150,19 +2150,19 @@ Russ if the specified column value is equivalent to ; otherwise, . - , , and so on) to avoid raising an error. - - - -## Examples - The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column of the correct type, the example displays an error message for each row. - + , , and so on) to avoid raising an error. + + + +## Examples + The following example displays the contents of the column numbered 2 within the passed-in . If the value the column within a particular row is null, the code displays the text \. If the data within the column of the correct type, the example displays an error message for each row. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.IsDbNull/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/IsDBNull/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/IsDBNull/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -2223,19 +2223,19 @@ Russ Gets the value of the specified column in its native format given the column ordinal. The value of the specified column in its native format. - behaves identically to the method. - - - -## Examples - The following example displays the contents of all the columns, in all the rows from the supplied . The code uses the method (the indexer, in Microsoft C#) to retrieve the value that is contained in each column. - + behaves identically to the method. + + + +## Examples + The following example displays the contents of all the columns, in all the rows from the supplied . The code uses the method (the indexer, in Microsoft C#) to retrieve the value that is contained in each column. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.Item/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/Item/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/Item/source.vb" id="Snippet1"::: + ]]> The index passed was outside the range of 0 to - 1. @@ -2285,23 +2285,23 @@ Russ Gets the value of the specified column in its native format given the column name. The value of the specified column in its native format. - corresponds to calling the method, and then subsequently calling the method. - - - -## Examples - Given a and a column name, the GetValueByName procedure returns the value of the specified column. Before calling this procedure, you must create a new instance and call its Read method at least one time to position the row pointer on a row of data. - + corresponds to calling the method, and then subsequently calling the method. + + + +## Examples + Given a and a column name, the GetValueByName procedure returns the value of the specified column. Before calling this procedure, you must create a new instance and call its Read method at least one time to position the row pointer on a row of data. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.ItemName/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/Item/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/Item/source1.vb" id="Snippet1"::: + ]]> The name specified is not a valid column name. @@ -2350,34 +2350,34 @@ Russ if there was another result set; otherwise . - over a that contains two or more tables, or an array that contains two or more instances. - - A new is positioned on the first result. - - - -## Examples - In the following example, the TestConstructor method creates two instances. In order to demonstrate this constructor for the class, the sample creates a new `DataTableReader` based on an array that contains the two `DataTables`, and performs a simple operation, printing the contents from the first few columns to the console window. In order to test this application, create a new Console application, and paste the sample code into the newly created file. - + over a that contains two or more tables, or an array that contains two or more instances. + + A new is positioned on the first result. + + + +## Examples + In the following example, the TestConstructor method creates two instances. In order to demonstrate this constructor for the class, the sample creates a new `DataTableReader` based on an array that contains the two `DataTables`, and performs a simple operation, printing the contents from the first few columns to the console window. In order to test this application, create a new Console application, and paste the sample code into the newly created file. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.NextResult/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/NextResult/source.vb" id="Snippet1"::: - - The Console window displays the following results: - -``` -1 Mary -2 Andy -3 Peter -4 Russ -1 Wireless Network Card -2 Hard Drive -3 Monitor -4 CPU -``` - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/NextResult/source.vb" id="Snippet1"::: + + The Console window displays the following results: + +``` +1 Mary +2 Andy +3 Peter +4 Russ +1 Wireless Network Card +2 Hard Drive +3 Monitor +4 CPU +``` + ]]> An attempt was made to navigate within a closed . @@ -2424,19 +2424,19 @@ Russ if there was another row to read; otherwise . - is before the first record. Therefore, you must call `Read` to start accessing any data. - - - -## Examples - The PrintColumns procedure loops through all the rows in the , displaying the contents of each column in the Console window. - + is before the first record. Therefore, you must call `Read` to start accessing any data. + + + +## Examples + The PrintColumns procedure loops through all the rows in the , displaying the contents of each column in the Console window. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataTableReader.Read/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/Read/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableReader/Read/source.vb" id="Snippet1"::: + ]]> An attempt was made to read or access a column in a closed . diff --git a/xml/System.Data/DataView.xml b/xml/System.Data/DataView.xml index 07bb8dd627a..f983bb4f27b 100644 --- a/xml/System.Data/DataView.xml +++ b/xml/System.Data/DataView.xml @@ -121,35 +121,35 @@ Represents a databindable, customized view of a for sorting, filtering, searching, editing, and navigation. The does not store data, but instead represents a connected view of its corresponding . Changes to the 's data will affect the . Changes to the 's data will affect all s associated with it. - is to allow for data binding on both Windows Forms and Web Forms. - - Additionally, a can be customized to present a subset of data from the . This capability lets you have two controls bound to the same , but that show different versions of the data. For example, one control might be bound to a that shows all the rows in the table, and a second might be configured to display only the rows that have been deleted from the . The also has a property. This returns the default for the table. For example, if you want to create a custom view on the table, set the on the returned by the . - - To create a filtered and sorted view of data, set the and properties. Then, use the property to return a single . - - You can also add and delete from the set of rows using the and methods. When you use those methods, the property can set to specify that only deleted rows or new rows be displayed by the . - + is to allow for data binding on both Windows Forms and Web Forms. + + Additionally, a can be customized to present a subset of data from the . This capability lets you have two controls bound to the same , but that show different versions of the data. For example, one control might be bound to a that shows all the rows in the table, and a second might be configured to display only the rows that have been deleted from the . The also has a property. This returns the default for the table. For example, if you want to create a custom view on the table, set the on the returned by the . + + To create a filtered and sorted view of data, set the and properties. Then, use the property to return a single . + + You can also add and delete from the set of rows using the and methods. When you use those methods, the property can set to specify that only deleted rows or new rows be displayed by the . + > [!NOTE] -> If you do not explicitly specify sort criteria for `DataView`, the `DataRowView` objects in `DataView` are sorted based on the index of DataView's corresponding `DataRow` in the `DataTable.Rows` `DataRowCollection`. - - LINQ to DataSet allows developers to create complex, powerful queries over a by using LINQ. A LINQ to DataSet query returns an enumeration of objects, however, which is not easily used in a binding scenario. can be created from a LINQ to DataSet query and takes on the filtering and sorting characteristics of that query. LINQ to DataSet extends the functionality of the by providing LINQ expression-based filtering and sorting, which allows for much more complex and powerful filtering and sorting operations than string-based filtering and sorting. See [Data Binding and LINQ to DataSet](/dotnet/framework/data/adonet/data-binding-and-linq-to-dataset) for more information. - - - -## Examples - The following example creates a single with one column and five rows. Two objects are created and the is set on each to show different views of the table data. The values are then printed. - +> If you do not explicitly specify sort criteria for `DataView`, the `DataRowView` objects in `DataView` are sorted based on the index of DataView's corresponding `DataRow` in the `DataTable.Rows` `DataRowCollection`. + + LINQ to DataSet allows developers to create complex, powerful queries over a by using LINQ. A LINQ to DataSet query returns an enumeration of objects, however, which is not easily used in a binding scenario. can be created from a LINQ to DataSet query and takes on the filtering and sorting characteristics of that query. LINQ to DataSet extends the functionality of the by providing LINQ expression-based filtering and sorting, which allows for much more complex and powerful filtering and sorting operations than string-based filtering and sorting. See [Data Binding and LINQ to DataSet](/dotnet/framework/data/adonet/data-binding-and-linq-to-dataset) for more information. + + + +## Examples + The following example creates a single with one column and five rows. Two objects are created and the is set on each to show different views of the table data. The values are then printed. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Overview/source.vb" id="Snippet1"::: - - The following example creates a of online orders ordered by total due from a LINQ to DataSet query: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Overview/source.vb" id="Snippet1"::: + + The following example creates a of online orders ordered by total due from a LINQ to DataSet query: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DP DataView Samples/CS/Form1.cs" id="Snippetcreateldvfromquery1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableExtensions/AsDataView/Form1.vb" id="Snippetcreateldvfromquery1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataTableExtensions/AsDataView/Form1.vb" id="Snippetcreateldvfromquery1"::: + ]]> This type is safe for multithreaded read operations. You must synchronize any write operations. @@ -206,14 +206,14 @@ Initializes a new instance of the class. - . - + . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.DataView Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/.ctor/source.vb" id="Snippet1"::: + ]]> @@ -262,14 +262,14 @@ A to add to the . Initializes a new instance of the class with the specified . - with the specified . - + with the specified . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.DataView1 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/.ctor/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/.ctor/source1.vb" id="Snippet1"::: + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -335,14 +335,14 @@ A to apply to the . Initializes a new instance of the class with the specified , , , and . - with the specified . - + with the specified . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.DataView2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/.ctor/source2.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/.ctor/source2.vb" id="Snippet1"::: + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -389,14 +389,14 @@ Adds a new row to the . A new object. - method to return a new that has been added to the . - + method to return a new that has been added to the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.AddNew Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AddNew/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AddNew/source.vb" id="Snippet1"::: + ]]> @@ -455,14 +455,14 @@ , if deletes are allowed; otherwise, . - property before deleting a from a . - + property before deleting a from a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.AllowDelete Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AllowDelete/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AllowDelete/source.vb" id="Snippet1"::: + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -519,14 +519,14 @@ , if edits are allowed; otherwise, . - method before editing a row in a . - + method before editing a row in a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.AllowEdit Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AllowEdit/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AllowEdit/source.vb" id="Snippet1"::: + ]]> @@ -586,14 +586,14 @@ , if new rows can be added; otherwise, . - property to true before adding a new row with the method. - + property to true before adding a new row with the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.AllowNew Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AllowNew/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/AllowNew/source.vb" id="Snippet1"::: + ]]> @@ -702,11 +702,11 @@ Starts the initialization of a that is used on a form or used by another component. The initialization occurs at runtime. - method ends the initialization. Using the `BeginInit` and `EndInit` methods prevents the control from being used before it is fully initialized. - + method ends the initialization. Using the `BeginInit` and `EndInit` methods prevents the control from being used before it is fully initialized. + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -752,13 +752,13 @@ Closes the . - in derived classes. Use the corresponding method to open the . - - This property is designed for internal use only. - + in derived classes. Use the corresponding method to open the . + + This property is designed for internal use only. + ]]> @@ -1017,18 +1017,18 @@ The index of the row to delete. Deletes a row at the specified index. - , its state changes to `DataViewRowState.Deleted`. You can roll back the deletion by calling on the . - - - -## Examples - The following example uses the method to delete a row. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Delete/source.vb" id="Snippet1"::: - + , its state changes to `DataViewRowState.Deleted`. You can roll back the deletion by calling on the . + + + +## Examples + The following example uses the method to delete a row. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Delete/source.vb" id="Snippet1"::: + ]]> @@ -1080,11 +1080,11 @@ to release both managed and unmanaged resources; to release only unmanaged resources. Disposes of the resources (other than memory) used by the object. - and the underlying stop after this method is called. should be called for all objects. - + and the underlying stop after this method is called. should be called for all objects. + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -1133,11 +1133,11 @@ Ends the initialization of a that is used on a form or used by another component. The initialization occurs at runtime. - method starts the initialization. Using the `BeginInit` and `EndInit` methods prevents the control from being used before it is fully initialized. - + method starts the initialization. Using the `BeginInit` and `EndInit` methods prevents the control from being used before it is fully initialized. + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -1246,13 +1246,13 @@ Finds a row in the by the specified sort key value. The index of the row in the that contains the sort key value specified; otherwise -1 if the sort key value does not exist. - method to return the index of the row that contains the value in the sort key column that you want. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Find/source.vb" id="Snippet1"::: - + method to return the index of the row that contains the value in the sort key column that you want. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Find/source.vb" id="Snippet1"::: + ]]> @@ -1311,13 +1311,13 @@ Finds a row in the by the specified sort key values. The index of the position of the first row in the that matches the sort key values specified; otherwise -1 if there are no matching sort key values. - method to return the index of a row that contains specified values in its sort key columns. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Find/source1.vb" id="Snippet1"::: - + method to return the index of a row that contains specified values in its sort key columns. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Find/source1.vb" id="Snippet1"::: + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -1688,13 +1688,13 @@ , if the source is open; otherwise, . - is a "view" on a because it provides custom sorting and filtering of the data. The property can be queried to determine whether a has been opened by using the method. - - This property is designed for internal use only. - + is a "view" on a because it provides custom sorting and filtering of the data. The property can be queried to determine whether a has been opened by using the method. + + This property is designed for internal use only. + ]]> @@ -1803,14 +1803,14 @@ Occurs when the list managed by the changes. - event of a . - + event of a . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.ListChanged Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/ListChanged/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/ListChanged/source.vb" id="Snippet1"::: + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -1902,13 +1902,13 @@ Opens a . - in derived classes. Use the corresponding method to close the . - - This property is designed for internal use only. - + in derived classes. Use the corresponding method to close the . + + This property is designed for internal use only. + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -2011,27 +2011,27 @@ Gets or sets the expression used to filter which rows are viewed in the . A string that specifies how rows are to be filtered. - value, specify the name of a column followed by an operator and a value to filter on. The value must be in quotation marks. For example: - - "LastName = 'Smith'" - - See the property of the class for more information. - - To return only those columns with null values, use the following expression: - - "Isnull(Col1,'Null Column') = 'Null Column'" - - - -## Examples - The following example creates a and sets its property. - + value, specify the name of a column followed by an operator and a value to filter on. The value must be in quotation marks. For example: + + "LastName = 'Smith'" + + See the property of the class for more information. + + To return only those columns with null values, use the following expression: + + "Isnull(Col1,'Null Column') = 'Null Column'" + + + +## Examples + The following example creates a and sets its property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.RowFilter Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/RowFilter/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/RowFilter/source.vb" id="Snippet1"::: + ]]> @@ -2089,26 +2089,26 @@ Gets or sets the row state filter used in the . One of the values. - method will have their value set to `Deleted`. Those rows added using the method will similarly have the property set to `Added`. - + method will have their value set to `Deleted`. Those rows added using the method will similarly have the property set to `Added`. + > [!NOTE] -> Using the method of the class does not mean that a row will be marked as `Deleted`. Use the method instead to make sure that such rows can be viewed in the . - - New rows will also be visible when the is set to `ModifiedCurrent` or `CurrentRows`. - - Deleted rows will also be visible when the is set to `ModifiedOriginal` and `OriginalRows`. - - - -## Examples - The following example creates a with a single column, and then changes the data and sets the of the to display different row sets, depending on the . - +> Using the method of the class does not mean that a row will be marked as `Deleted`. Use the method instead to make sure that such rows can be viewed in the . + + New rows will also be visible when the is set to `ModifiedCurrent` or `CurrentRows`. + + Deleted rows will also be visible when the is set to `ModifiedOriginal` and `OriginalRows`. + + + +## Examples + The following example creates a with a single column, and then changes the data and sets the of the to display different row sets, depending on the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.RowStateFilter Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/RowStateFilter/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/RowStateFilter/source.vb" id="Snippet1"::: + ]]> @@ -2171,21 +2171,21 @@ Gets or sets the sort column or columns, and sort order for the . A string that contains the column name followed by "ASC" (ascending) or "DESC" (descending). Columns are sorted ascending by default. Multiple columns can be separated by commas. - to sort the table by two columns. - + to sort the table by two columns. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.Sort Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Sort/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Sort/source.vb" id="Snippet1"::: + ]]> @@ -2235,11 +2235,11 @@ 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. + ]]> @@ -2292,11 +2292,11 @@ 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. + ]]> @@ -2349,11 +2349,11 @@ 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. + ]]> @@ -2401,11 +2401,11 @@ For a description of this member, see . - . Instead, use the Clear method on the object returned by . - + . Instead, use the Clear method on the object returned by . + ]]> @@ -2458,11 +2458,11 @@ 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. + ]]> @@ -2515,11 +2515,11 @@ 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. + ]]> @@ -2573,11 +2573,11 @@ An value to be inserted. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2624,11 +2624,11 @@ 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. + ]]> @@ -2675,11 +2675,11 @@ 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. + ]]> @@ -2731,11 +2731,11 @@ 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. + ]]> @@ -2787,11 +2787,11 @@ An value. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2842,11 +2842,11 @@ An value. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2898,11 +2898,11 @@ A object. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -2952,11 +2952,11 @@ For a description of this member, see . The item added to the list. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -3003,11 +3003,11 @@ 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. + ]]> @@ -3054,11 +3054,11 @@ 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. + ]]> @@ -3105,11 +3105,11 @@ 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. + ]]> @@ -3163,11 +3163,11 @@ A object. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -3222,11 +3222,11 @@ 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. + ]]> @@ -3273,11 +3273,11 @@ 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. + ]]> @@ -3329,11 +3329,11 @@ A object. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -3381,11 +3381,11 @@ For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -3432,11 +3432,11 @@ 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. + ]]> @@ -3484,11 +3484,11 @@ 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. + ]]> @@ -3535,11 +3535,11 @@ 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. + ]]> @@ -3586,11 +3586,11 @@ 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. + ]]> @@ -3637,11 +3637,11 @@ 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. + ]]> @@ -3692,11 +3692,11 @@ A object. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -3750,11 +3750,11 @@ 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. + ]]> @@ -3801,11 +3801,11 @@ For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -3858,11 +3858,11 @@ For a description of this member, see . For a description of this member, see . - . Instead, use the Clear method on the object returned by . - + . Instead, use the Clear method on the object returned by . + ]]> @@ -3909,11 +3909,11 @@ 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. + ]]> @@ -3960,11 +3960,11 @@ 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. + ]]> @@ -4017,11 +4017,11 @@ For a description of this member, see . The that represents the properties on each item used to bind data. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -4074,11 +4074,11 @@ 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. + ]]> @@ -4142,21 +4142,21 @@ Gets or sets the source . A that provides the data for this view. - also has a property which returns the default for the table. For example, if you want to create a custom view on the table, set the on the returned by the . - - You can only set the property if the current value is null. - - - -## Examples - The following example gets the of the current . - + also has a property which returns the default for the table. For example, if you want to create a custom view on the table, set the on the returned by the . + + You can only set the property if the current value is null. + + + +## Examples + The following example gets the of the current . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.Table Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Table/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/Table/source.vb" id="Snippet1"::: + ]]> @@ -4172,13 +4172,13 @@ Creates and returns a new based on rows in an existing . - maintains the values of the following properties from the source : , , , and . Each column in the resulting contains an identical copy of all the corresponding properties in the underlying . - - The instances in the returned `DataTable` will contain values that are consistent with CLR semantics. That is, for all data types besides user-defined types, the corresponding column values are copied by value. For user-defined data types, the column data is copied by reference. - + maintains the values of the following properties from the source : , , , and . Each column in the resulting contains an identical copy of all the corresponding properties in the underlying . + + The instances in the returned `DataTable` will contain values that are consistent with CLR semantics. That is, for all data types besides user-defined types, the corresponding column values are copied by value. For user-defined data types, the column data is copied by reference. + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -4224,40 +4224,40 @@ Creates and returns a new based on rows in an existing . A new instance that contains the requested rows and columns. - , its name is the same as the name of the source `DataTable`. Because this method does not let you specify a subset of available columns, the output table contains the same columns as the input table. - - - -## Examples - The following console application example creates a , fills the with data, creates a filtered view based on the original data, and finally, creates a that contains the filtered rows. - + , its name is the same as the name of the source `DataTable`. Because this method does not let you specify a subset of available columns, the output table contains the same columns as the input table. + + + +## Examples + The following console application example creates a , fills the with data, creates a filtered view based on the original data, and finally, creates a that contains the filtered rows. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataView.ToTableFiltered/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/ToTable/source.vb" id="Snippet1"::: - - The example displays the following text in the console window: - -``` -Original table name: NewTable -Current Values in Table -1, Fruit, Apple, 14 -2, Fruit, Orange, 27 -3, Bread, Muffin, 23 -4, Fish, Salmon, 12 - -Current Values in View -2, Fruit, Orange, 27 -3, Bread, Muffin, 23 - -Table created from filtered DataView -2, Fruit, Orange, 27 -3, Bread, Muffin, 23 - -New table name: NewTable -``` - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/ToTable/source.vb" id="Snippet1"::: + + The example displays the following text in the console window: + +``` +Original table name: NewTable +Current Values in Table +1, Fruit, Apple, 14 +2, Fruit, Orange, 27 +3, Bread, Muffin, 23 +4, Fish, Salmon, 12 + +Current Values in View +2, Fruit, Orange, 27 +3, Bread, Muffin, 23 + +Table created from filtered DataView +2, Fruit, Orange, 27 +3, Bread, Muffin, 23 + +New table name: NewTable +``` + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -4314,40 +4314,40 @@ New table name: NewTable Creates and returns a new based on rows in an existing . A new instance that contains the requested rows and columns. - , fills the `DataTable` with data, creates a filtered view based on the original data, and finally creates a `DataTable` with a new name that contains the filtered rows. - + , fills the `DataTable` with data, creates a filtered view based on the original data, and finally creates a `DataTable` with a new name that contains the filtered rows. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataView.ToTableNewName/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/ToTable/source1.vb" id="Snippet1"::: - - The example displays the following text in the console window: - -``` -Original table name: NewTable -Current Values in Table -1, Fruit, Apple, 14 -2, Fruit, Orange, 27 -3, Bread, Muffin, 23 -4, Fish, Salmon, 12 - -Current Values in View -2, Fruit, Orange, 27 -3, Bread, Muffin, 23 - -Table created from filtered DataView -2, Fruit, Orange, 27 -3, Bread, Muffin, 23 - -New table name: FilteredTable -``` - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/ToTable/source1.vb" id="Snippet1"::: + + The example displays the following text in the console window: + +``` +Original table name: NewTable +Current Values in Table +1, Fruit, Apple, 14 +2, Fruit, Orange, 27 +3, Bread, Muffin, 23 +4, Fish, Salmon, 12 + +Current Values in View +2, Fruit, Orange, 27 +3, Bread, Muffin, 23 + +Table created from filtered DataView +2, Fruit, Orange, 27 +3, Bread, Muffin, 23 + +New table name: FilteredTable +``` + ]]> DataSets, DataTables, and DataViews (ADO.NET) @@ -4405,49 +4405,49 @@ New table name: FilteredTable Creates and returns a new based on rows in an existing . A new instance that contains the requested rows and columns. - , its name is the same as the name of the source . - - - -## Examples - The following console application example creates a , fills the with data, sorts the , and finally creates a with just two columns, limited to rows in which all values are unique. - + , its name is the same as the name of the source . + + + +## Examples + The following console application example creates a , fills the with data, sorts the , and finally creates a with just two columns, limited to rows in which all values are unique. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataView.ToTableUniqueValues/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/ToTable/source2.vb" id="Snippet1"::: - - The example displays the following output in the console window: - -``` -Original table name: NewTable -Current Values in Table -1, Fruit, Apple, 14 -2, Fruit, Orange, 27 -3, Bread, Muffin, 23 -4, Fish, Salmon, 12 -5, Fish, Salmon, 15 -6, Bread, Croissant, 23 - -Current Values in View -3, Bread, Muffin, 23 -6, Bread, Croissant, 23 -4, Fish, Salmon, 12 -5, Fish, Salmon, 15 -1, Fruit, Apple, 14 -2, Fruit, Orange, 27 - -Table created from sorted DataView -Bread, 23 -Fish, 12 -Fish, 15 -Fruit, 14 -Fruit, 27 - -New table name: NewTable -``` - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/ToTable/source2.vb" id="Snippet1"::: + + The example displays the following output in the console window: + +``` +Original table name: NewTable +Current Values in Table +1, Fruit, Apple, 14 +2, Fruit, Orange, 27 +3, Bread, Muffin, 23 +4, Fish, Salmon, 12 +5, Fish, Salmon, 15 +6, Bread, Croissant, 23 + +Current Values in View +3, Bread, Muffin, 23 +6, Bread, Croissant, 23 +4, Fish, Salmon, 12 +5, Fish, Salmon, 15 +1, Fruit, Apple, 14 +2, Fruit, Orange, 27 + +Table created from sorted DataView +Bread, 23 +Fish, 12 +Fish, 15 +Fruit, 14 +Fruit, 27 + +New table name: NewTable +``` + ]]> @@ -4514,49 +4514,49 @@ New table name: NewTable Creates and returns a new based on rows in an existing . A new instance that contains the requested rows and columns. - method if you have to retrieve distinct values in a subset of available columns, specifying a new name for the returned . If you do not need distinct rows or a subset of columns, see . - - - -## Examples - The following console application example creates a , fills the with data, sorts the , and finally creates a with a new name that contains just two columns, limited to rows in which all values are unique. - + method if you have to retrieve distinct values in a subset of available columns, specifying a new name for the returned . If you do not need distinct rows or a subset of columns, see . + + + +## Examples + The following console application example creates a , fills the with data, sorts the , and finally creates a with a new name that contains just two columns, limited to rows in which all values are unique. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/DataWorks DataView.ToTableUniqueValuesName/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/ToTable/source3.vb" id="Snippet1"::: - - The example displays the following output in the console window: - -``` -Original table name: NewTable -Current Values in Table -1, Fruit, Apple, 14 -2, Fruit, Orange, 27 -3, Bread, Muffin, 23 -4, Fish, Salmon, 12 -5, Fish, Salmon, 15 -6, Bread, Croissant, 23 - -Current Values in View -3, Bread, Muffin, 23 -6, Bread, Croissant, 23 -4, Fish, Salmon, 12 -5, Fish, Salmon, 15 -1, Fruit, Apple, 14 -2, Fruit, Orange, 27 - -Table created from sorted DataView -Bread, 23 -Fish, 12 -Fish, 15 -Fruit, 14 -Fruit, 27 - -New table name: UniqueData -``` - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/ToTable/source3.vb" id="Snippet1"::: + + The example displays the following output in the console window: + +``` +Original table name: NewTable +Current Values in Table +1, Fruit, Apple, 14 +2, Fruit, Orange, 27 +3, Bread, Muffin, 23 +4, Fish, Salmon, 12 +5, Fish, Salmon, 15 +6, Bread, Croissant, 23 + +Current Values in View +3, Bread, Muffin, 23 +6, Bread, Croissant, 23 +4, Fish, Salmon, 12 +5, Fish, Salmon, 15 +1, Fruit, Apple, 14 +2, Fruit, Orange, 27 + +Table created from sorted DataView +Bread, 23 +Fish, 12 +Fish, 15 +Fruit, 14 +Fruit, 27 + +New table name: UniqueData +``` + ]]> DataSets, DataTables, and DataViews (ADO.NET) diff --git a/xml/System.Data/DataViewRowState.xml b/xml/System.Data/DataViewRowState.xml index a0a02a4f170..052a280bab1 100644 --- a/xml/System.Data/DataViewRowState.xml +++ b/xml/System.Data/DataViewRowState.xml @@ -63,25 +63,25 @@ Describes the version of data in a . - values are used either to retrieve a particular version of data from a , or to determine what versions exist. - - Set the property of the to specify which version or versions of data you want to view. - - You can use the Boolean operator Or with the values to get more than one version. - - The uses in the method. - - - -## Examples - In the following example is created with a single column. The data is changed, and the of the is set to display different row sets, depending on the . - + values are used either to retrieve a particular version of data from a , or to determine what versions exist. + + Set the property of the to specify which version or versions of data you want to view. + + You can use the Boolean operator Or with the values to get more than one version. + + The uses in the method. + + + +## Examples + In the following example is created with a single column. The data is changed, and the of the is set to display different row sets, depending on the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataView.RowStateFilter Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/RowStateFilter/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/DataView/RowStateFilter/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/DataViewSetting.xml b/xml/System.Data/DataViewSetting.xml index 7bc84ce0983..7f36cf065be 100644 --- a/xml/System.Data/DataViewSetting.xml +++ b/xml/System.Data/DataViewSetting.xml @@ -248,11 +248,11 @@ Gets or sets a value indicating whether to display Current, Deleted, Modified Current, ModifiedOriginal, New, Original, Unchanged, or no rows in the . A value that indicates which rows to display. - is `DataViewRowState.CurrentRows`. - + is `DataViewRowState.CurrentRows`. + ]]> @@ -297,11 +297,11 @@ Gets or sets a value indicating the sort to apply in the . The sort to apply in the . - can have two defaults based on the value of property. If is null or empty (that is, the value is not explicitly specified), the in the is sorted on the position or ordinal of in the collection. The default, an empty string, causes a in to be sorted on the position or ordinal of in the collection. - + can have two defaults based on the value of property. If is null or empty (that is, the value is not explicitly specified), the in the is sorted on the position or ordinal of in the collection. The default, an empty string, causes a in to be sorted on the position or ordinal of in the collection. + ]]> diff --git a/xml/System.Data/DataViewSettingCollection.xml b/xml/System.Data/DataViewSettingCollection.xml index ab24781ce83..16fb9a2794f 100644 --- a/xml/System.Data/DataViewSettingCollection.xml +++ b/xml/System.Data/DataViewSettingCollection.xml @@ -76,11 +76,11 @@ Contains a read-only collection of objects for each in a . - from the collection, but can change the properties of the corresponding to a particular . Adding or removing a from the DataSet adds or removes the corresponding from the collection. - + from the collection, but can change the properties of the corresponding to a particular . Adding or removing a from the DataSet adds or removes the corresponding from the collection. + ]]> This type is safe for multithreaded read operations. You must synchronize any write operations. @@ -241,11 +241,11 @@ Gets the number of objects in the . The number of objects in the collection. - objects is the same as the number of objects in the . - + objects is the same as the number of objects in the . + ]]> @@ -393,13 +393,13 @@ Gets a value that indicates whether access to the is synchronized (thread-safe). This property is always , unless overridden by a derived class. - interface. - - Derived classes can provide a synchronized version of the using the property. - + interface. + + Derived classes can provide a synchronized version of the using the property. + ]]> @@ -615,13 +615,13 @@ Gets an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - using the property. - - Program code must always perform synchronized operations on the of the , not directly on the . This guarantees the correct operation of collections that are derived from other objects. Specifically, it maintains the correct synchronization with other threads that might be simultaneously modifying the . - + using the property. + + Program code must always perform synchronized operations on the of the , not directly on the . This guarantees the correct operation of collections that are derived from other objects. Specifically, it maintains the correct synchronization with other threads that might be simultaneously modifying the . + ]]> diff --git a/xml/System.Data/DeletedRowInaccessibleException.xml b/xml/System.Data/DeletedRowInaccessibleException.xml index 5bd0a05b668..bcbb0b0307e 100644 --- a/xml/System.Data/DeletedRowInaccessibleException.xml +++ b/xml/System.Data/DeletedRowInaccessibleException.xml @@ -57,21 +57,21 @@ Represents the exception that is thrown when an action is tried on a that has been deleted. - , use the method of a class. As soon as you have deleted a row, any attempts to modify it will generate the . - - The is thrown when you use one of the following properties or methods that try to get or set the value of a deleted : - -- property - -- property - -- method - - Use the of a class to determine whether a row has been deleted. If it has been deleted, you can use the field to retrieve it because deleted rows have no values available for the state. - + , use the method of a class. As soon as you have deleted a row, any attempts to modify it will generate the . + + The is thrown when you use one of the following properties or methods that try to get or set the value of a deleted : + +- property + +- property + +- method + + Use the of a class to determine whether a row has been deleted. If it has been deleted, you can use the field to retrieve it because deleted rows have no values available for the state. + ]]> @@ -129,11 +129,11 @@ Initializes a new instance of the class. - of a class to determine whether a row has been deleted. - + of a class to determine whether a row has been deleted. + ]]> @@ -185,11 +185,11 @@ The string to display when the exception is thrown. Initializes a new instance of the class with the specified string. - of a class to determine whether a row has been deleted. - + of a class to determine whether a row has been deleted. + ]]> @@ -298,11 +298,11 @@ The exception that is the cause of the current exception, or a null reference ( in Visual Basic) if no inner exception is specified. 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. - of a class to determine whether a row has been deleted. - + of a class to determine whether a row has been deleted. + ]]> diff --git a/xml/System.Data/EntityKey.xml b/xml/System.Data/EntityKey.xml index 20ce9913d4a..c91d2f4f727 100644 --- a/xml/System.Data/EntityKey.xml +++ b/xml/System.Data/EntityKey.xml @@ -478,7 +478,7 @@ property to `true`. When you call the method, the Entity Framework assigns a permanent key and sets the property to `false`. + When a new entity is created, the Entity Framework defines temporary key and sets the property to `true`. When you call the method, the Entity Framework assigns a permanent key and sets the property to `false`. > [!NOTE] > Temporary keys are constructed automatically by the framework; they cannot be constructed directly by a user. diff --git a/xml/System.Data/EntityState.xml b/xml/System.Data/EntityState.xml index a95ac2c008b..614d922e37a 100644 --- a/xml/System.Data/EntityState.xml +++ b/xml/System.Data/EntityState.xml @@ -26,13 +26,13 @@ The state of an entity object. - objects store information. The `SaveChanges` methods of the process entities that are attached to the context and update the data source depending on the of each object. For more information, see [Creating, Adding, Modifying, and Deleting Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738695(v=vs.100)). - - The state of objects inside an object context is managed by the . To find out the state of an object, call one of the following methods: , , or . The property of the defines the state of the object. - + objects store information. The `SaveChanges` methods of the process entities that are attached to the context and update the data source depending on the of each object. For more information, see [Creating, Adding, Modifying, and Deleting Objects](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/bb738695(v=vs.100)). + + The state of objects inside an object context is managed by the . To find out the state of an object, call one of the following methods: , , or . The property of the defines the state of the object. + ]]> diff --git a/xml/System.Data/ForeignKeyConstraint.xml b/xml/System.Data/ForeignKeyConstraint.xml index 2a431a72485..6ff8070cc1e 100644 --- a/xml/System.Data/ForeignKeyConstraint.xml +++ b/xml/System.Data/ForeignKeyConstraint.xml @@ -86,9 +86,9 @@ - An exception can be generated. - objects are contained in the of a , which is accessed through the property. + objects are contained in the of a , which is accessed through the property. - Constraints are not enforced unless the property is set to `true`. + Constraints are not enforced unless the property is set to `true`. The is enforced whenever a object's method is invoked. @@ -657,7 +657,7 @@ objects through the property. + The following example returns an array of objects through the property. :::code language="vb" source="~/snippets/visualbasic/System.Data/ForeignKeyConstraint/Columns/source.vb" id="Snippet1"::: @@ -724,7 +724,7 @@ ## Remarks When a row is deleted from a parent table, the determines what will happen in the columns of the child table (or tables). If the rule is set to `Cascade`, child rows will be deleted. - If set to `SetNull`, a `DBNull` will be placed in the appropriate columns of the affected rows. Depending on your data source, a null value may or may not be permitted in a column. For example, SQL Server allows multiple null values to be found in a primary key column, even if they are not unique. In a , however, if a object's property is set to `true`, multiple null values are not allowed in primary key columns. + If set to `SetNull`, a `DBNull` will be placed in the appropriate columns of the affected rows. Depending on your data source, a null value may or may not be permitted in a column. For example, SQL Server allows multiple null values to be found in a primary key column, even if they are not unique. In a , however, if a object's property is set to `true`, multiple null values are not allowed in primary key columns. If set to `SetDefault`, the default value for the column is assigned. diff --git a/xml/System.Data/IColumnMapping.xml b/xml/System.Data/IColumnMapping.xml index 500c300ba31..685fd0070cc 100644 --- a/xml/System.Data/IColumnMapping.xml +++ b/xml/System.Data/IColumnMapping.xml @@ -44,40 +44,40 @@ Associates a data source column with a column, and is implemented by the class, which is used in common by .NET data providers. - interface enables an inheriting class to implement a Column Mapping class, which associates a data source column with a column. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). - - An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - - Classes that inherit must implement all inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the method. - - - -## Examples - The following example creates an instance of the derived class, , and adds it to a collection. It then tells the user that the mapping was added to the collection and shows the parent for the mapping. - + interface enables an inheriting class to implement a Column Mapping class, which associates a data source column with a column. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). + + An application does not create an instance of the interface directly, but creates an instance of a class that inherits . + + Classes that inherit must implement all inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the method. + + + +## Examples + The following example creates an instance of the derived class, , and adds it to a collection. It then tells the user that the mapping was added to the collection and shows the parent for the mapping. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMapping Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/Overview/source.vb" id="Snippet1"::: + ]]> - When you inherit from the interface, you should implement the following constructors: - - Item - - Description - - ColumnMapping() - - Initializes a new instance of the ColumnMapping class. - - ColumnMapping(string sourceColumn, string dataSetColumn) - - Initializes a new instance of the ColumnMapping class with a source with the specified source column name and column name. - + When you inherit from the interface, you should implement the following constructors: + + Item + + Description + + ColumnMapping() + + Initializes a new instance of the ColumnMapping class. + + ColumnMapping(string sourceColumn, string dataSetColumn) + + Initializes a new instance of the ColumnMapping class with a source with the specified source column name and column name. + @@ -122,14 +122,14 @@ Gets or sets the name of the column within the to map to. The name of the column within the to map to. The name is not case sensitive. - , and sets its properties. - + , and sets its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMapping.DataSetColumn Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/DataSetColumn/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/DataSetColumn/source.vb" id="Snippet1"::: + ]]> @@ -174,14 +174,14 @@ Gets or sets the name of the column within the data source to map from. The name is case-sensitive. The case-sensitive name of the column in the data source. - , and sets its properties. - + , and sets its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataColumnMapping.DataSetColumn Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/DataSetColumn/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IColumnMapping/DataSetColumn/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/IDataAdapter.xml b/xml/System.Data/IDataAdapter.xml index 9aaa52f668d..a2fb197cf2b 100644 --- a/xml/System.Data/IDataAdapter.xml +++ b/xml/System.Data/IDataAdapter.xml @@ -141,9 +141,9 @@ retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. + retrieves rows from the data source using the SELECT statement specified by an associated property. The connection object associated with the SELECT statement must be valid, but it does not need to be open. If the connection is closed before is called, it is opened to retrieve data, then closed. If the connection is open before is called, it remains open. - The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation usually creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. + The operation then adds the rows to destination objects in the , creating the objects if they do not already exist. When creating objects, the operation usually creates only column name metadata. However, if the property is set to `AddWithKey`, appropriate primary keys and constraints are also created. If the `SelectCommand` returns the results of an OUTER JOIN, the `DataAdapter` does not set a value for the resulting . You must explicitly define the primary key to ensure that duplicate rows are resolved correctly. For more information, see [Defining Primary Keys](/dotnet/framework/data/adonet/dataset-datatable-dataview/defining-primary-keys). @@ -234,7 +234,7 @@ - If one or more primary key columns are returned by the , they are used as the primary key columns for the . -- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if all the unique columns are non-nullable. If any of the columns are nullable, a is added to the , but the property is not set. +- If no primary key columns are returned but unique columns are, the unique columns are used as the primary key if all the unique columns are non-nullable. If any of the columns are nullable, a is added to the , but the property is not set. - If both primary key columns and unique columns are returned, the primary key columns are used as the primary key columns for the . @@ -366,7 +366,7 @@ private static void GetParameters(string connectionString) property provides the primary mapping between the returned records and the . + The property provides the primary mapping between the returned records and the . ]]> @@ -520,13 +520,13 @@ private static void GetParameters(string connectionString) method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, because of the ordering of the rows in the . + When an application calls the method, the examines the property, and executes the required INSERT, UPDATE, or DELETE statements iteratively for each row, based on the order of the indexes configured in the . For example, might execute a DELETE statement, followed by an INSERT statement, and then another DELETE statement, because of the ordering of the rows in the . Be aware that these statements are not performed as a batch process; each row is updated individually. An application can call the method if you must control the sequence of statement types (for example, INSERTs before UPDATEs). For more information, see [Updating Data Sources with DataAdapters](/dotnet/framework/data/adonet/updating-data-sources-with-dataadapters). If INSERT, UPDATE, or DELETE statements have not been specified, the method generates an exception. However, you can create a or object to automatically generate SQL statements for single-table updates if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional SQL statements that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - The method retrieves rows from the table listed in the first mapping before performing an update. The then updates the row using the value of the property. Any additional rows returned are ignored. + The method retrieves rows from the table listed in the first mapping before performing an update. The then updates the row using the value of the property. Any additional rows returned are ignored. After any data is loaded back into the , the event is raised, allowing the user to inspect the reconciled row and any output parameters returned by the command. After a row updates successfully, the changes to that row are accepted. @@ -561,7 +561,7 @@ private static void GetParameters(string connectionString) The `SourceVersion` property of a .NET Framework data provider's `Parameter` class determines whether to use the `Original`, `Current`, or `Proposed` version of the column value. This capability is frequently used to include original values in the WHERE clause of an UPDATE statement to check for optimistic concurrency violations. > [!NOTE] -> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . +> If an error occurs while updating a row, an exception is thrown and execution of the update is discontinued. To continue the update operation without generating exceptions when an error is encountered, set the property to `true` before calling . You may also respond to errors on a per-row basis within the `RowUpdated` event of a DataAdapter. To continue the update operation without generating an exception within the `RowUpdated` event, set the property of the to . diff --git a/xml/System.Data/IDataParameter.xml b/xml/System.Data/IDataParameter.xml index 3f6cf6810e7..78cb8f05a8c 100644 --- a/xml/System.Data/IDataParameter.xml +++ b/xml/System.Data/IDataParameter.xml @@ -45,58 +45,58 @@ Represents a parameter to a Command object, and optionally, its mapping to columns; and is implemented by .NET data providers that access data sources. - interface allows an inheriting class to implement a Parameter class, which represents a parameter to a Command object. For more information about Parameter classes, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). - - An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the property. - - - -## Examples - The following example creates multiple instances of the derived class, , through the collection within the . These parameters are used to select data from the data source and place the data in the . This example assumes that a and a have already been created with the appropriate schema, commands, and connection. - + interface allows an inheriting class to implement a Parameter class, which represents a parameter to a Command object. For more information about Parameter classes, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). + + An application does not create an instance of the interface directly, but creates an instance of a class that inherits . + + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the property. + + + +## Examples + The following example creates multiple instances of the derived class, , through the collection within the . These parameters are used to select data from the data source and place the data in the . This example assumes that a and a have already been created with the appropriate schema, commands, and connection. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameter Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/Overview/source.vb" id="Snippet1"::: + ]]> - To promote consistency among .NET Framework data providers, name the inheriting class in the form Parameter where is the uniform prefix given to all classes in a specific .NET Framework data provider namespace. For example, is the prefix of the class in the namespace. - - When you inherit from the interface, you should implement the following constructors: - - Item - - Description - - PrvParameter() - - Initializes a new instance of the Parameter class. - - PrvParameter(string name, PrvDbType dataType) - - Initializes a new instance of the Parameter class with the parameter name and data type. - - PrvParameter(string name, object value) - - Initializes a new instance of the Parameter class with the parameter name and an object that is the value of the Parameter. - - PrvParameter(string name, PrvDbType dataType, int size) - - Initializes a new instance of the Parameter class with the parameter name, data type, and width. - - PrvParameter(string name, PrvDbType dataType, int size, string srcColumn) - - Initializes a new instance of the DbParameter class with the parameter name, data type, width, and source column name. - - PrvParameter(string parameterName, PrvDbType dbType, int size, ParameterDirection direction, Boolean isNullable, Byte precision, Byte scale, string srcColumn, DataRowVersion srcVersion, object value) - - Initializes a new instance of the class with the parameter name, data type, width, source column name, parameter direction, numeric precision, and other properties. - + To promote consistency among .NET Framework data providers, name the inheriting class in the form Parameter where is the uniform prefix given to all classes in a specific .NET Framework data provider namespace. For example, is the prefix of the class in the namespace. + + When you inherit from the interface, you should implement the following constructors: + + Item + + Description + + PrvParameter() + + Initializes a new instance of the Parameter class. + + PrvParameter(string name, PrvDbType dataType) + + Initializes a new instance of the Parameter class with the parameter name and data type. + + PrvParameter(string name, object value) + + Initializes a new instance of the Parameter class with the parameter name and an object that is the value of the Parameter. + + PrvParameter(string name, PrvDbType dataType, int size) + + Initializes a new instance of the Parameter class with the parameter name, data type, and width. + + PrvParameter(string name, PrvDbType dataType, int size, string srcColumn) + + Initializes a new instance of the DbParameter class with the parameter name, data type, width, and source column name. + + PrvParameter(string parameterName, PrvDbType dbType, int size, ParameterDirection direction, Boolean isNullable, Byte precision, Byte scale, string srcColumn, DataRowVersion srcVersion, object value) + + Initializes a new instance of the class with the parameter name, data type, width, source column name, parameter direction, numeric precision, and other properties. + @@ -142,13 +142,13 @@ Gets or sets the of the parameter. One of the values. The default is . - are linked. Therefore, setting the changes the PrvDbType to a supporting PrvDbType. - - For a list of the supported data types, see the appropriate .NET Framework data provider PrvDbType member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). - + are linked. Therefore, setting the changes the PrvDbType to a supporting PrvDbType. + + For a list of the supported data types, see the appropriate .NET Framework data provider PrvDbType member. For more information, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). + ]]> The property was not set to a valid . @@ -195,21 +195,21 @@ Gets or sets a value indicating whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter. One of the values. The default is . - is output, and execution of the associated does not return a value, the contains a null value. - - After the last row from the last resultset is read, `Output`, `InputOut`, and `ReturnValue` parameters are updated. - - - -## Examples - The following example creates an instance of the implementing class, , and sets some of its properties. - + is output, and execution of the associated does not return a value, the contains a null value. + + After the last row from the last resultset is read, `Output`, `InputOut`, and `ReturnValue` parameters are updated. + + + +## Examples + The following example creates an instance of the implementing class, , and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameter.Direction Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/Direction/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/Direction/source.vb" id="Snippet1"::: + ]]> The property was not set to one of the valid values. @@ -257,19 +257,19 @@ if null values are accepted; otherwise, . The default is . - class. - - - -## Examples - The following example creates an instance of the implementing class, , and sets some of its properties. - + class. + + + +## Examples + The following example creates an instance of the implementing class, , and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameter.IsNullable Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/IsNullable/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/IsNullable/source.vb" id="Snippet1"::: + ]]> @@ -315,20 +315,20 @@ Gets or sets the name of the . The name of the . The default is an empty string. - is specified in the form \@*paramname*. You must set before executing a command that relies on parameters. - - - -## Examples - The following example creates an instance of the implementing class, , and sets some of its properties. - + is specified in the form \@*paramname*. You must set before executing a command that relies on parameters. + + + +## Examples + The following example creates an instance of the implementing class, , and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameter.ParameterName Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/ParameterName/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/ParameterName/source.vb" id="Snippet1"::: + ]]> @@ -374,19 +374,19 @@ Gets or sets the name of the source column that is mapped to the and used for loading or returning the . The name of the source column that is mapped to the . The default is an empty string. - and the may be bidirectional depending on the value of the property. - - - -## Examples - The following example creates an instance of the implementing class, , and sets some of its properties. - + and the may be bidirectional depending on the value of the property. + + + +## Examples + The following example creates an instance of the implementing class, , and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameter.SourceColumn Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/SourceColumn/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/SourceColumn/source.vb" id="Snippet1"::: + ]]> @@ -432,19 +432,19 @@ Gets or sets the to use when loading . One of the values. The default is . - during the to determine whether the original or current value is used for a parameter value. This allows primary keys to be updated. This property is ignored by the and . This property is set to the version of the used by the property, or the method of the object. - - - -## Examples - The following example creates an instance of the implementing class, , and sets some of its properties. - + during the to determine whether the original or current value is used for a parameter value. This allows primary keys to be updated. This property is ignored by the and . This property is set to the version of the used by the property, or the method of the object. + + + +## Examples + The following example creates an instance of the implementing class, , and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameter.SourceVersion Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/SourceVersion/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/SourceVersion/source.vb" id="Snippet1"::: + ]]> The property was not set one of the values. @@ -498,25 +498,25 @@ Gets or sets the value of the parameter. An that is the value of the parameter. The default value is null. - that is sent to the server. For output and return value parameters, the value is set on completion of the and after the is closed. - - When sending a null parameter value to the server, the user must specify `DBNull`, not null. The null value in the system is an empty object that has no value. `DBNull` is used to represent null values. - - If the application specifies the database type, the bound value is converted to that type when the provider sends the data to the server. The provider attempts to convert any type of value if it supports the interface. Conversion errors may result if the specified type is not compatible with the value. - - The property is overwritten by . - - - -## Examples - The following example creates an instance of the implementing class, , and sets some of its properties. - + that is sent to the server. For output and return value parameters, the value is set on completion of the and after the is closed. + + When sending a null parameter value to the server, the user must specify `DBNull`, not null. The null value in the system is an empty object that has no value. `DBNull` is used to represent null values. + + If the application specifies the database type, the bound value is converted to that type when the provider sends the data to the server. The provider attempts to convert any type of value if it supports the interface. Conversion errors may result if the specified type is not compatible with the value. + + The property is overwritten by . + + + +## Examples + The following example creates an instance of the implementing class, , and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlParameter.Value Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/Value/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataParameter/Value/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/IDataReader.xml b/xml/System.Data/IDataReader.xml index 30dd0a2daa3..0ff5dad117f 100644 --- a/xml/System.Data/IDataReader.xml +++ b/xml/System.Data/IDataReader.xml @@ -53,30 +53,30 @@ Provides a means of reading one or more forward-only streams of result sets obtained by executing a command at a data source, and is implemented by .NET data providers that access relational databases. - and interfaces allow an inheriting class to implement a `DataReader` class, which provides a means of reading one or more forward-only streams of result sets. For more information about `DataReader` classes, see [Retrieving Data Using a DataReader](/dotnet/framework/data/adonet/retrieving-data-using-a-datareader). - - An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. - - Changes made to a result set by another process or thread while data is being read may be visible to the user of a class that implements an `IDataReader`. However, the precise behavior is both provider and timing dependent. - - - -## Examples - The following example creates instances of the derived classes, , , and . The example reads through the data, writing it out to the console. Finally, the example closes the , then the . - + and interfaces allow an inheriting class to implement a `DataReader` class, which provides a means of reading one or more forward-only streams of result sets. For more information about `DataReader` classes, see [Retrieving Data Using a DataReader](/dotnet/framework/data/adonet/retrieving-data-using-a-datareader). + + An application does not create an instance of the interface directly, but creates an instance of a class that inherits . + + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. + + Changes made to a result set by another process or thread while data is being read may be visible to the user of a class that implements an `IDataReader`. However, the precise behavior is both provider and timing dependent. + + + +## Examples + The following example creates instances of the derived classes, , , and . The example reads through the data, writing it out to the console. Finally, the example closes the , then the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlDataReader.Read Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataReader/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataReader/Overview/source.vb" id="Snippet1"::: + ]]> - To promote consistency among .NET Framework data providers, name the inheriting class in the form Command where is the uniform prefix given to all classes in a specific .NET Framework data provider namespace. For example, is the prefix of the class in the namespace. - + To promote consistency among .NET Framework data providers, name the inheriting class in the form Command where is the uniform prefix given to all classes in a specific .NET Framework data provider namespace. For example, is the prefix of the class in the namespace. + Users do not create an instance of a class directly. Instead, they obtain the instance through the method of the object. Therefore, you should mark constructors as internal. @@ -122,11 +122,11 @@ Closes the Object. - method when you are through using the to use the associated for any other purpose. - + method when you are through using the to use the associated for any other purpose. + ]]> @@ -172,11 +172,11 @@ Gets a value indicating the depth of nesting for the current row. The level of nesting. - @@ -226,18 +226,18 @@ Returns if the executed command returned no resultset, or after returns . A that describes the column metadata. - method for the .NET Framework Data Provider for OLE DB maps to the OLE DB IColumnsRowset::GetColumnsRowset method, while implementations for other .NET Framework data providers do not use an OLE DB provider layer. The order in which returns metadata about each column in a table, and the DataReader columns that are returned, vary depending on which data provider you use. The following table lists data providers and members that implement . - -|Data Provider|Member| -|-------------------|------------| -|.NET Data Provider for ODBC|.| -|.NET Data Provider for OLE DB|.| -|.NET Data Provider for Oracle|.| -|.NET Data Provider for SQL Server|.| - + method for the .NET Framework Data Provider for OLE DB maps to the OLE DB IColumnsRowset::GetColumnsRowset method, while implementations for other .NET Framework data providers do not use an OLE DB provider layer. The order in which returns metadata about each column in a table, and the DataReader columns that are returned, vary depending on which data provider you use. The following table lists data providers and members that implement . + +|Data Provider|Member| +|-------------------|------------| +|.NET Data Provider for ODBC|.| +|.NET Data Provider for OLE DB|.| +|.NET Data Provider for Oracle|.| +|.NET Data Provider for SQL Server|.| + ]]> The is closed. @@ -285,11 +285,11 @@ Returns if the executed command returned no resultset, o if the data reader is closed; otherwise, . - and are the only properties that you can call after the is closed. - + and are the only properties that you can call after the is closed. + ]]> @@ -337,16 +337,16 @@ Returns if the executed command returned no resultset, o if there are more rows; otherwise, . - @@ -394,21 +394,21 @@ Returns if the executed command returned no resultset, o if there are more rows; otherwise, . - is prior to the first record. Therefore you must call to begin accessing any data. - - While the data reader is in use, the associated connection is busy serving the . This is the case until is called. - - - -## Examples - The following example creates instances of three derived classes , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , then the . - + is prior to the first record. Therefore you must call to begin accessing any data. + + While the data reader is in use, the associated connection is busy serving the . This is the case until is called. + + + +## Examples + The following example creates instances of three derived classes , an , and an . The example reads through the data, writing it out to the console. Finally, the example closes the , then the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDataReader.Read Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataReader/Read/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataReader/Read/source.vb" id="Snippet1"::: + ]]> @@ -454,13 +454,13 @@ Returns if the executed command returned no resultset, o Gets the number of rows changed, inserted, or deleted by execution of the SQL statement. The number of rows changed, inserted, or deleted; 0 if no rows were affected or the statement failed; and -1 for SELECT statements. - property is not set until all rows are read and you close the . - - and are the only properties that you can call after the is closed. - + property is not set until all rows are read and you close the . + + and are the only properties that you can call after the is closed. + ]]> diff --git a/xml/System.Data/IDbCommand.xml b/xml/System.Data/IDbCommand.xml index fb4ac4b4a65..c2b4f23de59 100644 --- a/xml/System.Data/IDbCommand.xml +++ b/xml/System.Data/IDbCommand.xml @@ -49,50 +49,50 @@ Represents an SQL statement that is executed while connected to a data source, and is implemented by .NET data providers that access relational databases. - interface enables an inheriting class to implement a Command class, which represents an SQL statement that is executed at a data source. For more information about Command classes, see [Executing a Command](/dotnet/framework/data/adonet/executing-a-command). - - An application does not create an instance of the interface directly, but creates an instance of a class that implements the interface. - - Classes that implement must implement all its members, and typically define additional members to add provider-specific functionality. For example, the interface defines the method. In turn, the class inherits this method, and also defines the method. - - - -## Examples - The following example creates instances of the derived classes, , , and . The example reads through the data, writing it to the console. Finally, the example closes the , then the . - + interface enables an inheriting class to implement a Command class, which represents an SQL statement that is executed at a data source. For more information about Command classes, see [Executing a Command](/dotnet/framework/data/adonet/executing-a-command). + + An application does not create an instance of the interface directly, but creates an instance of a class that implements the interface. + + Classes that implement must implement all its members, and typically define additional members to add provider-specific functionality. For example, the interface defines the method. In turn, the class inherits this method, and also defines the method. + + + +## Examples + The following example creates instances of the derived classes, , , and . The example reads through the data, writing it to the console. Finally, the example closes the , then the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/Overview/source.vb" id="Snippet1"::: + ]]> - To promote consistency among .NET Framework data providers, name the inheriting class in the form where is the uniform prefix given to all classes in a specific .NET Framework data provider namespace. For example, is the prefix of the class in the namespace. - - When you inherit from the interface, you should implement the following constructors: - - Item - - Description - - PrvCommand() - - Initializes a new instance of the PrvCommand class. - - PrvCommand(string cmdText) - - Initializes a new instance of the PrvCommand class with the text of the query. - - PrvCommand(string cmdText, PrvConnection connection) - - Initializes a new instance of the PrvCommand class with the text of the query and a PrvConnection. - - PrvCommand(string cmdText, PrvConnection connection, PrvTransaction transaction) - - Initializes a new instance of the PrvCommand class with the text of the query, a PrvConnection, and the PrvTransaction. - + To promote consistency among .NET Framework data providers, name the inheriting class in the form where is the uniform prefix given to all classes in a specific .NET Framework data provider namespace. For example, is the prefix of the class in the namespace. + + When you inherit from the interface, you should implement the following constructors: + + Item + + Description + + PrvCommand() + + Initializes a new instance of the PrvCommand class. + + PrvCommand(string cmdText) + + Initializes a new instance of the PrvCommand class with the text of the query. + + PrvCommand(string cmdText, PrvConnection connection) + + Initializes a new instance of the PrvCommand class with the text of the query and a PrvConnection. + + PrvCommand(string cmdText, PrvConnection connection, PrvTransaction transaction) + + Initializes a new instance of the PrvCommand class with the text of the query, a PrvConnection, and the PrvTransaction. + @@ -142,11 +142,11 @@ Attempts to cancels the execution of an . - @@ -192,19 +192,19 @@ Gets or sets the text command to run against the data source. The text command to execute. The default value is an empty string (""). - property is set to `StoredProcedure`, set the property to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command will call this stored procedure when you call one of the Execute methods. - - - -## Examples - The following example creates an instance of a derived class, and sets some of its properties. - + property is set to `StoredProcedure`, set the property to the name of the stored procedure. The user may be required to use escape character syntax if the stored procedure name contains any special characters. The command will call this stored procedure when you call one of the Execute methods. + + + +## Examples + The following example creates an instance of a derived class, and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDbCommand.CommandText Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/CommandText/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/CommandText/source.vb" id="Snippet1"::: + ]]> @@ -252,14 +252,14 @@ Gets or sets the wait time (in seconds) before terminating the attempt to execute a command and generating an error. The time (in seconds) to wait for the command to execute. The default value is 30 seconds. - and sets some of its properties. - + and sets some of its properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDbCommand.CommandTimeout Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/CommandTimeout/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/CommandTimeout/source.vb" id="Snippet1"::: + ]]> The property value assigned is less than 0. @@ -309,11 +309,11 @@ Indicates or specifies how the property is interpreted. One of the values. The default is . - property to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods. - + property to `StoredProcedure`, you should set the property to the name of the stored procedure. The command executes this stored procedure when you call one of the Execute methods. + ]]> @@ -410,11 +410,11 @@ Creates a new instance of an object. An object. - , a .NET Framework data provider implements a strongly-typed version of . - + , a .NET Framework data provider implements a strongly-typed version of . + ]]> @@ -461,29 +461,29 @@ Executes an SQL statement against the object of a .NET data provider, and returns the number of rows affected. The number of rows affected. - to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database without using a by executing UPDATE, INSERT, or DELETE statements. - - Although the does not return any rows, any output parameters or return values mapped to parameters are populated with data. - - For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1. - - - -## Examples - The following example creates an instance of the derived class, , and then executes it. To accomplish this, the method is passed a string that is a SQL SELECT statement and a string to use to connect to the data source. - + to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database without using a by executing UPDATE, INSERT, or DELETE statements. + + Although the does not return any rows, any output parameters or return values mapped to parameters are populated with data. + + For UPDATE, INSERT, and DELETE statements, the return value is the number of rows affected by the command. For all other types of statements, the return value is -1. + + + +## Examples + The following example creates an instance of the derived class, , and then executes it. To accomplish this, the method is passed a string that is a SQL SELECT statement and a string to use to connect to the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.ExecuteNonQuery Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/ExecuteNonQuery/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/ExecuteNonQuery/source.vb" id="Snippet1"::: + ]]> - The connection does not exist. - - -or- - + The connection does not exist. + + -or- + The connection is not open. @@ -586,18 +586,18 @@ Executes the against the , and builds an using one of the values. An object. - method of the property. - - When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . - + method of the property. + + When the property is set to `StoredProcedure`, the property should be set to the name of the stored procedure. The command executes this stored procedure when you call . + > [!NOTE] -> Use to retrieve large values and binary data. Otherwise, an might occur and the connection will be closed. - - While the is in use, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until the method of the DataReader is called. If the DataReader is created with set to `CloseConnection`, closing the DataReader closes the connection automatically. - +> Use to retrieve large values and binary data. Otherwise, an might occur and the connection will be closed. + + While the is in use, the associated is busy serving the . While in this state, no other operations can be performed on the other than closing it. This is the case until the method of the DataReader is called. If the DataReader is created with set to `CloseConnection`, closing the DataReader closes the connection automatically. + ]]> @@ -645,28 +645,28 @@ Executes the query, and returns the first column of the first row in the resultset returned by the query. Extra columns or rows are ignored. The first column of the first row in the resultset. - method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method, and then performing the operations necessary to generate the single value using the data returned by an . - - A typical query can be formatted as in the following C# example: - -``` -CommandText = "select count(*) as NumberOfRegions from region"; -Int32 count = (int) ExecuteScalar(); -``` - - If the first column of the first row in the result set is not found, a null reference (`Nothing` in Visual Basic) is returned. If the value in the database is `null`, the query returns `DBNull.Value`. - - - -## Examples - The following example creates an instance of the derived class, , and then executes it using . The example is passed a string that is a Transact-SQL statement that returns an aggregate result, and a string to use to connect to the data source. - + method to retrieve a single value (for example, an aggregate value) from a database. This requires less code than using the method, and then performing the operations necessary to generate the single value using the data returned by an . + + A typical query can be formatted as in the following C# example: + +``` +CommandText = "select count(*) as NumberOfRegions from region"; +Int32 count = (int) ExecuteScalar(); +``` + + If the first column of the first row in the result set is not found, a null reference (`Nothing` in Visual Basic) is returned. If the value in the database is `null`, the query returns `DBNull.Value`. + + + +## Examples + The following example creates an instance of the derived class, , and then executes it using . The example is passed a string that is a Transact-SQL statement that returns an aggregate result, and a string to use to connect to the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlCommand.ExecuteScalar/CS/mysample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/ExecuteScalar/mysample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/ExecuteScalar/mysample.vb" id="Snippet1"::: + ]]> @@ -712,14 +712,14 @@ Int32 count = (int) ExecuteScalar(); Gets the . The parameters of the SQL statement or stored procedure. - , and displays its parameters. In the example, the application passes a , a query string that is a Transact-SQL SELECT statement, and an array of objects. - + , and displays its parameters. In the example, the application passes a , a query string that is a Transact-SQL SELECT statement, and an array of objects. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData IDbCommand.Parameters Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/Parameters/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/Parameters/source.vb" id="Snippet1"::: + ]]> @@ -766,25 +766,25 @@ Int32 count = (int) ExecuteScalar(); Creates a prepared (or compiled) version of the command on the data source. - property is set to `TableDirect`, does nothing. If is set to `StoredProcedure`, the call to should succeed, although it may result in a no-op. The server automatically caches plans for reuse as necessary; therefore, there is no need to call this method directly in your client application. - - - -## Examples - The following example creates an instance of the derived class, , and opens the connection. The example then prepares a stored procedure on the data source by passing a string that is a SQL Select statement and a string to use to connect to the data source. - + property is set to `TableDirect`, does nothing. If is set to `StoredProcedure`, the call to should succeed, although it may result in a no-op. The server automatically caches plans for reuse as necessary; therefore, there is no need to call this method directly in your client application. + + + +## Examples + The following example creates an instance of the derived class, , and opens the connection. The example then prepares a stored procedure on the data source by passing a string that is a SQL Select statement and a string to use to connect to the data source. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbCommand.Prepare Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/Prepare/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbCommand/Prepare/source.vb" id="Snippet1"::: + ]]> - The is not set. - - -or- - + The is not set. + + -or- + The is not . diff --git a/xml/System.Data/IDbConnection.xml b/xml/System.Data/IDbConnection.xml index 676737c14ee..08bbe61e56e 100644 --- a/xml/System.Data/IDbConnection.xml +++ b/xml/System.Data/IDbConnection.xml @@ -56,7 +56,7 @@ An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - Classes that inherit must implement all inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the property. + Classes that inherit must implement all inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the property. diff --git a/xml/System.Data/IDbDataAdapter.xml b/xml/System.Data/IDbDataAdapter.xml index b39c6ab0139..db04dfe62a2 100644 --- a/xml/System.Data/IDbDataAdapter.xml +++ b/xml/System.Data/IDbDataAdapter.xml @@ -48,50 +48,50 @@ Represents a set of command-related properties that are used to fill the and update a data source, and is implemented by .NET data providers that access relational databases. - interface inherits from the interface and allows an object to create a DataAdapter designed for use with a relational database. The interface and, optionally, the utility class, , allow an inheriting class to implement a DataAdapter class, which represents the bridge between a data source and a . For more information about DataAdapter classes, see [Populating a DataSet from a DataAdapter](/dotnet/framework/data/adonet/populating-a-dataset-from-a-dataadapter). For more information about implementing .NET Framework data providers, see [Implementing a .NET Framework Data Provider](https://learn.microsoft.com/previous-versions/dotnet/netframework-1.1/4ksaf9z5(v=vs.71)). - - An application does not create an instance of the interface directly, but creates an instance of a class that inherits and . - - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property, and the interface defines a method that takes a as a parameter. In turn, the class inherits the property and the method, and also defines two additional overloads of the method that take an ADO Recordset object as a parameter. - - - -## Examples - The following example uses the derived classes, , and , to select records from a data source. The filled is then returned. To accomplish this, the method is passed an initialized , a connection string, and a query string that is a Transact-SQL SELECT statement. - + interface inherits from the interface and allows an object to create a DataAdapter designed for use with a relational database. The interface and, optionally, the utility class, , allow an inheriting class to implement a DataAdapter class, which represents the bridge between a data source and a . For more information about DataAdapter classes, see [Populating a DataSet from a DataAdapter](/dotnet/framework/data/adonet/populating-a-dataset-from-a-dataadapter). For more information about implementing .NET Framework data providers, see [Implementing a .NET Framework Data Provider](https://learn.microsoft.com/previous-versions/dotnet/netframework-1.1/4ksaf9z5(v=vs.71)). + + An application does not create an instance of the interface directly, but creates an instance of a class that inherits and . + + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property, and the interface defines a method that takes a as a parameter. In turn, the class inherits the property and the method, and also defines two additional overloads of the method that take an ADO Recordset object as a parameter. + + + +## Examples + The following example uses the derived classes, , and , to select records from a data source. The filled is then returned. To accomplish this, the method is passed an initialized , a connection string, and a query string that is a Transact-SQL SELECT statement. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData SqlDataAdapter Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataAdapter/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDataAdapter/Overview/source.vb" id="Snippet1"::: + ]]> - To promote consistency among .NET Framework data providers, name the inheriting class in the form DataAdapter where is the uniform prefix given to all classes in a specific .NET Framework data provider namespace. For example, is the prefix of the class in the namespace. - - When you inherit from the interface, you should implement the following constructors: - - Item - - Description - - PrvDataAdapter() - - Initializes a new instance of the PrvDataAdapter class. - - PrvDataAdapter(PrvCommand selectCommand) - - Initializes a new instance of the PrvDataAdapter class with the specified SQL SELECT statement. - - PrvDataAdapter(string selectCommandText, string selectConnectionString) - - Initializes a new instance of the PrvDataAdapter class with an SQL SELECT statement and a connection string. - - PrvDataAdapter(string selectCommandText, PrvConnection selectConnection) - - Initializes a new instance of the PrvDataAdapter class with an SQL SELECT statement and a PrvConnection object. - + To promote consistency among .NET Framework data providers, name the inheriting class in the form DataAdapter where is the uniform prefix given to all classes in a specific .NET Framework data provider namespace. For example, is the prefix of the class in the namespace. + + When you inherit from the interface, you should implement the following constructors: + + Item + + Description + + PrvDataAdapter() + + Initializes a new instance of the PrvDataAdapter class. + + PrvDataAdapter(PrvCommand selectCommand) + + Initializes a new instance of the PrvDataAdapter class with the specified SQL SELECT statement. + + PrvDataAdapter(string selectCommandText, string selectConnectionString) + + Initializes a new instance of the PrvDataAdapter class with an SQL SELECT statement and a connection string. + + PrvDataAdapter(string selectCommandText, PrvConnection selectConnection) + + Initializes a new instance of the PrvDataAdapter class with an SQL SELECT statement and a PrvConnection object. + @@ -137,21 +137,21 @@ Gets or sets an SQL statement for deleting records from the data set. An used during to delete records in the data source for deleted rows in the data set. - , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - - - -## Examples - The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. - + , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + + + +## Examples + The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.DeleteCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/DeleteCommand/source.vb" id="Snippet1"::: + ]]> @@ -197,24 +197,24 @@ Gets or sets an SQL statement used to insert new records into the data source. An used during to insert records in the data source for new rows in the data set. - , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - + , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + > [!NOTE] -> If execution of this command returns rows, these rows may be added to the depending on how you set the property of the object. - - - -## Examples - The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. - +> If execution of this command returns rows, these rows may be added to the depending on how you set the property of the object. + + + +## Examples + The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.InsertCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/InsertCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/InsertCommand/source.vb" id="Snippet1"::: + ]]> @@ -260,21 +260,21 @@ Gets or sets an SQL statement used to select records in the data source. An that is used during to select records from data source for placement in the data set. - is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - - If the does not return any rows, no tables are added to the , and no exception is raised. - - - -## Examples - The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. - + is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + + If the does not return any rows, no tables are added to the , and no exception is raised. + + + +## Examples + The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DbDataAdapter.SelectCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/SelectCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/SelectCommand/source.vb" id="Snippet1"::: + ]]> @@ -320,24 +320,24 @@ Gets or sets an SQL statement used to update records in the data source. An used during to update records in the data source for modified rows in the data set. - , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). - - When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. - + , if this property is not set and primary key information is present in the , the can be generated automatically if you set the `SelectCommand` property of a .NET Framework data provider. Then, any additional commands that you do not set are generated by the CommandBuilder. This generation logic requires key column information to be present in the . For more information see [Generating Commands with CommandBuilders](/dotnet/framework/data/adonet/generating-commands-with-commandbuilders). + + When is assigned to a previously created , the is not cloned. The maintains a reference to the previously created object. + > [!NOTE] -> If execution of this command returns rows, these rows are added to the . - - - -## Examples - The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. - +> If execution of this command returns rows, these rows are added to the . + + + +## Examples + The following example creates an instance of the inherited class, and sets the and properties. It assumes you have already created an object. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData OleDbDataAdapter.UpdateCommand Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/IDbDataAdapter/UpdateCommand/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/ITableMapping.xml b/xml/System.Data/ITableMapping.xml index e212330ddb9..921110886fa 100644 --- a/xml/System.Data/ITableMapping.xml +++ b/xml/System.Data/ITableMapping.xml @@ -44,44 +44,44 @@ Associates a source table with a table in a , and is implemented by the class, which is used in common by .NET data providers. - interface allows an inheriting class to implement a TableMapping class, which associates a data source column with a column. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). - - An application does not create an instance of the interface directly, but creates an instance of a class that inherits . - - Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the method. - - - -## Examples - The following example creates an instance of the derived class, , and adds it to a collection. It then informs the user that the mapping was added to the collection and displays the parent mapping. - + interface allows an inheriting class to implement a TableMapping class, which associates a data source column with a column. For more information, see [DataAdapter DataTable and DataColumn Mappings](/dotnet/framework/data/adonet/dataadapter-datatable-and-datacolumn-mappings). + + An application does not create an instance of the interface directly, but creates an instance of a class that inherits . + + Classes that inherit must implement the inherited members, and typically define additional members to add provider-specific functionality. For example, the interface defines the property. In turn, the class inherits this property, and also defines the method. + + + +## Examples + The following example creates an instance of the derived class, , and adds it to a collection. It then informs the user that the mapping was added to the collection and displays the parent mapping. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/Overview/source.vb" id="Snippet1"::: + ]]> - When you inherit from the interface, you should implement the following constructors: - - Item - - Description - - DataTableMapping() - - Initializes a new instance of the TableMapping class. - - TableMapping(string sourceTable, string dataSetTable) - - Initializes a new instance of the TableMapping class with a source when given a source table name and a name. - - TableMapping(string sourceTable, string dataSetTable, DataColumnMapping[] columnMappings) - - Initializes a new instance of the TableMapping class when given a source table name, a name, and an array of ColumnMapping objects. - + When you inherit from the interface, you should implement the following constructors: + + Item + + Description + + DataTableMapping() + + Initializes a new instance of the TableMapping class. + + TableMapping(string sourceTable, string dataSetTable) + + Initializes a new instance of the TableMapping class with a source when given a source table name and a name. + + TableMapping(string sourceTable, string dataSetTable, DataColumnMapping[] columnMappings) + + Initializes a new instance of the TableMapping class when given a source table name, a name, and an array of ColumnMapping objects. + @@ -127,14 +127,14 @@ Gets the derived for the . A collection of data column mappings. - , sets some of its properties, and copies its to an array. This example assumes that a has been created. - + , sets some of its properties, and copies its to an array. This example assumes that a has been created. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData DataTableMapping.ColumnMappings Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/ColumnMappings/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/ITableMapping/ColumnMappings/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/InvalidExpressionException.xml b/xml/System.Data/InvalidExpressionException.xml index fddedceca4c..0cd381a1927 100644 --- a/xml/System.Data/InvalidExpressionException.xml +++ b/xml/System.Data/InvalidExpressionException.xml @@ -57,11 +57,11 @@ Represents the exception that is thrown when you try to add a that contains an invalid to a . - property is use to calculate the value of a column, or create an aggregate column. - + property is use to calculate the value of a column, or create an aggregate column. + ]]> diff --git a/xml/System.Data/MappingType.xml b/xml/System.Data/MappingType.xml index 36ad2acbaa1..727a58a8c97 100644 --- a/xml/System.Data/MappingType.xml +++ b/xml/System.Data/MappingType.xml @@ -52,19 +52,19 @@ Specifies how a is mapped. - enumeration is used when getting or setting the property of the . The property determines how a column's values will be written when the method is called on a to write the data and schema out as an XML document. - - - -## Examples - The following example returns the property value for each column in a table. - + enumeration is used when getting or setting the property of the . The property determines how a column's values will be written when the method is called on a to write the data and schema out as an XML document. + + + +## Examples + The following example returns the property value for each column in a table. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData MappingType Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/MappingType/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/MappingType/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/Rule.xml b/xml/System.Data/Rule.xml index f6bd5f85c1b..cdeed361bfc 100644 --- a/xml/System.Data/Rule.xml +++ b/xml/System.Data/Rule.xml @@ -45,26 +45,26 @@ Indicates the action that occurs when a is enforced. - values are set to the and the properties of a object found in a object's . - - The values determine the action that occurs when a value in a column is either deleted or updated. Of the two, deleting a value is the more critical and demanding of attention when setting a rule. - - In the case where a value is deleted, `Cascade` specifies that all rows containing that value are also deleted. `SetNull` specifies that values in all child columns are set to null values. `SetDefault` specifies that all child columns be set to the default value for the column. `None` specifies that no action will occur, but exceptions are generated. - - In the case where a value is updated, `Cascade` specifies that all child columns are likewise updated with the new value. `SetNull` specifies that all child columns be set to null values. `SetDefault` specifies that all child column values be set to the default value. `None` specifies that no action be taken, but exceptions are generated. - - Constraints on a are not enforced unless the property is `true`. - - When the method is called, the further determines what action occurs. - - - -## Examples - :::code language="vb" source="~/snippets/visualbasic/System.Data/ForeignKeyConstraint/Overview/source.vb" id="Snippet1"::: - + values are set to the and the properties of a object found in a object's . + + The values determine the action that occurs when a value in a column is either deleted or updated. Of the two, deleting a value is the more critical and demanding of attention when setting a rule. + + In the case where a value is deleted, `Cascade` specifies that all rows containing that value are also deleted. `SetNull` specifies that values in all child columns are set to null values. `SetDefault` specifies that all child columns be set to the default value for the column. `None` specifies that no action will occur, but exceptions are generated. + + In the case where a value is updated, `Cascade` specifies that all child columns are likewise updated with the new value. `SetNull` specifies that all child columns be set to null values. `SetDefault` specifies that all child column values be set to the default value. `None` specifies that no action be taken, but exceptions are generated. + + Constraints on a are not enforced unless the property is `true`. + + When the method is called, the further determines what action occurs. + + + +## Examples + :::code language="vb" source="~/snippets/visualbasic/System.Data/ForeignKeyConstraint/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/SchemaSerializationMode.xml b/xml/System.Data/SchemaSerializationMode.xml index d8b3ec0cb0d..22d4998ae7a 100644 --- a/xml/System.Data/SchemaSerializationMode.xml +++ b/xml/System.Data/SchemaSerializationMode.xml @@ -44,11 +44,11 @@ Indicates the schema serialization mode for a typed . - property of a typed to ExcludeSchema provides the option of omitting schema information from the serialization payload. - + property of a typed to ExcludeSchema provides the option of omitting schema information from the serialization payload. + ]]> diff --git a/xml/System.Data/UniqueConstraint.xml b/xml/System.Data/UniqueConstraint.xml index a16a279cc92..77d056934eb 100644 --- a/xml/System.Data/UniqueConstraint.xml +++ b/xml/System.Data/UniqueConstraint.xml @@ -73,22 +73,22 @@ Represents a restriction on a set of columns in which all values must be unique. - is enforced on a single column (or columns) to ensure that a primary key value is unique. - - Constraints are not enforced unless the property is set to `true`. - - When the a is merged with a second , constraints are not enforced until all merges are completed. - - - -## Examples - The following example adds a to a and sets the property to `true`. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/Overview/source.vb" id="Snippet1"::: - + is enforced on a single column (or columns) to ensure that a primary key value is unique. + + Constraints are not enforced unless the property is set to `true`. + + When the a is merged with a second , constraints are not enforced until all merges are completed. + + + +## Examples + The following example adds a to a and sets the property to `true`. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/Overview/source.vb" id="Snippet1"::: + ]]> This type is suitable for multithreaded read operations. You must synchronize any write operations. @@ -151,13 +151,13 @@ The to constrain. Initializes a new instance of the class with the specified . - and assigns it to the property of a . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/.ctor/source.vb" id="Snippet1"::: - + and assigns it to the property of a . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/.ctor/source.vb" id="Snippet1"::: + ]]> Adding Constraints to a Table @@ -348,13 +348,13 @@ The to constrain. Initializes a new instance of the class with the specified name and . - and assigns it to the property of a . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/.ctor/source.vb" id="Snippet1"::: - + and assigns it to the property of a . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/.ctor/source.vb" id="Snippet1"::: + ]]> @@ -412,14 +412,14 @@ The array of objects to constrain. Initializes a new instance of the class with the specified name and array of objects. - with two columns, and adds a new to the . - + with two columns, and adds a new to the . + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_ADO.NET/Classic WebData UniqueConstraint.UniqueConstraint2 Example/CS/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/.ctor/source1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/.ctor/source1.vb" id="Snippet1"::: + ]]> Adding Constraints to a Table @@ -596,11 +596,11 @@ to indicate that the constraint is a primary key; otherwise, . Initializes a new instance of the class with the specified name, an array of objects to constrain, and a value specifying whether the constraint is a primary key. - objects created by using this constructor must then be added to the collection via . Columns with the specified names must exist at the time the method is called, or if has been called prior to calling this constructor, the columns with the specified names must exist at the time that is called. - + objects created by using this constructor must then be added to the collection via . Columns with the specified names must exist at the time the method is called, or if has been called prior to calling this constructor, the columns with the specified names must exist at the time that is called. + ]]> Adding Constraints to a Table @@ -656,13 +656,13 @@ Gets the array of columns that this constraint affects. An array of objects. - objects that the constrains. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/Columns/source.vb" id="Snippet1"::: - + objects that the constrains. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/Columns/source.vb" id="Snippet1"::: + ]]> Adding Constraints to a Table @@ -721,18 +721,18 @@ , if the constraints are equal; otherwise, . - @@ -829,18 +829,18 @@ , if the constraint is on a primary key; otherwise, . - property. - - :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/IsPrimaryKey/source.vb" id="Snippet1"::: - + property. + + :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/IsPrimaryKey/source.vb" id="Snippet1"::: + ]]> Adding Constraints to a Table @@ -901,13 +901,13 @@ Gets the table to which this constraint belongs. The to which the constraint belongs. - object's . - - :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/Table/source.vb" id="Snippet1"::: - + object's . + + :::code language="vb" source="~/snippets/visualbasic/System.Data/UniqueConstraint/Table/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Data/UpdateRowSource.xml b/xml/System.Data/UpdateRowSource.xml index bb8f2aa41c6..422997cfcb7 100644 --- a/xml/System.Data/UpdateRowSource.xml +++ b/xml/System.Data/UpdateRowSource.xml @@ -47,13 +47,13 @@ Specifies how query command results are applied to the row being updated. - values are used by the property of and any classes derived from it. - - For more information property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). - + values are used by the property of and any classes derived from it. + + For more information property, see [DataAdapter Parameters](/dotnet/framework/data/adonet/dataadapter-parameters). + ]]> diff --git a/xml/System.Device.Location/GeoCoordinate.xml b/xml/System.Device.Location/GeoCoordinate.xml index f8a27388450..20211191c59 100644 --- a/xml/System.Device.Location/GeoCoordinate.xml +++ b/xml/System.Device.Location/GeoCoordinate.xml @@ -712,7 +712,7 @@ property can be used to verify whether a contains no data. + The property can be used to verify whether a contains no data. diff --git a/xml/System.Device.Location/GeoCoordinateWatcher.xml b/xml/System.Device.Location/GeoCoordinateWatcher.xml index 80e30440828..4000cf472f7 100644 --- a/xml/System.Device.Location/GeoCoordinateWatcher.xml +++ b/xml/System.Device.Location/GeoCoordinateWatcher.xml @@ -39,7 +39,7 @@ To begin accessing location data, create a and call or to initiate the acquisition of data from the current location provider. - The property can be checked to determine if data is available. If data is available, you can get the location one time from the property, or receive continuous location updates by handling the event. + The property can be checked to determine if data is available. If data is available, you can get the location one time from the property, or receive continuous location updates by handling the event. The , , and properties support , so that an application can data-bind to these properties. @@ -50,9 +50,9 @@ **Note** In versions of Windows prior to Windows 7, the following conditions apply: -- All objects that have constructors can be created, but the property will always have the value . +- All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. @@ -86,9 +86,9 @@ ## Remarks **Note** In versions of Windows prior to Windows 7, the following conditions apply: -- All objects that have constructors can be created, but the property will always have the value . +- All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. @@ -124,9 +124,9 @@ **Note** In versions of Windows prior to Windows 7, the following conditions apply: -- All objects that have constructors can be created, but the property will always have the value . +- All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. @@ -161,9 +161,9 @@ ## Remarks **Note** In versions of Windows prior to Windows 7, the following conditions apply: -- All objects that have constructors can be created, but the property will always have the value . +- All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. @@ -346,16 +346,16 @@ event and an update in the property. + The default movement threshold is zero, which means that any change in location detected by the current location provider causes a event and an update in the property. > [!NOTE] > The movement threshold does not guarantee that events will be received at the requested threshold. The platform attempts to honor requests for a particular movement threshold, but in some cases, the events will not be raised at the requested threshold. **Note** In versions of Windows prior to Windows 7, the following conditions apply: -- All objects that have constructors can be created, but the property will always have the value . +- All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. @@ -452,7 +452,7 @@ ## Remarks Handle the event to implement data binding in Windows Forms applications. - This method indicates that the property, the property, or the property has changed. + This method indicates that the property, the property, or the property has changed. ]]> @@ -512,7 +512,7 @@ property of the property is saved in a object. The latitude and longitude fields of the are printed if they are known. + In the following example, the property of the property is saved in a object. The latitude and longitude fields of the are printed if they are known. :::code language="csharp" source="~/snippets/csharp/System.Device.Location/GeoCoordinateWatcher/Overview/getlocationdatasync.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/system.device.location.getlocationdatasync1/vb/GetLocationDataSync.vb" id="Snippet2"::: @@ -607,7 +607,7 @@ If the current prioritized location provider does not have data when the method is called, it will start to acquire data. If the permissions have been granted to the client when the data becomes available, data can be accessed synchronously, and will be delivered asynchronously if events are being handled. - If the Windows 7 Sensor and Location platform is disabled when is called, will immediately return, events will not be raised, and the location returned by the property of will contain . + If the Windows 7 Sensor and Location platform is disabled when is called, will immediately return, events will not be raised, and the location returned by the property of will contain . If the current prioritized location provider does have data, it will be available synchronously immediately, and will be delivered asynchronously if events are being handled. @@ -770,9 +770,9 @@ is called, no further events occur, and the property will return . + After is called, no further events occur, and the property will return . - When is called, the property is set to . + When is called, the property is set to . ]]> diff --git a/xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml b/xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml index fe7760c9a90..edfaff4b480 100644 --- a/xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml +++ b/xml/System.Diagnostics.CodeAnalysis/SuppressMessageAttribute.xml @@ -209,7 +209,7 @@ The following code example shows the use of the property describes the tool or tool analysis category for which a message suppression attribute applies. +The property describes the tool or tool analysis category for which a message suppression attribute applies. ## Examples The following code example shows the use of the attribute to suppress warnings for the `Microsoft.Performance` category and the `CA1801` and `CA1804` check identifiers. This code example is part of a larger example provided for the class. @@ -380,7 +380,7 @@ Concatenated together, the property is an optional argument that specifies additional exclusion where the literal metadata target is not sufficiently precise. For example, the cannot be applied within a method, but you may want to suppress a violation against a single statement in the method. +The property is an optional argument that specifies additional exclusion where the literal metadata target is not sufficiently precise. For example, the cannot be applied within a method, but you may want to suppress a violation against a single statement in the method. > [!NOTE] > This property is only respected by [legacy code analysis](/visualstudio/code-quality/static-code-analysis-for-managed-code-overview). @@ -443,7 +443,7 @@ The ## Remarks -The property is an optional argument that specifies the metadata scope for which the attribute is relevant. The following table shows the possible values. +The property is an optional argument that specifies the metadata scope for which the attribute is relevant. The following table shows the possible values. | Value | Description | | - | - | @@ -506,7 +506,7 @@ For [legacy code analysis](/visualstudio/code-quality/static-code-analysis-for-m property is an optional argument identifying the analysis target of the attribute. An example value is "System.IO.Stream.ctor():System.Void". Because it is fully qualified, it can be long, particularly for targets such as parameters. The analysis tool user interface should be capable of automatically formatting the parameter. + The property is an optional argument identifying the analysis target of the attribute. An example value is "System.IO.Stream.ctor():System.Void". Because it is fully qualified, it can be long, particularly for targets such as parameters. The analysis tool user interface should be capable of automatically formatting the parameter. ]]> diff --git a/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml b/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml index 8ac5cb57441..65eadc167d5 100644 --- a/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml +++ b/xml/System.Diagnostics.Contracts/ContractFailedEventArgs.xml @@ -51,11 +51,11 @@ Provides methods and data for the event. - object is passed to the event when a contract fails. The event enables a managed application environment such as an interactive interpreter, a Web browser host, a test harness, or a logging infrastructure to be notified of contract failures. The event requires full trust. - + object is passed to the event when a contract fails. The event enables a managed application environment such as an interactive interpreter, a Web browser host, a test harness, or a logging infrastructure to be notified of contract failures. The event requires full trust. + ]]> @@ -233,11 +233,11 @@ if the event has been handled; otherwise, . - event has not been handled, the debugger is notified. If no debugger is attached, an **Assert** dialog box is displayed. - + event has not been handled, the debugger is notified. If no debugger is attached, an **Assert** dialog box is displayed. + ]]> @@ -368,11 +368,11 @@ Sets the property to . - method provides a way for the runtime analysis checker to indicate that a contract exception has been handled. See the property for more information. - + method provides a way for the runtime analysis checker to indicate that a contract exception has been handled. See the property for more information. + ]]> @@ -421,11 +421,11 @@ Sets the property to . - method provides a way to indicate that the escalation policy for the code contract should be applied. See the property for more information. - + method provides a way to indicate that the escalation policy for the code contract should be applied. See the property for more information. + ]]> @@ -469,14 +469,14 @@ to apply the escalation policy; otherwise, . The default is . - [!WARNING] -> This value should be set to `false` for analysis tools that run on a server (for example, ASP.NET). - +> This value should be set to `false` for analysis tools that run on a server (for example, ASP.NET). + ]]> diff --git a/xml/System.Diagnostics.Eventing/EventProvider.xml b/xml/System.Diagnostics.Eventing/EventProvider.xml index 4d6884245a6..7016019ab80 100644 --- a/xml/System.Diagnostics.Eventing/EventProvider.xml +++ b/xml/System.Diagnostics.Eventing/EventProvider.xml @@ -407,7 +407,7 @@ ## Remarks The identifier is stored in the thread context. - Note that in version 3.5 of the .NET framework, you had to set the `id` parameter of this method and the property value to the same identifier value. However, in version 4.0 of the framework, the method automatically sets the correlation activity identifier for you. + Note that in version 3.5 of the .NET framework, you had to set the `id` parameter of this method and the property value to the same identifier value. However, in version 4.0 of the framework, the method automatically sets the correlation activity identifier for you. This is a static method. @@ -814,7 +814,7 @@ if (!provider.WriteMessageEvent("Event string.", 3, 2)) ## Remarks The method uses the activity ID set in the thread context to identify this component. To set the activity ID, call the method. - If you use the class, you do not use the method to specify the activity ID. Instead, access the property to get the object. Then, set the property to the activity ID. You must also set the `relatedActivityId` to a value. + If you use the class, you do not use the method to specify the activity ID. Instead, access the property to get the object. Then, set the property to the activity ID. You must also set the `relatedActivityId` to a value. ]]> diff --git a/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml b/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml index 192909e5c47..3677494a556 100644 --- a/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml +++ b/xml/System.Diagnostics.Eventing/EventProviderTraceListener.xml @@ -20,7 +20,7 @@ property. + All event data (trace or debug) from the source event is written to the ETW subsystem as a string. The data elements are delimited using a comma. To specify a different delimiter, use the property. Adding the listener to registers the provider with the ETW subsystem. You must create an ETW trace session using the Logman.exe executable program (or something similar) to write the events to a log file. diff --git a/xml/System.Diagnostics.PerformanceData/CounterData.xml b/xml/System.Diagnostics.PerformanceData/CounterData.xml index de5d1375830..27e8030bf07 100644 --- a/xml/System.Diagnostics.PerformanceData/CounterData.xml +++ b/xml/System.Diagnostics.PerformanceData/CounterData.xml @@ -32,13 +32,13 @@ Contains the raw data for a counter. - property returns an instance of this class. - - This class provides thread-safe methods for reading and writing counter data. - + property returns an instance of this class. + + This class provides thread-safe methods for reading and writing counter data. + ]]> @@ -80,15 +80,15 @@ Decrements the counter value by 1. - method and set the `value` parameter to a negative number. - - To set the counter value, use the property. - + method and set the `value` parameter to a negative number. + + To set the counter value, use the property. + ]]> @@ -130,15 +130,15 @@ Increments the counter value by 1. - property. - - To increment the counter value by a specific value, call the method. - + property. + + To increment the counter value by a specific value, call the method. + ]]> @@ -183,15 +183,15 @@ The amount by which to increment the counter value. The increment value can be positive or negative. Increments the counter value by the specified amount. - property. - - To increment the counter value by 1, call the method. - + property. + + To increment the counter value by 1, call the method. + ]]> @@ -237,11 +237,11 @@ Gets or sets the raw counter data. The raw counter data. - property. - + property. + ]]> @@ -288,20 +288,20 @@ Gets or sets the counter data. The counter data. - property; however, the property is not thread safe. - - Note that the property is not thread safe in .NET Framework 3.5. - - To increment the counter value, consider using the or method. - - - -## Examples - For an example, see . - + property; however, the property is not thread safe. + + Note that the property is not thread safe in .NET Framework 3.5. + + To increment the counter value, consider using the or method. + + + +## Examples + For an example, see . + ]]> diff --git a/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml b/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml index 88876749dd6..ecb1e7b2781 100644 --- a/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml +++ b/xml/System.Diagnostics.PerformanceData/CounterSetInstanceCounterDataSet.xml @@ -36,11 +36,11 @@ Contains the collection of counter values. - property returns an instance of this class. - + property returns an instance of this class. + ]]> @@ -173,11 +173,11 @@ Accesses a counter value in the collection by using the specified counter identifier. The counter data. - @@ -218,13 +218,13 @@ Accesses a counter value in the collection by using the specified counter name. The counter data. - method to add the counter to the counter set. - + method to add the counter to the counter set. + ]]> diff --git a/xml/System.Diagnostics.Tracing/EventAttribute.xml b/xml/System.Diagnostics.Tracing/EventAttribute.xml index 9ea277b6a96..eca00a3e433 100644 --- a/xml/System.Diagnostics.Tracing/EventAttribute.xml +++ b/xml/System.Diagnostics.Tracing/EventAttribute.xml @@ -312,7 +312,7 @@ The following example shows how to use the property to define event keywords. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. + The following example shows how to use the property to define event keywords. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet3"::: @@ -370,7 +370,7 @@ The following example shows how to use the property to specify an event level. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. +The following example shows how to use the property to specify an event level. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: @@ -433,7 +433,7 @@ You can use standard .NET substitution operators (for example, {1}) in the strin ## Examples -The following example shows how to use the property to specify an event message. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. +The following example shows how to use the property to specify an event message. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet5"::: @@ -488,7 +488,7 @@ The following example shows how to use the property to specify operation codes. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. +The following example shows how to use the property to specify operation codes. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet9"::: @@ -588,7 +588,7 @@ The following example shows how to use the property to define event tasks. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. +The following example shows how to use the property to define event tasks. This code example is part of a larger example provided for the [EventSource](/dotnet/fundamentals/runtime-libraries/system-diagnostics-tracing-eventsource#examples) class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics.Tracing/EventAttribute/Overview/program.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics.Tracing/EventAttribute/Overview/program.vb" id="Snippet4"::: diff --git a/xml/System.Diagnostics.Tracing/EventSource.xml b/xml/System.Diagnostics.Tracing/EventSource.xml index 2856f1354f0..8f96a4e4315 100644 --- a/xml/System.Diagnostics.Tracing/EventSource.xml +++ b/xml/System.Diagnostics.Tracing/EventSource.xml @@ -582,7 +582,7 @@ constructors do not throw exceptions. Instead, any exception that is thrown is assigned to the property and logged by the method. + constructors do not throw exceptions. Instead, any exception that is thrown is assigned to the property and logged by the method. ]]> @@ -4039,7 +4039,7 @@ fixed(byte* ptr = arg) Your ETW event method calling this function must follow these guidelines: - Specify the first parameter as a named `relatedActivityId`. -- Specify either or as the property. +- Specify either or as the property. - Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. If `args` is not used, it is converted to an empty array for the resulting call to ETW. @@ -4133,7 +4133,7 @@ The following code example shows how you might can specify an event source that Your ETW event method calling this function must follow these guidelines: - Specify the first parameter as a named `relatedActivityId`. -- Specify either or as the property. +- Specify either or as the property. - Call passing in the event ID, followed by the related ID GUID, followed by all the parameters the event method is passed, in the same order. This method uses the same rules as for the `args` parameter. See WriteEventCore documentation for more details. diff --git a/xml/System.Diagnostics.Tracing/EventSourceAttribute.xml b/xml/System.Diagnostics.Tracing/EventSourceAttribute.xml index bdbc9e967ed..3dd12ff1d6b 100644 --- a/xml/System.Diagnostics.Tracing/EventSourceAttribute.xml +++ b/xml/System.Diagnostics.Tracing/EventSourceAttribute.xml @@ -210,7 +210,7 @@ constructor that will read the resources. This name is the value of the property. If the property is not `null`, the object looks up the localized strings for events by using the following resource naming scheme, where the terms in uppercase represent the name of the event, task, keyword, or map value that should be localized: + Event sources support the localization of events. You can localize the names used for events, operation codes, tasks, keywords, and maps to multiple languages. To localize events, create a .ResX style string table by adding a resource file to your project. The resource file is given a name (for example, DefaultNameSpace.ResourceFileName) that can be passed to the constructor that will read the resources. This name is the value of the property. If the property is not `null`, the object looks up the localized strings for events by using the following resource naming scheme, where the terms in uppercase represent the name of the event, task, keyword, or map value that should be localized: - event_EVENTNAME diff --git a/xml/System.Diagnostics.Tracing/EventSourceException.xml b/xml/System.Diagnostics.Tracing/EventSourceException.xml index e34f1c1f60b..7cfede61e56 100644 --- a/xml/System.Diagnostics.Tracing/EventSourceException.xml +++ b/xml/System.Diagnostics.Tracing/EventSourceException.xml @@ -262,7 +262,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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. ]]> diff --git a/xml/System.Diagnostics/BooleanSwitch.xml b/xml/System.Diagnostics/BooleanSwitch.xml index d9f71feca7c..626aeac4a66 100644 --- a/xml/System.Diagnostics/BooleanSwitch.xml +++ b/xml/System.Diagnostics/BooleanSwitch.xml @@ -60,9 +60,9 @@ property to get the current value of the switch. + You can use a Boolean trace switch to enable or disable messages based on their importance. Use the property to get the current value of the switch. -You can create a in your code and set the property directly to instrument a specific section of code. +You can create a in your code and set the property directly to instrument a specific section of code. For .NET Framework apps only, you can also enable or disable a through the application configuration file and then use the configured value in your application. To configure a , edit the configuration file that corresponds to the name of your application. Within this file, you can add or remove a switch, set a switch's value, or clear all the switches previously set by the application. The configuration file should be formatted like the following example. @@ -76,14 +76,14 @@ For .NET Framework apps only, you can also enable or disable a ``` - This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your .NET Framework application, you can use the configured switch value by creating a with the same name, as shown in the following code example. + This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your .NET Framework application, you can use the configured switch value by creating a with the same name, as shown in the following code example. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/BooleanSwitch/Overview/remarks.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/BooleanSwitch/Overview/remarks.vb" id="Snippet2"::: For .NET Core and .NET 5+ apps, the property of the new switch is set to `false` by default. -For .NET Framework apps, the property is set using the value specified in the configuration file. Configure the switch with a value of 0 to set the property to `false`; configure the switch with a nonzero value to set the property to `true`. If the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to `false`. +For .NET Framework apps, the property is set using the value specified in the configuration file. Configure the switch with a value of 0 to set the property to `false`; configure the switch with a nonzero value to set the property to `true`. If the constructor cannot find initial switch settings in the configuration file, the property of the new switch is set to `false`. You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -382,7 +382,7 @@ For .NET Framework apps, the method determines whether the new value is a valid string representation of a Boolean value ("false" or "true"). If so, the method sets the property to 0 or 1. Otherwise, the base method is called, which converts the string value to an integer value, which is then used to set the property. + The method determines whether the new value is a valid string representation of a Boolean value ("false" or "true"). If so, the method sets the property to 0 or 1. Otherwise, the base method is called, which converts the string value to an integer value, which is then used to set the property. ]]> diff --git a/xml/System.Diagnostics/ConsoleTraceListener.xml b/xml/System.Diagnostics/ConsoleTraceListener.xml index 25d68a47ef1..8da07c0e0cf 100644 --- a/xml/System.Diagnostics/ConsoleTraceListener.xml +++ b/xml/System.Diagnostics/ConsoleTraceListener.xml @@ -132,7 +132,7 @@ For .NET Framework apps, to direct all trace and debug messages to the console w object to write messages to the stream. Its property is initialized to an empty string (""). + This constructor initializes a object to write messages to the stream. Its property is initialized to an empty string (""). @@ -189,7 +189,7 @@ For .NET Framework apps, to direct all trace and debug messages to the console w object to write messages to either the or the stream. Its property is initialized to an empty string (""). + This constructor initializes a object to write messages to either the or the stream. Its property is initialized to an empty string (""). diff --git a/xml/System.Diagnostics/CorrelationManager.xml b/xml/System.Diagnostics/CorrelationManager.xml index 6b474e08699..9586c2429a3 100644 --- a/xml/System.Diagnostics/CorrelationManager.xml +++ b/xml/System.Diagnostics/CorrelationManager.xml @@ -56,7 +56,7 @@ ## Remarks Traces generated from a single logical operation can be tagged with an operation-unique identity, in order to distinguish them from traces from a different logical operation. For example, it may be useful to group correlated traces by ASP.NET request. The class provides methods used to store a logical operation identity in a thread-bound context and automatically tag each trace event generated by the thread with the stored identity. - Logical operations can also be nested. The property exposes the stack of nested logical operation identities. Each call to the method pushes a new logical operation identity onto the stack. Each call to the method pops a logical operation identity off the stack. + Logical operations can also be nested. The property exposes the stack of nested logical operation identities. Each call to the method pushes a new logical operation identity onto the stack. Each call to the method pops a logical operation identity off the stack. > [!NOTE] > Logical operation identities are objects, allowing the use of a type for a logical operation identity. @@ -65,7 +65,7 @@ ## Examples The following code example demonstrates the use of the class by identifying the logical operation associated with a traced event. Two logical operations are started, one in the main thread and the other in a worker thread. An error event is logged in both logical operations. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CorrelationManager/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CorrelationManager/Overview/module1.vb" id="Snippet1"::: @@ -115,7 +115,7 @@ property gets and sets the global activity identity in the for the thread. The is used for trace transfer operations in trace listeners that override the method, such as the class. + The property gets and sets the global activity identity in the for the thread. The is used for trace transfer operations in trace listeners that override the method, such as the class. ]]> @@ -169,7 +169,7 @@ method pushes a new logical operation identity onto the property's stack. Each call to the method pops a logical operation identity from the stack. + Each call to the method pushes a new logical operation identity onto the property's stack. Each call to the method pops a logical operation identity from the stack. ]]> @@ -278,7 +278,7 @@ that allows the operation to be identified for tracing purposes. The object represented by `operationId` is added to the property. + The `operationId` parameter can be any object, such as a that allows the operation to be identified for tracing purposes. The object represented by `operationId` is added to the property. @@ -335,7 +335,7 @@ property. + The logical operation is halted and the logical operation identity is removed from the property. ]]> diff --git a/xml/System.Diagnostics/CounterCreationData.xml b/xml/System.Diagnostics/CounterCreationData.xml index 7ae7ea352c4..ad5bda09c54 100644 --- a/xml/System.Diagnostics/CounterCreationData.xml +++ b/xml/System.Diagnostics/CounterCreationData.xml @@ -57,7 +57,7 @@ ## Examples The following code example demonstrates how to use the class to define custom counters. This example creates counters that display how many items are processed in an operation. The example initializes the counters, collects information from them, and then calculates and displays the results to the console. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -226,7 +226,7 @@ property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. + The following code example demonstrates how to get and set the property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.vb" id="Snippet5"::: @@ -301,7 +301,7 @@ property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. + The following code example demonstrates how to get and set the property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.vb" id="Snippet4"::: @@ -365,7 +365,7 @@ property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. + The following code example demonstrates how to get and set the property. This example creates two counters and sets their property by using different techniques. When the first counter is initialized, the data is passed to the constructor, whereas the second counter sets the property explicitly. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/.ctor/diagnostics_countercreationdata.vb" id="Snippet6"::: diff --git a/xml/System.Diagnostics/CounterSample.xml b/xml/System.Diagnostics/CounterSample.xml index 6767cb68117..3b68ca7fef9 100644 --- a/xml/System.Diagnostics/CounterSample.xml +++ b/xml/System.Diagnostics/CounterSample.xml @@ -53,7 +53,7 @@ ## Examples The following example demonstrates the use of the class to display data for a performance counter. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -238,7 +238,7 @@ property for a counter. + The following example displays the value of the property for a counter. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -378,7 +378,7 @@ property for a counter. + The following example displays the value of the property for a counter. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -429,7 +429,7 @@ property for a counter. + The following example displays the value of the property for a counter. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -792,7 +792,7 @@ property for a counter. + The following example displays the value of the property for a counter. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -843,7 +843,7 @@ property for a counter. + The following example displays the value of the property for a counter. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -894,7 +894,7 @@ property for a counter. + The following example displays the value of the property for a counter. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -945,7 +945,7 @@ property for a counter. + The following example displays the value of the property for a counter. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/DataReceivedEventArgs.xml b/xml/System.Diagnostics/DataReceivedEventArgs.xml index bebd52309ef..5858d6c57bd 100644 --- a/xml/System.Diagnostics/DataReceivedEventArgs.xml +++ b/xml/System.Diagnostics/DataReceivedEventArgs.xml @@ -55,7 +55,7 @@ or stream output of a process, you must create a method that handles the redirected stream output events. The event-handler method is called when the process writes to the redirected stream. The event delegate calls your event handler with an instance of . The property contains the text line that the process wrote to the redirected stream. + To asynchronously collect the redirected or stream output of a process, you must create a method that handles the redirected stream output events. The event-handler method is called when the process writes to the redirected stream. The event delegate calls your event handler with an instance of . The property contains the text line that the process wrote to the redirected stream. @@ -63,7 +63,7 @@ The following code example illustrates how to perform asynchronous read operations on the redirected stream of the `sort` command. The `sort` command is a console application that reads and sorts text input. The example creates an event delegate for the `SortOutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DataReceivedEventArgs/Overview/sort_async.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DataReceivedEventArgs/Overview/sort_async.vb" id="Snippet1"::: @@ -125,11 +125,11 @@ or stream of a to your event handler, an event is raised each time the process writes a line to the redirected stream. The property is the line that the wrote to the redirected output stream. Your event handler can use the property to filter process output or write output to an alternate location. For example, you might create an event handler that stores all error output lines into a designated error log file. + When you redirect the or stream of a to your event handler, an event is raised each time the process writes a line to the redirected stream. The property is the line that the wrote to the redirected output stream. Your event handler can use the property to filter process output or write output to an alternate location. For example, you might create an event handler that stores all error output lines into a designated error log file. - A line is defined as a sequence of characters followed by a line feed ("\n") or a carriage return immediately followed by a line feed ("\r\n"). The line characters are encoded using the default system ANSI code page. The property does not include the terminating carriage return or line feed. + A line is defined as a sequence of characters followed by a line feed ("\n") or a carriage return immediately followed by a line feed ("\r\n"). The line characters are encoded using the default system ANSI code page. The property does not include the terminating carriage return or line feed. - When the redirected stream is closed, a null line is sent to the event handler. Ensure your event handler checks the property appropriately before accessing it. For example, you can use the static method to validate the property in your event handler. + When the redirected stream is closed, a null line is sent to the event handler. Ensure your event handler checks the property appropriately before accessing it. For example, you can use the static method to validate the property in your event handler. diff --git a/xml/System.Diagnostics/DataReceivedEventHandler.xml b/xml/System.Diagnostics/DataReceivedEventHandler.xml index f18662494c1..3944f22dc00 100644 --- a/xml/System.Diagnostics/DataReceivedEventHandler.xml +++ b/xml/System.Diagnostics/DataReceivedEventHandler.xml @@ -59,7 +59,7 @@ ## Remarks When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - To asynchronously collect the redirected or stream output of a process, add your event handler to the or event. These events are raised each time the process writes a line to the corresponding redirected stream. When the redirected stream is closed, a null line is sent to the event handler. Ensure that your event handler checks for this condition before accessing the property. For example, you can use the `static` method to validate the property in your event handler. + To asynchronously collect the redirected or stream output of a process, add your event handler to the or event. These events are raised each time the process writes a line to the corresponding redirected stream. When the redirected stream is closed, a null line is sent to the event handler. Ensure that your event handler checks for this condition before accessing the property. For example, you can use the `static` method to validate the property in your event handler. @@ -67,7 +67,7 @@ The following code example illustrates how to perform asynchronous read operations on the redirected stream of the **sort** command. The **sort** command is a console application that reads and sorts text input. The example creates a delegate for the `SortOutputHandler` event handler and associates the delegate with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DataReceivedEventArgs/Overview/sort_async.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DataReceivedEventArgs/Overview/sort_async.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/Debug.xml b/xml/System.Diagnostics/Debug.xml index 0587d27428a..0828fef1233 100644 --- a/xml/System.Diagnostics/Debug.xml +++ b/xml/System.Diagnostics/Debug.xml @@ -89,7 +89,7 @@ To make your code more robust without impacting the performance and code size of > [!NOTE] > Adding a trace listener to the collection can cause an exception to be thrown while tracing, if a resource used by the trace listener is not available. The conditions and the exception thrown depend on the trace listener and can't be enumerated in this article. It may be useful to place calls to the methods in `try`/`catch` blocks to detect and handle any exceptions from trace listeners. - You can modify the level of indentation using the method or the property. To modify the indent spacing, use the property. You can specify whether to automatically flush the output buffer after each write by setting the property to `true`. + You can modify the level of indentation using the method or the property. To modify the indent spacing, use the property. You can specify whether to automatically flush the output buffer after each write by setting the property to `true`. For .NET Framework apps, you can set the and for by editing your app's configuration file. The configuration file should be formatted as shown in the following example. @@ -219,9 +219,9 @@ The following example uses to indicate the begin > Windows 8.x apps do not support modal dialog boxes, so they behave the same in user interface mode and non-user interface mode. The message is written to the active trace listeners in debugging mode, or no message is written in release mode. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -321,9 +321,9 @@ This overload was introduced in .NET 6 to improve performance. In comparison to When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -427,9 +427,9 @@ For .NET Framework apps, you can change the behavior of the [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -538,9 +538,9 @@ This overload was introduced in .NET 6 to improve performance. In comparison to When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -636,9 +636,9 @@ For .NET Framework apps, you can change the behavior of the [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -769,9 +769,9 @@ The following example checks whether the `type` parameter is valid. If `type` is When the application runs in user interface mode, it displays a message box that shows the call stack with file and line numbers. The message box contains three buttons: **Abort**, **Retry**, and **Ignore**. Clicking the **Abort** button terminates the application. Clicking **Retry** sends you to the code in the debugger if your application is running in a debugger, or offers to open a debugger if it is not. Clicking **Ignore** continues with the next instruction in the code. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -1007,7 +1007,7 @@ The following example creates a outputs the message to a message box when the application is running in user interface mode and to the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). You can customize this behavior by adding a to, or removing one from, the collection. @@ -1103,7 +1103,7 @@ The following example uses the method to The default behavior is that the outputs the message to a message box when the application is running in user interface mode and to the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). You can customize this behavior by adding a to, or removing one from, the collection. @@ -1329,7 +1329,7 @@ End of list of errors ## Remarks -The property represents the number of times the indent of size is applied. +The property represents the number of times the indent of size is applied. ## Examples diff --git a/xml/System.Diagnostics/DebuggableAttribute.xml b/xml/System.Diagnostics/DebuggableAttribute.xml index ff30a93484f..9f660fe8abf 100644 --- a/xml/System.Diagnostics/DebuggableAttribute.xml +++ b/xml/System.Diagnostics/DebuggableAttribute.xml @@ -240,7 +240,7 @@ property controls how the runtime tracks information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. + The property controls how the runtime tracks information important to the debugger during code generation. This information helps the debugger provide a rich debugging experience. ]]> diff --git a/xml/System.Diagnostics/DebuggerDisplayAttribute.xml b/xml/System.Diagnostics/DebuggerDisplayAttribute.xml index 4aa5f0a0759..2243c85a46d 100644 --- a/xml/System.Diagnostics/DebuggerDisplayAttribute.xml +++ b/xml/System.Diagnostics/DebuggerDisplayAttribute.xml @@ -91,7 +91,7 @@ class MyHashtable ## Examples View the following example in Visual Studio to see the results of applying the . - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DebuggerBrowsableAttribute/.ctor/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DebuggerBrowsableAttribute/.ctor/module1.vb" id="Snippet1"::: @@ -160,7 +160,7 @@ class MyTable ## Examples - The following code example causes the value of the property from the inherited class to be displayed when the plus sign (+) is selected to expand the debugger display for an instance of `MyHashtable`. You must run the complete example, which is provided in the class, to see the results. + The following code example causes the value of the property from the inherited class to be displayed when the plus sign (+) is selected to expand the debugger display for an instance of `MyHashtable`. You must run the complete example, which is provided in the class, to see the results. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DebuggerBrowsableAttribute/.ctor/program.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DebuggerBrowsableAttribute/.ctor/module1.vb" id="Snippet4"::: diff --git a/xml/System.Diagnostics/DebuggerTypeProxyAttribute.xml b/xml/System.Diagnostics/DebuggerTypeProxyAttribute.xml index 7dae75dc044..c01e3f636fb 100644 --- a/xml/System.Diagnostics/DebuggerTypeProxyAttribute.xml +++ b/xml/System.Diagnostics/DebuggerTypeProxyAttribute.xml @@ -77,7 +77,7 @@ ## Remarks **Note** Use this attribute when you need to significantly and fundamentally change the debugging view of a type, but not change the type itself. - The attribute is used to specify a display proxy for a type, allowing a developer to tailor the view for the type. This attribute can be used at the assembly level as well, in which case the property specifies the type for which the proxy will be used. In general, this attribute specifies a private nested type that occurs within the type to which the attribute is applied. An expression evaluator that supports type viewers checks for this attribute when a type is displayed. If the attribute is found, the expression evaluator substitutes the display proxy type for the type the attribute is applied to. + The attribute is used to specify a display proxy for a type, allowing a developer to tailor the view for the type. This attribute can be used at the assembly level as well, in which case the property specifies the type for which the proxy will be used. In general, this attribute specifies a private nested type that occurs within the type to which the attribute is applied. An expression evaluator that supports type viewers checks for this attribute when a type is displayed. If the attribute is found, the expression evaluator substitutes the display proxy type for the type the attribute is applied to. When the is present, the debugger variable window displays only the public members of the proxy type. Private members are not displayed. The behavior of the data window is not changed by attribute-enhanced views. @@ -87,7 +87,7 @@ ## Examples The following code example shows the use of the to specify a private nested type to be used as a debugger display proxy. This code example is part of a larger example provided for the class. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DebuggerBrowsableAttribute/.ctor/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DebuggerBrowsableAttribute/.ctor/module1.vb" id="Snippet5"::: diff --git a/xml/System.Diagnostics/DebuggerVisualizerAttribute.xml b/xml/System.Diagnostics/DebuggerVisualizerAttribute.xml index 07b707e8d9b..146acc9ff2a 100644 --- a/xml/System.Diagnostics/DebuggerVisualizerAttribute.xml +++ b/xml/System.Diagnostics/DebuggerVisualizerAttribute.xml @@ -69,14 +69,14 @@ Specifies that the type has a visualizer. This class cannot be inherited. - . This allows a component creator to ship the visualizer in a DLL to be called only at debug time. The property specifies the visualizer description that appears in the drop-down box. The target parameters specify the type that is the target of the visualizer. For more information about visualizers, see [Create Custom Visualizers of Data](/visualstudio/debugger/create-custom-visualizers-of-data). - + . This allows a component creator to ship the visualizer in a DLL to be called only at debug time. The property specifies the visualizer description that appears in the drop-down box. The target parameters specify the type that is the target of the visualizer. For more information about visualizers, see [Create Custom Visualizers of Data](/visualstudio/debugger/create-custom-visualizers-of-data). + > [!NOTE] -> Visualizer and visualizer object source implementation is dependent upon the hosting debugger. For information on creating a visualizer for Visual Studio 2005, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). - +> Visualizer and visualizer object source implementation is dependent upon the hosting debugger. For information on creating a visualizer for Visual Studio 2005, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). + ]]> @@ -140,11 +140,11 @@ The fully qualified type name of the visualizer. Initializes a new instance of the class, specifying the type name of the visualizer. - can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). - + can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). + ]]> @@ -198,11 +198,11 @@ The type of the visualizer. Initializes a new instance of the class, specifying the type of the visualizer. - can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). - + can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). + ]]> @@ -272,11 +272,11 @@ The fully qualified type name of the visualizer object source. Initializes a new instance of the class, specifying the type name of the visualizer and the type name of the visualizer object source. - can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). - + can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). + ]]> @@ -339,11 +339,11 @@ The type of the visualizer object source. Initializes a new instance of the class, specifying the type name of the visualizer and the type of the visualizer object source. - can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). - + can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). + ]]> @@ -413,11 +413,11 @@ The fully qualified type name of the visualizer object source. Initializes a new instance of the class, specifying the type of the visualizer and the type name of the visualizer object source. - can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). - + can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). + ]]> @@ -482,11 +482,11 @@ The type of the visualizer object source. Initializes a new instance of the class, specifying the type of the visualizer and the type of the visualizer object source. - can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). - + can be applied to assemblies, classes, and structures. For information on the use of this attribute, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). + ]]> @@ -627,11 +627,11 @@ Gets or sets the fully qualified type name when the attribute is applied at the assembly level. The fully qualified type name of the target type. - property of the target type. - + property of the target type. + ]]> @@ -685,13 +685,13 @@ Gets the fully qualified type name of the visualizer object source. The fully qualified type name of the visualizer object source. - property of the visualizer object source type. - - A visualizer object source created for Visual Studio should inherit from the Visual Studio class `VisualizerObjectSource` class. For information on creating a visualizer, see [Create Custom Visualizers of Data](/visualstudio/debugger/create-custom-visualizers-of-data). - + property of the visualizer object source type. + + A visualizer object source created for Visual Studio should inherit from the Visual Studio class `VisualizerObjectSource` class. For information on creating a visualizer, see [Create Custom Visualizers of Data](/visualstudio/debugger/create-custom-visualizers-of-data). + ]]> @@ -748,13 +748,13 @@ Gets the fully qualified type name of the visualizer. The fully qualified visualizer type name. - property for the visualizer type. - - For information on creating a visualizer, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). - + property for the visualizer type. + + For information on creating a visualizer, see [How to: Write a Visualizer](/visualstudio/debugger/create-custom-visualizers-of-data). + ]]> diff --git a/xml/System.Diagnostics/DefaultTraceListener.xml b/xml/System.Diagnostics/DefaultTraceListener.xml index 0ea5ff23efa..3edc546b676 100644 --- a/xml/System.Diagnostics/DefaultTraceListener.xml +++ b/xml/System.Diagnostics/DefaultTraceListener.xml @@ -67,7 +67,7 @@ The method, by default, displays a message box when the application is running in a user interface mode; it also emits the message using . > [!NOTE] -> The display of the message box for and method calls depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box for and method calls depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. You must enable tracing or debugging to use a trace listener. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -91,9 +91,9 @@ For .NET Framework apps, you can add a trace listener by editing the configurati ``` ## Examples - The following code example calculates binomial coefficients, which are values used in probability and statistics. This example uses a to trace results and log errors. It creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. + The following code example calculates binomial coefficients, which are values used in probability and statistics. This example uses a to trace results and log errors. It creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. - If an error is detected while processing the input parameter, or if the `CalcBinomial` function throws an exception, the method logs and displays an error message. If the property is `false`, the error message is also written to the console. When the result is calculated successfully, the and methods write the results to the log file. + If an error is detected while processing the input parameter, or if the `CalcBinomial` function throws an exception, the method logs and displays an error message. If the property is `false`, the error message is also written to the console. When the result is calculated successfully, the and methods write the results to the log file. The , , and methods cause trace information to be written only to the . To write trace information to all listeners in the collection, use the , , and methods of the class. @@ -209,7 +209,7 @@ For .NET Framework apps, you can add a trace listener by editing the configurati method to log an error message if the function throws an exception. If the property is `false`, the method also writes the error message to the console. + The following code example calls a function that calls the method to log an error message if the function throws an exception. If the property is `false`, the method also writes the error message to the console. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DefaultTraceListener/Overview/binomial.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DefaultTraceListener/Overview/binomial.vb" id="Snippet8"::: @@ -410,7 +410,7 @@ For .NET Framework apps, you can add a trace listener by editing the configurati , adds it to the collection, and sets the property to the log file specified in the command-line arguments. + The following code example creates a new , adds it to the collection, and sets the property to the log file specified in the command-line arguments. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/DefaultTraceListener/Overview/binomial.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/DefaultTraceListener/Overview/binomial.vb" id="Snippet4"::: @@ -551,7 +551,7 @@ For .NET Framework apps, you can add a trace listener by editing the configurati For information about the Win32 `OutputDebugString` debugging function, see the Platform SDK or MSDN. - This method sets the property to `true`. + This method sets the property to `true`. diff --git a/xml/System.Diagnostics/DelimitedListTraceListener.xml b/xml/System.Diagnostics/DelimitedListTraceListener.xml index a55cf0e6fc6..1a7798edb93 100644 --- a/xml/System.Diagnostics/DelimitedListTraceListener.xml +++ b/xml/System.Diagnostics/DelimitedListTraceListener.xml @@ -52,43 +52,43 @@ Directs tracing or debugging output to a text writer, such as a stream writer, or to a stream, such as a file stream. - property. The delimiter is used to terminate each field in a line of output. For example, to display the trace output in a Microsoft Excel spreadsheet, you might specify a comma (",") as a delimiter and create a comma-separated value (CSV) file. - + property. The delimiter is used to terminate each field in a line of output. For example, to display the trace output in a Microsoft Excel spreadsheet, you might specify a comma (",") as a delimiter and create a comma-separated value (CSV) file. + > [!IMPORTANT] -> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. +> This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a`try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. You can create a in your code. Alternatively, in .NET Framework apps only, you can enable or disable a through the application configuration file and then use the configured in your application. - + > [!NOTE] -> The delimits only text that is emitted by using the methods that have names starting with the word `Trace`, such as or . Trace data that is emitted by using the and methods is not delimited. - -To configure a in a .NET Framework app, edit the configuration file that corresponds to the name of your application. In this file, you can add a listener, set the properties for a listener, or remove a listener. The configuration file should be formatted as shown in the following example: - -```xml - - - - - - - - - -``` - +> The delimits only text that is emitted by using the methods that have names starting with the word `Trace`, such as or . Trace data that is emitted by using the and methods is not delimited. + +To configure a in a .NET Framework app, edit the configuration file that corresponds to the name of your application. In this file, you can add a listener, set the properties for a listener, or remove a listener. The configuration file should be formatted as shown in the following example: + +```xml + + + + + + + + + +``` + > [!NOTE] -> If you try to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. - +> If you try to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. + > [!NOTE] -> Listeners are intended to be used by methods of the , , and classes to write trace information. Listener methods, except for constructors, should not be called directly from application code. - +> Listeners are intended to be used by methods of the , , and classes to write trace information. Listener methods, except for constructors, should not be called directly from application code. + ]]> @@ -143,11 +143,11 @@ To configure a in a .NET Fr The to receive the output. Initializes a new instance of the class that writes to the specified output stream. - property to an empty string (""). - + property to an empty string (""). + ]]> @@ -194,11 +194,11 @@ To configure a in a .NET Fr The to receive the output. Initializes a new instance of the class that writes to the specified text writer. - property to an empty string (""). - + property to an empty string (""). + ]]> @@ -245,11 +245,11 @@ To configure a in a .NET Fr The name of the file to receive the output. Initializes a new instance of the class that writes to the specified file. - property to an empty string (""). - + property to an empty string (""). + ]]> @@ -306,15 +306,15 @@ To configure a in a .NET Fr The name of the new instance of the trace listener. Initializes a new instance of the class that writes to the specified output stream and has the specified name. - property to the value of the `name` parameter, or to an empty string ("") if the `name` parameter is `null`. The property can be used as an index into the `Listeners` collection to programmatically change the properties for the listener. For example, the following code sets the property for the instance of that has the name "delimListener": - -```csharp -((DelimitedListTraceListener)Trace.Listeners["delimListener"]).Delimiter = ":" -``` - + property to the value of the `name` parameter, or to an empty string ("") if the `name` parameter is `null`. The property can be used as an index into the `Listeners` collection to programmatically change the properties for the listener. For example, the following code sets the property for the instance of that has the name "delimListener": + +```csharp +((DelimitedListTraceListener)Trace.Listeners["delimListener"]).Delimiter = ":" +``` + ]]> @@ -371,15 +371,15 @@ To configure a in a .NET Fr The name of the new instance of the trace listener. Initializes a new instance of the class that writes to the specified text writer and has the specified name. - property to the value of the `name` parameter, or to an empty string ("") if the `name` parameter is `null`. The property can be used as an index into the `Listeners` collection to programmatically change the properties for the listener. For example the following code sets the property for the instance of that has the name "delimListener": - -```csharp -((DelimitedListTraceListener)Trace.Listeners["delimListener"]).Delimiter = ":" -``` - + property to the value of the `name` parameter, or to an empty string ("") if the `name` parameter is `null`. The property can be used as an index into the `Listeners` collection to programmatically change the properties for the listener. For example the following code sets the property for the instance of that has the name "delimListener": + +```csharp +((DelimitedListTraceListener)Trace.Listeners["delimListener"]).Delimiter = ":" +``` + ]]> @@ -428,20 +428,20 @@ To configure a in a .NET Fr The name of the new instance of the trace listener. Initializes a new instance of the class that writes to the specified file and has the specified name. - class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. - + class for the specified file on the specified path, using encoding. If the file exists, it is appended to. If the file does not exist, a new file is created. + > [!NOTE] -> To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. - - The property is set to the value of the `name` parameter, or to an empty string ("") if the `name` parameter is `null`. The property can be used as an index into the `Listeners` collection to programmatically change the properties for the listener. For example, the following code sets the property for the instance of that has the name "delimListener": - -```csharp -((DelimitedListTraceListener)Trace.Listeners["delimListener"]).Delimiter = ":" -``` - +> To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. + + The property is set to the value of the `name` parameter, or to an empty string ("") if the `name` parameter is `null`. The property can be used as an index into the `Listeners` collection to programmatically change the properties for the listener. For example, the following code sets the property for the instance of that has the name "delimListener": + +```csharp +((DelimitedListTraceListener)Trace.Listeners["delimListener"]).Delimiter = ":" +``` + ]]> @@ -488,32 +488,32 @@ To configure a in a .NET Fr Gets or sets the delimiter for the delimited list. The delimiter for the delimited list. - property using the `delimiter` attribute in a configuration file for a .NET Framework app: - -```xml - - - - - - - - - - - -``` - +The following configuration file example shows how to set the property using the `delimiter` attribute in a configuration file for a .NET Framework app: + +```xml + + + + + + + + + + + +``` + ]]> @@ -566,30 +566,30 @@ The following configuration file example shows how to set the Returns the custom configuration file attribute supported by the delimited trace listener. A string array that contains the single value "delimiter". - is used to set the property. - -The following .NET Framework application configuration file example shows the use of the `delimiter` attribute to set the property: - -```xml - - - - - - - - - - -``` - + is used to set the property. + +The following .NET Framework application configuration file example shows the use of the `delimiter` attribute to set the property: + +```xml + + + + + + + + + + +``` + ]]> @@ -663,14 +663,14 @@ The following .NET Framework application configuration file example shows the us A data object to write to the output file or stream. Writes trace information, a data object, and event information to the output file or stream. - property. - + property. + > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. - +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -741,14 +741,14 @@ The following .NET Framework application configuration file example shows the us An array of data objects to write to the output file or stream. Writes trace information, an array of data objects, and event information to the output file or stream. - property. - + property. + > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. - +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -822,14 +822,14 @@ The following .NET Framework application configuration file example shows the us The trace message to write to the output file or stream. Writes trace information, a message, and event information to the output file or stream. - property. - + property. + > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. - +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. + ]]> @@ -910,14 +910,14 @@ The following .NET Framework application configuration file example shows the us An array containing zero or more objects to format. Writes trace information, a formatted array of objects, and event information to the output file or stream. - method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer whose content depends on the value of the property. - + method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer whose content depends on the value of the property. + > [!IMPORTANT] -> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. - +> The method is not intended to be called by application code. It is called by methods of the , , and classes to write trace data. + ]]> diff --git a/xml/System.Diagnostics/EventInstance.xml b/xml/System.Diagnostics/EventInstance.xml index 9b6c49197b9..c75fc76c96a 100644 --- a/xml/System.Diagnostics/EventInstance.xml +++ b/xml/System.Diagnostics/EventInstance.xml @@ -36,9 +36,9 @@ to write an event log entry with a resource identifier rather than a string value. To write an event log entry, initialize the property and pass the instance to the method. The Event Viewer uses the instance identifier to find and display the corresponding string from the localized resource file based on current language settings. You must register the event source with the corresponding resource file before you write events using resource identifiers. + Use to write an event log entry with a resource identifier rather than a string value. To write an event log entry, initialize the property and pass the instance to the method. The Event Viewer uses the instance identifier to find and display the corresponding string from the localized resource file based on current language settings. You must register the event source with the corresponding resource file before you write events using resource identifiers. - When writing events, you can set the property to specify the icon that the Event Viewer displays for the entry. You can also specify a property to specify the category that the Event Viewer displays for the entry. + When writing events, you can set the property to specify the icon that the Event Viewer displays for the entry. You can also specify a property to specify the category that the Event Viewer displays for the entry. The Event Viewer uses the category to filter events written by an event source. The Event Viewer can display the category as a numeric value, or it can use the category as a resource identifier to display a localized category string. @@ -54,7 +54,7 @@ ## Examples The following code example writes an informational event entry, and then reuses the to write an entry for a warning event to an existing event log. The event message text is specified using a resource identifier in a message resource file. The code example assumes that the corresponding message resource file has been registered for the source. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventInstance/Overview/source.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventInstance/Overview/source.vb" id="Snippet9"::: @@ -223,7 +223,7 @@ SVC_UPDATE.EXE and pass it to the method. Set the `instanceId` to the resource identifier of the event message in the corresponding property for the source. Set the `categoryId` to a numeric category value, or the resource identifier of the event category in the property for the source; set the `categoryId` to zero for no event category. The property for the new instance is set to by default. + To write an informational entry to an event log, initialize an and pass it to the method. Set the `instanceId` to the resource identifier of the event message in the corresponding property for the source. Set the `categoryId` to a numeric category value, or the resource identifier of the event category in the property for the source; set the `categoryId` to zero for no event category. The property for the new instance is set to by default. The Event Viewer uses the resource identifiers to display the corresponding strings from the localized resource files for the source. You must register the source with the corresponding resource files before you can write events using resource identifiers. @@ -400,7 +400,7 @@ SVC_UPDATE.EXE and pass it to the method. Set the `instanceId` to the resource identifier of the event message in the corresponding property for the source. Set the `categoryId` to a numeric category value, or the resource identifier of the event category in the property for the source; set the `categoryId` to zero for no event category. + To write an entry to an event log, initialize an and pass it to the method. Set the `instanceId` to the resource identifier of the event message in the corresponding property for the source. Set the `categoryId` to a numeric category value, or the resource identifier of the event category in the property for the source; set the `categoryId` to zero for no event category. The Event Viewer uses the resource identifiers to display the corresponding strings from the localized resource files for the source. You must register the source with the corresponding resource files before you can write events using resource identifiers. @@ -587,11 +587,11 @@ SVC_UPDATE.EXE ## Remarks Event log categories are application-defined values that help filter events, or provide further information about the event. For example, your application can define separate categories for different components or different operations. - Set the property to specify the category that the Event Viewer displays for the entry. The Event Viewer can display the category as a numeric value, or it can use the as a resource identifier to display a localized category string based on the current language settings. + Set the property to specify the category that the Event Viewer displays for the entry. The Event Viewer can display the category as a numeric value, or it can use the as a resource identifier to display a localized category string based on the current language settings. To display localized category strings in the Event Viewer, you must use an event source configured with a category resource file, and set the to a resource identifier in the category resource file. If the event source does not have a configured category resource file, or the specified does not index a string in the category resource file, and then the Event Viewer displays the numeric category value for that entry. - You must register the source with the corresponding resource file before you write event categories using resource identifiers. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. When defining category strings in a resource file, the category resource identifiers must be numbered consecutively starting at 1, up to the configured property value. + You must register the source with the corresponding resource file before you write event categories using resource identifiers. Configure the category resource file, along with the number of category strings in the resource file, using the or the class. When defining category strings in a resource file, the category resource identifiers must be numbered consecutively starting at 1, up to the configured property value. Event categories are optional. If your application does not use categories, do not set the for the event log entry. @@ -940,7 +940,7 @@ SVC_UPDATE.EXE property uniquely identifies an event entry for a configured event source. For events defined in message resource files, the corresponds to the resource identifier compiled from the message definition fields in the message text file. Your application can write localized event log entries by setting the to a resource identifier. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You must register the source with the corresponding resource file before you write events using resource identifiers. + The property uniquely identifies an event entry for a configured event source. For events defined in message resource files, the corresponds to the resource identifier compiled from the message definition fields in the message text file. Your application can write localized event log entries by setting the to a resource identifier. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You must register the source with the corresponding resource file before you write events using resource identifiers. For details about defining event messages and building event log resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. For details about event log identifiers, see the [Event Identifiers](/windows/win32/eventlog/event-categories) article in the Platform SDK documentation. diff --git a/xml/System.Diagnostics/EventLog.xml b/xml/System.Diagnostics/EventLog.xml index 8ebf9e122c0..07a38def534 100644 --- a/xml/System.Diagnostics/EventLog.xml +++ b/xml/System.Diagnostics/EventLog.xml @@ -82,9 +82,9 @@ You can use to create custom event logs that you can view through the server's Event Viewer. Use the method to display a localized name for your event log in the Event Viewer. Use the method to configure the behavior of your event log when it reaches its maximum log size. - To read from an event log, specify the log name ( property) and server computer name ( property for the event log. If you don't specify the server computer name, the local computer, ".", is assumed. It's not necessary to specify the event source ( property), because a source is required only for writing to logs. The property is automatically populated with the event log's list of entries. + To read from an event log, specify the log name ( property) and server computer name ( property for the event log. If you don't specify the server computer name, the local computer, ".", is assumed. It's not necessary to specify the event source ( property), because a source is required only for writing to logs. The property is automatically populated with the event log's list of entries. - To write to an event log, specify or create an event source ( property). You must have administrative credentials on the computer to create a new event source. The event source registers your application with the event log as a valid source of entries. You can use the event source to write to only one log at a time. The property can be any random string, but the name must be distinct from other sources on the computer. The event source is typically the name of the application or another identifying string. Trying to create a duplicate value throws an exception. However, a single event log can be associated with multiple sources. + To write to an event log, specify or create an event source ( property). You must have administrative credentials on the computer to create a new event source. The event source registers your application with the event log as a valid source of entries. You can use the event source to write to only one log at a time. The property can be any random string, but the name must be distinct from other sources on the computer. The event source is typically the name of the application or another identifying string. Trying to create a duplicate value throws an exception. However, a single event log can be associated with multiple sources. If the event source for the event log associated with the instance doesn't exist, a new event source is created. To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative credentials. @@ -93,7 +93,7 @@ > [!IMPORTANT] > Creating or deleting an event source requires synchronization of the underlying code by using a named mutex. If a highly privileged application locks the named mutex, trying to create or delete an event source causes the application to stop responding until the lock is released. To help prevent this problem, never grant permission to untrusted code. In addition, permission potentially allows other permissions to be bypassed and should only be granted to highly trusted code. - Applications and services should write to the Application log or to a custom log. Device drivers should write to the System log. If you do not explicitly set the property, the event log defaults to the Application log. + Applications and services should write to the Application log or to a custom log. Device drivers should write to the System log. If you do not explicitly set the property, the event log defaults to the Application log. > [!NOTE] > There is nothing to protect an application from writing as any registered source. If an application is granted permission, it can write events for any valid source registered on the computer. @@ -187,7 +187,7 @@ , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. + Before calling , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. > [!NOTE] > If you do not specify a , the local computer (".") is assumed. @@ -261,12 +261,12 @@ property to the `logName` parameter. Before calling , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. + This overload sets the property to the `logName` parameter. Before calling , specify the property of the instance. If you are only reading from the log, you can alternatively specify only the and properties. > [!NOTE] -> If you do not specify a , the local computer (".") is assumed. This overload of the constructor specifies the property, but you can change this before reading the property. +> If you do not specify a , the local computer (".") is assumed. This overload of the constructor specifies the property, but you can change this before reading the property. - If the source you specify in the property is unique from other sources on the computer, a subsequent call to creates a log with the specified name, if it does not already exist. + If the source you specify in the property is unique from other sources on the computer, a subsequent call to creates a log with the specified name, if it does not already exist. The following table shows initial property values for an instance of . @@ -341,10 +341,10 @@ property to the `logName` parameter and the property to the `machineName` parameter. Before calling , specify the property of the . If you are only reading from the log, you can alternatively specify only the and properties. + This overload sets the property to the `logName` parameter and the property to the `machineName` parameter. Before calling , specify the property of the . If you are only reading from the log, you can alternatively specify only the and properties. > [!NOTE] -> This overload of the constructor specifies the and properties, but you can change either before reading the property. +> This overload of the constructor specifies the and properties, but you can change either before reading the property. The following table shows initial property values for an instance of . @@ -419,7 +419,7 @@ property to the `logName` parameter, the property to the `machineName` parameter, and the property to the `source` parameter. The property is required when writing to an event log. However, if you are only reading from an event log, only the and properties are required (as long as the event log on the server has a source already associated with it). If you are only reading from the event log, another overload of the constructor might suffice. + This constructor sets the property to the `logName` parameter, the property to the `machineName` parameter, and the property to the `source` parameter. The property is required when writing to an event log. However, if you are only reading from an event log, only the and properties are required (as long as the event log on the server has a source already associated with it). If you are only reading from the event log, another overload of the constructor might suffice. The following table shows initial property values for an instance of . @@ -660,7 +660,7 @@ ## Remarks Use this overload to configure a new source for writing entries to an event log on the local computer or a remote computer. It is not necessary to use this method to read from an event log. - The method uses the input `sourceData` , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. If the property is not set, the source is registered for the Application event log. If the is not set, the source is registered on the local computer. + The method uses the input `sourceData` , and properties to create registry values on the target computer for the new source and its associated event log. A new source name cannot match an existing source name or an existing event log name on the target computer. If the property is not set, the source is registered for the Application event log. If the is not set, the source is registered on the local computer. > [!NOTE] > To create an event source in Windows Vista and later or Windows Server 2003, you must have administrative privileges. @@ -675,7 +675,7 @@ You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. Each source can only write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. @@ -917,7 +917,7 @@ SVC_UPDATE.EXE You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. @@ -1052,7 +1052,7 @@ SVC_UPDATE.EXE You can create an event source for an existing event log or a new event log. When you create a new source for a new event log, the system registers the source for that log, but the log is not created until the first entry is written to it. - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. The source must be unique on the local computer; a new source name cannot match an existing source name or an existing event log name. Each source can write to only one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. @@ -1570,7 +1570,7 @@ SVC_UPDATE.EXE property determines whether the raises events when entries are written to the log. When the property is `true`, components that receive the event will receive notification any time an entry is written to the log that is specified in the property. If is `false`, no events are raised. + The property determines whether the raises events when entries are written to the log. When the property is `true`, components that receive the event will receive notification any time an entry is written to the log that is specified in the property. If is `false`, no events are raised. > [!NOTE] > You can receive event notifications only when entries are written on the local computer. You cannot receive notifications for entries written on remote computers. @@ -1691,7 +1691,7 @@ SVC_UPDATE.EXE It is not necessary to specify a when only reading from a log. You can specify only the name and (server computer name) properties for the instance. In either case, the member is automatically populated with the event log's list of entries. You can select the appropriate index for an item in this list to read individual entries. - An important distinction between reading and writing log entries is that it is not necessary to explicitly call a read method. After the and are specified, the property is automatically populated. If you change the value of the or property, the property is repopulated the next time you read it. + An important distinction between reading and writing log entries is that it is not necessary to explicitly call a read method. After the and are specified, the property is automatically populated. If you change the value of the or property, the property is repopulated the next time you read it. > [!NOTE] > You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer, ".", is assumed. @@ -2133,23 +2133,23 @@ SVC_UPDATE.EXE > [!NOTE] > Log names are limited to eight characters. According to the system, MyLogSample1 and MyLogSample2 are the same log. - If you write to an event log, it is not enough to specify the property. You must associate a property with your event log resource to connect it to a particular log. It is not necessary to specify a when only reading from a log, but an event source must be associated with the event log resource in the server's registry. You can specify only the name and (server computer name) to read from it. + If you write to an event log, it is not enough to specify the property. You must associate a property with your event log resource to connect it to a particular log. It is not necessary to specify a when only reading from a log, but an event source must be associated with the event log resource in the server's registry. You can specify only the name and (server computer name) to read from it. > [!NOTE] > You are not required to specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. - If the property has not been specified, a call to returns an empty string if has not been explicitly set (by setting the property, or through the constructor). If the has been specified, returns the name of the log to which that source was registered. + If the property has not been specified, a call to returns an empty string if has not been explicitly set (by setting the property, or through the constructor). If the has been specified, returns the name of the log to which that source was registered. - A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property after the property has been set, writing a log entry throws an exception. + A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property after the property has been set, writing a log entry throws an exception. - The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. - You cannot create a new log using the property alone (without specifying a source for the log). You can call , passing in a new log name as a parameter, and then call . However, the intent is usually either to create (and write entries to) new application-specific logs, or to read from existing logs. + You cannot create a new log using the property alone (without specifying a source for the log). You can call , passing in a new log name as a parameter, and then call . However, the intent is usually either to create (and write entries to) new application-specific logs, or to read from existing logs. If the value changes, the event log is closed and all event handles are released. > [!CAUTION] -> If you set the property to the name of a log that does not exist, the system attaches the to the Application log, but does not warn you that it is using a log other than the one you specified. +> If you set the property to the name of a log that does not exist, the system attaches the to the Application log, but does not warn you that it is using a log other than the one you specified. @@ -2276,7 +2276,7 @@ SVC_UPDATE.EXE ## Remarks The event source indicates what logs the event. It is often the name of the application, or the name of a subcomponent of the application, if the application is large. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. - When you create a new source, which can only write to one log at a time, the system registers your application with the event log as a valid source of entries. The property can be any string, but the name cannot be used by other sources on the computer. An attempt to create a duplicated value throws an exception. However, a single event log can have many different sources writing to it. + When you create a new source, which can only write to one log at a time, the system registers your application with the event log as a valid source of entries. The property can be any string, but the name cannot be used by other sources on the computer. An attempt to create a duplicated value throws an exception. However, a single event log can have many different sources writing to it. @@ -2355,12 +2355,12 @@ SVC_UPDATE.EXE with your event log object to connect it to a particular log. It is not necessary to specify the property when only reading from a log. You can specify only the name and (server computer name). + If you write to an event log, you must associate a with your event log object to connect it to a particular log. It is not necessary to specify the property when only reading from a log. You can specify only the name and (server computer name). > [!NOTE] > You need not specify the if you are connecting to a log. If you do not specify the , the local computer (".") is assumed. - A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property, the closes all handles and reattaches to the log and source on the new computer. + A source can only be registered to one log at a time. If the property was set for an instance of , you cannot change the property for that without changing the value of or calling first. If you change the property, the closes all handles and reattaches to the log and source on the new computer. The value cannot be an empty string. If it is not explicitly set, it defaults to the local computer ("."). @@ -2434,7 +2434,7 @@ SVC_UPDATE.EXE property represents the size limit of the event log file. When the event log reaches the size limit, the configured value determines whether new entries are discarded, or whether new entries overwrite older entries. + The property represents the size limit of the event log file. When the event log reaches the size limit, the configured value determines whether new entries are discarded, or whether new entries overwrite older entries. > [!NOTE] > This property represents a configuration setting for the event log represented by this instance. When the event log reaches its maximum size, this property specifies how the operating system handles new entries written by all event sources registered for the event log. @@ -2506,7 +2506,7 @@ SVC_UPDATE.EXE ## Remarks > [!IMPORTANT] -> Support for the property was removed in Windows Vista and later operating systems. Setting this value can cause the Event Log to never overwrite events, and to drop all events to the channel once it is full. +> Support for the property was removed in Windows Vista and later operating systems. Setting this value can cause the Event Log to never overwrite events, and to drop all events to the channel once it is full. ## Examples The following example enumerates the event logs defined on the local computer, and displays configuration details for each event log. @@ -2572,7 +2572,7 @@ SVC_UPDATE.EXE > [!NOTE] > The overflow behavior takes effect only when an event log reaches its maximum file size. The overflow behavior does not affect writing a new entry to a log that can accommodate additional event log entries. - The method configures the overflow behavior of an event log. instance. After calling this method for the event log specified by the property, the and property values reflect the newly configured overflow behavior. + The method configures the overflow behavior of an event log. instance. After calling this method for the event log specified by the property, the and property values reflect the newly configured overflow behavior. > [!NOTE] > This property represents a configuration setting for the event log represented by this instance. When the event log reaches its maximum size, this property specifies how the operating system handles new entries written by all event sources registered for the event log. @@ -2655,9 +2655,9 @@ SVC_UPDATE.EXE property defines the maximum number of kilobytes allowed for the event log file size. + Event logs grow in size as new events are written to them. Each event log has a configured maximum size limit; the property defines the maximum number of kilobytes allowed for the event log file size. - Use the property value to examine the configured overflow behavior for an event log at its maximum size. Use the method to change the overflow behavior for an event log. + Use the property value to examine the configured overflow behavior for an event log at its maximum size. Use the method to change the overflow behavior for an event log. > [!NOTE] > The overflow behavior takes effect only when an event log reaches its maximum file size. The overflow behavior does not affect writing a new entry to a log that can accommodate additional event log entries. @@ -2938,7 +2938,7 @@ SVC_UPDATE.EXE ## Remarks The event source indicates what logs the event. It is often the name of the application, or the name of a subcomponent of the application, if the application is large. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. - You only need to specify an event source if you are writing to an event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the property to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . + You only need to specify an event source if you are writing to an event log. Before writing an entry to an event log, you must register the event source with the event log as a valid source of events. When you write a log entry, the system uses the property to find the appropriate log in which to place your entry. If you are reading the event log, you can either specify the , or a and . > [!NOTE] > You are not required to specify the if you are connecting to a log on the local computer. If you do not specify the , the local computer (".") is assumed. @@ -3210,7 +3210,7 @@ SVC_UPDATE.EXE When the event is handled by a visual Windows Forms component, such as a button, accessing the component through the system thread pool might not work, or might result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods handling the event 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, is automatically set to the control containing the . For example, if you place an on a designer for Form1 (which inherits from ) the property of is set to the instance of Form1. + If the is used inside Visual Studio 2005 in a Windows Forms designer, is automatically set to the control containing the . For example, if you place an on a designer for Form1 (which inherits from ) the property of is set to the instance of Form1. ]]> @@ -3277,16 +3277,16 @@ SVC_UPDATE.EXE > [!NOTE] > The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. + You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] > If you do not specify a for your instance before you call or , the local computer (".") is assumed. - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] > Many of the exceptions listed above are generated by errors raised during the process of registering the . @@ -3389,16 +3389,16 @@ SVC_UPDATE.EXE > [!NOTE] > The `message` string cannot contain %*n*, where *n* is an integer value (for example, %1), because the event viewer treats it as an insertion string. Because an Internet Protocol, version 6 (IPv6) address can contain this character sequence, you cannot log an event message that contains an IPv6 address. - You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. + You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] > If you do not specify a for your instance before you call or , the local computer (".") is assumed. - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] > Many exceptions listed above are generated by errors raised during the process of registering the . @@ -3597,16 +3597,16 @@ SVC_UPDATE.EXE In addition to the event identifier, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. + You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] > If you do not specify a for your instance before you call or , the local computer (".") is assumed. - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] > Many exceptions listed above are generated by errors raised during the process of registering the . @@ -3825,16 +3825,16 @@ SVC_UPDATE.EXE Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. + You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] > If you do not specify a for your instance before you call or , the local computer (".") is assumed. - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] > Many exceptions listed above are generated by errors raised during the process of registering the . @@ -4057,16 +4057,16 @@ SVC_UPDATE.EXE Finally, you can specify an for the event being written to the event log. The `type` is indicated by an icon and text in the Type column in the Event Viewer for a log. This parameter indicates whether the event type is error, warning, information, success audit, or failure audit. - You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. + You must set the property on your component before you can write entries to the log. You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. - If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. + If the source specified in the property of this instance is not registered on the computer that your component is writing to, calls and registers the source. > [!NOTE] > If you do not specify a for your instance before you call or , the local computer (".") is assumed. - If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. + If the system needs to register the through a call to and the property has not been set on your instance, the log defaults to the Application log. > [!NOTE] > Many exceptions listed above are generated by errors raised during the process of registering the . @@ -4415,7 +4415,7 @@ SVC_UPDATE.EXE The input `instance` instance specifies the event message and properties. Set the of the `instance` input for the defined message in the source message resource file. You can optionally set the and of the `instance` input to define the category and event type of your event entry. You can also specify an array of language-independent strings to insert into the localized message text. Set `values` to `null` if the event message does not contain formatting placeholders for replacement strings. - You must set the property on your component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. + You must set the property on your component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. @@ -4643,7 +4643,7 @@ SVC_UPDATE.EXE Specify binary data with an event when it is necessary to provide additional details for the event. For example, use the `data` parameter to include information on a specific error. The Event Viewer does not interpret the associated event data; it displays the data in a combined hexadecimal and text format. Use event-specific data sparingly; include it only if you are sure it will be useful. You can also use event-specific data to store information the application can process independently of the Event Viewer. For example, you could write a viewer specifically for your events, or write a program that scans the event log and creates reports that include information from the event-specific data. - You must set the property on your component before component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. + You must set the property on your component before component before using . The specified source must be configured for writing localized entries to the log; the source must at minimum have a message resource file defined. You must create and configure the event source before writing the first entry with the source. Create the new event source during the installation of your application. This allows time for the operating system to refresh its list of registered event sources and their configuration. If the operating system has not refreshed its list of event sources, and you attempt to write an event with the new source, the write operation will fail. You can configure a new source using an , or using the method. You must have administrative rights on the computer to create a new event source. diff --git a/xml/System.Diagnostics/EventLogEntry.xml b/xml/System.Diagnostics/EventLogEntry.xml index 8aad9e2b44c..10fd6aef37c 100644 --- a/xml/System.Diagnostics/EventLogEntry.xml +++ b/xml/System.Diagnostics/EventLogEntry.xml @@ -65,7 +65,7 @@ ## Examples The following code example demonstrates the use of the class. In this example, a `switch` statement uses console input to search for event log entries for the specified event type. If a match is found, log entry source information is displayed at the console. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogEntry/Overview/eventlogentry_source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogEntry/Overview/eventlogentry_source.vb" id="Snippet1"::: @@ -169,7 +169,7 @@ property. The Event Viewer can display the category as a numeric value, or it can use the category as a resource identifier to display a localized category string. For more information, see . + Each application (event source) can define its own numbered categories and the text strings to which they are mapped. The Event Viewer can use the category to filter events in the log. The categories must be numbered consecutively beginning with the number 1. The category number is specified by the property. The Event Viewer can display the category as a numeric value, or it can use the category as a resource identifier to display a localized category string. For more information, see . ]]> @@ -273,7 +273,7 @@ ## Examples - The following code example demonstrates the use of the property. In this example, a `switch` statement uses console input to search for event log entries for the specified . If a match is found, log entry source information is displayed at the console. + The following code example demonstrates the use of the property. In this example, a `switch` statement uses console input to search for event log entries for the specified . If a match is found, log entry source information is displayed at the console. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogEntry/Overview/eventlogentry_source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogEntry/Overview/eventlogentry_source.vb" id="Snippet1"::: @@ -385,9 +385,9 @@ property for an event log entry represents the full 32-bit resource identifier for the event in the message resource file for the event source. Two event log entries from the same source can have matching values, but have different values due to differences in the top two bits of the event identifier. + This value represents the event identifier for the entry in the event log, with the top two bits masked off. The property for an event log entry represents the full 32-bit resource identifier for the event in the message resource file for the event source. Two event log entries from the same source can have matching values, but have different values due to differences in the top two bits of the event identifier. - If the application wrote the event entry using one of the methods, the property matches the optional `eventId` parameter. If the application wrote the event using or the Windows API `ReportEvent`, the property matches the resource identifier for the event, with the top two bits masked off. + If the application wrote the event entry using one of the methods, the property matches the optional `eventId` parameter. If the application wrote the event using or the Windows API `ReportEvent`, the property matches the resource identifier for the event, with the top two bits masked off. ]]> @@ -487,9 +487,9 @@ property uniquely identifies an event entry for a configured event source. The for an event log entry represents the full 32-bit resource identifier for the event in the message resource file for the event source. The property equals the with the top two bits masked off. Two event log entries from the same source can have matching values, but have different values due to differences in the top two bits of the resource identifier. + The property uniquely identifies an event entry for a configured event source. The for an event log entry represents the full 32-bit resource identifier for the event in the message resource file for the event source. The property equals the with the top two bits masked off. Two event log entries from the same source can have matching values, but have different values due to differences in the top two bits of the resource identifier. - If the application wrote the event entry using one of the methods, the property matches the optional `eventId` parameter. If the application wrote the event using , the property matches the resource identifier specified in the of the `instance` parameter. If the application wrote the event using the Windows API `ReportEvent`, the property matches the resource identifier specified in the `dwEventID` parameter. + If the application wrote the event entry using one of the methods, the property matches the optional `eventId` parameter. If the application wrote the event using , the property matches the resource identifier specified in the of the `instance` parameter. If the application wrote the event using the Windows API `ReportEvent`, the property matches the resource identifier specified in the `dwEventID` parameter. For details about defining event messages and building event log resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. For details about event log identifiers, see the [Event Identifiers](/windows/win32/eventlog/event-categories) article in the Platform SDK documentation. @@ -653,9 +653,9 @@ property. + This property retrieves only the replacement strings for the entry. To retrieve the full message, read the property. - The property contains the localized versions of replacement strings that are used in the event log entry. If you provide resource files that contain strings in each target language for your application, you can emit event log messages in the language that is used on that computer. To do that, create an instance of the class for the resource assembly that contains your replacement strings. The first parameter of the constructor identifies the resource assembly to be used. Use the method of that instance to supply localized messages for log events. The following code automatically sets the message to the language for the current culture. + The property contains the localized versions of replacement strings that are used in the event log entry. If you provide resource files that contain strings in each target language for your application, you can emit event log messages in the language that is used on that computer. To do that, create an instance of the class for the resource assembly that contains your replacement strings. The first parameter of the constructor identifies the resource assembly to be used. Use the method of that instance to supply localized messages for log events. The following code automatically sets the message to the language for the current culture. ```csharp ResourceManager LocRM = new ResourceManager("ReplacementStrings.TestStrings", @@ -719,7 +719,7 @@ e1.WriteEntry(LocRM.GetString("strMessage"), ## Examples - The following code example demonstrates the use of the property. In this example, a `switch` statement uses console input to search for event log entries for the specified . If a match is found, the property information is displayed at the console. + The following code example demonstrates the use of the property. In this example, a `switch` statement uses console input to search for event log entries for the specified . If a match is found, the property information is displayed at the console. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogEntry/Overview/eventlogentry_source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogEntry/Overview/eventlogentry_source.vb" id="Snippet1"::: @@ -814,7 +814,7 @@ e1.WriteEntry(LocRM.GetString("strMessage"), property. + This member holds the time that an event was generated. This might not be the same as the time when the event information was written to the event log. For the latter, read the property. There is usually a lag between the time that an event is generated and the time it is logged. It is more important to know when the event was generated, unless you want to see if there is a significant lag in logging. That can happen if your log files are on a different server and you are experiencing a bottleneck. @@ -865,7 +865,7 @@ e1.WriteEntry(LocRM.GetString("strMessage"), property. + This member holds the time that an event's information is written to the event log. This might not be the same time as when the event was generated. For the latter, read the property. ]]> diff --git a/xml/System.Diagnostics/EventLogEntryCollection.xml b/xml/System.Diagnostics/EventLogEntryCollection.xml index 2f0a449bafe..48bdf4b9aa2 100644 --- a/xml/System.Diagnostics/EventLogEntryCollection.xml +++ b/xml/System.Diagnostics/EventLogEntryCollection.xml @@ -44,7 +44,7 @@ class when reading the entries associated with an instance. The property of the class is a collection of all the entries in the event log. + Use the class when reading the entries associated with an instance. The property of the class is a collection of all the entries in the event log. Because new entries are appended to the existing list, stepping through the collection enables you to access the entries that were created after you originally created the . However, after you view the entire list, it is not updated with new entries. @@ -52,7 +52,7 @@ ## Examples The following example demonstrates how to obtain event log information from an object. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogEntryCollection/Overview/eventlogentry_copyto.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogEntryCollection/Overview/eventlogentry_copyto.vb" id="Snippet1"::: @@ -157,12 +157,12 @@ represents a dynamic list of all the entries in a log. Therefore, the property can change during the lifetime of the instance that you create. It is usually best to work with the property directly instead of assigning its value to a variable. + An represents a dynamic list of all the entries in a log. Therefore, the property can change during the lifetime of the instance that you create. It is usually best to work with the property directly instead of assigning its value to a variable. ## Examples - The following example demonstrates how to use the property to iterate through an object. + The following example demonstrates how to use the property to iterate through an object. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogEntryCollection/Count/eventlogentry_item.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogEntryCollection/Count/eventlogentry_item.vb" id="Snippet1"::: @@ -215,7 +215,7 @@ The object that is returned by the method is a wrapper for the class that implements the enumerator. > [!NOTE] -> If the collection is changed during the iteration, the iteration is terminated. To avoid this possibility, see the property for an alternative technique for iterating through a collection. +> If the collection is changed during the iteration, the iteration is terminated. To avoid this possibility, see the property for an alternative technique for iterating through a collection. ]]> @@ -261,7 +261,7 @@ objects are indexed by the event log system according to the chronological order in which they arrived in the event log. Use the property to select a specific event log entry whose index in the collection is known. + objects are indexed by the event log system according to the chronological order in which they arrived in the event log. Use the property to select a specific event log entry whose index in the collection is known. Iterating through the instance steps through each object sequentially. The collection is dynamic and the number of entries may not be immutable when you enter the loop. Therefore, you should use a `for each...next` loop instead of a `for(int i=0; i instance to examine the entire set of entries. @@ -413,7 +413,7 @@ class, the property always returns the current . + For the class, the property always returns the current . ]]> diff --git a/xml/System.Diagnostics/EventLogInstaller.xml b/xml/System.Diagnostics/EventLogInstaller.xml index 69c25a6b01a..66300f5ccde 100644 --- a/xml/System.Diagnostics/EventLogInstaller.xml +++ b/xml/System.Diagnostics/EventLogInstaller.xml @@ -28,7 +28,7 @@ > [!NOTE] > The Security log is read-only. - The installer creates the event source that you specify in the property and registers it for the event log specified in property. This behavior is similar to calling on the component. + The installer creates the event source that you specify in the property and registers it for the event log specified in property. This behavior is similar to calling on the component. Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. @@ -40,9 +40,9 @@ When the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool) is called, it looks at the . If it is `true`, the tool installs all the items in the collection that are associated with your project installer. If is `false`, the tool ignores the project installer. - You modify other properties of an either before or after adding the instance to the collection of your project installer, but before the installer tool runs. You must set the property if your application will be writing to the event log. + You modify other properties of an either before or after adding the instance to the collection of your project installer, but before the installer tool runs. You must set the property if your application will be writing to the event log. - Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. + Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. You can register the event source with localized resource files for your event category and message strings. Your application can write event log entries using resource identifiers, rather than specifying the actual string. The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. You can register a separate file for event categories, messages, and parameter insertion strings, or you can register the same resource file for all three types of strings. Use the , , , and properties to configure the source to write localized entries to the event log. If your application writes strings values directly to the event log, you do not need to set these properties. @@ -457,7 +457,7 @@ SVC_UPDATE.EXE Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). is used by Installutil.exe to set the property values for the to the values of an existing . - If the of the that is passed in is an empty string (""), you must set the property to a valid value before the installer executes. + If the of the that is passed in is an empty string (""), you must set the property to a valid value before the installer executes. ]]> @@ -495,13 +495,13 @@ SVC_UPDATE.EXE method writes event log information to the registry, and associates the event log with a log that is specified by the property. If the log does not already exist (and a source is specified), creates a log and associates the new source with it. + The method writes event log information to the registry, and associates the event log with a log that is specified by the property. If the log does not already exist (and a source is specified), creates a log and associates the new source with it. Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). The tool automatically calls the method during the installation process to write registry information that is associated with the event log being installed. Installation is transactional, so if there is a failure of any installation project component during the installation, all the previously-installed components are rolled back to their pre-installation states. This is accomplished by calling each component's method. - Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method skips registering the source if the property matches a source name that is already registered for the same event log specified in the property. + Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method skips registering the source if the property matches a source name that is already registered for the same event log specified in the property. - An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the tool installs each . Usually, it is not necessary for your code to explicitly modify this state information. + An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the tool installs each . Usually, it is not necessary for your code to explicitly modify this state information. ]]> @@ -585,13 +585,13 @@ SVC_UPDATE.EXE property to associate the source you specify in the property with either an existing log or a new log on the local computer. The [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool) uses this information to map the source to the log in the computer's registry. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. + You can use the property to associate the source you specify in the property with either an existing log or a new log on the local computer. The [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool) uses this information to map the source to the log in the computer's registry. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. - To write entries to an event log, you must create a source and register it with an event log. An event source can only write to one log at a time. The installer uses the value of the property to register your application with the event log as a valid source of entries. If you do not specify a log name before the installer runs, the installer registers your source to the Application log. If you specify a new source and an existing log, the installer creates a new event source and associates it with the log you specify. If you specify both a new source and a new log, the installer associates the new source with the new log in the registry, but the log is not created until the first entry is written to it. + To write entries to an event log, you must create a source and register it with an event log. An event source can only write to one log at a time. The installer uses the value of the property to register your application with the event log as a valid source of entries. If you do not specify a log name before the installer runs, the installer registers your source to the Application log. If you specify a new source and an existing log, the installer creates a new event source and associates it with the log you specify. If you specify both a new source and a new log, the installer associates the new source with the new log in the registry, but the log is not created until the first entry is written to it. - The operating system stores event logs as files. When you use or the method to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or the method to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. - Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. + Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. For more detailed information about the behaviors of event logs and sources, see the class documentation for the and properties. @@ -646,15 +646,15 @@ SVC_UPDATE.EXE property to configure an event log source to write localized event messages. Event messages are application-defined strings that describe the event to the user. + Use the property to configure an event log source to write localized event messages. Event messages are application-defined strings that describe the event to the user. Your application can write event log entries using resource identifiers. A resource identifier indexes a message located in the . The Event Viewer uses the resource identifier to find and display the corresponding string from the localized resource file based on current language settings. The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. - If your application writes event message strings directly, rather than using a resource identifier in a localized resource file, do not set the property. + If your application writes event message strings directly, rather than using a resource identifier in a localized resource file, do not set the property. - If the property is not the local computer identifier ("."), the .NET Framework assumes that the resource file is on a remote computer. If the property value contains a drive letter, the resource file is assumed to be on the \\\\\\\\$ share (for example, \\\server\c\\$). If the value contains the string %systemroot%, the resource file is assumed to be on the \\\\\admin\\$ share (for example, \\\server\admin\\$). + If the property is not the local computer identifier ("."), the .NET Framework assumes that the resource file is on a remote computer. If the property value contains a drive letter, the resource file is assumed to be on the \\\\\\\\$ share (for example, \\\server\c\\$). If the value contains the string %systemroot%, the resource file is assumed to be on the \\\\\admin\\$ share (for example, \\\server\admin\\$). For details about defining event messages and building event resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. @@ -827,7 +827,7 @@ SVC_UPDATE.EXE property to configure an event log source to write localized event messages with inserted parameter strings. Each localized event message specified in the property can contain placeholders for insertion strings. These placeholders are used to specify the position and resource identifier for a language-independent string within the event message. The Event Viewer replaces the placeholders with the corresponding strings from the and formats the event log message for the localized event entry. + Use the property to configure an event log source to write localized event messages with inserted parameter strings. Each localized event message specified in the property can contain placeholders for insertion strings. These placeholders are used to specify the position and resource identifier for a language-independent string within the event message. The Event Viewer replaces the placeholders with the corresponding strings from the and formats the event log message for the localized event entry. For example, the following section of a message text file defines a string with a parameter placeholder: @@ -855,7 +855,7 @@ TRIGGER.EXE The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. - If your application writes event message strings directly to the event log, or if your does not contain messages with parameter insertion placeholders, do not set the property. + If your application writes event message strings directly to the event log, or if your does not contain messages with parameter insertion placeholders, do not set the property. For details about defining event messages and building event resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. @@ -1016,7 +1016,7 @@ SVC_UPDATE.EXE Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). The tool calls the method, when this or another component has failed to install, to undo any changes that the installation process has already made. - An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool rolls back each . Usually, it is not necessary for your code to explicitly modify this state information. + An application's install routine uses the project installer's property to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool rolls back each . Usually, it is not necessary for your code to explicitly modify this state information. ]]> @@ -1065,11 +1065,11 @@ SVC_UPDATE.EXE ## Remarks The event source indicates what logs the event. It is often the name of the application, or the name of a component within a large application. - The installer uses the value of the property to register your application with the event log as a valid source of entries. A new source name cannot match an existing source name or an existing event log name. Each source can only write to one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. + The installer uses the value of the property to register your application with the event log as a valid source of entries. A new source name cannot match an existing source name or an existing event log name. Each source can only write to one event log at a time; however, your application can use multiple sources to write to multiple event logs. For example, your application might require multiple sources configured for different event logs or different resource files. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. If you do not specify a log name before the installer runs, the installer registers your source to the Application log. If you specify the name of a log that does not exist, the system registers the to that log, but the log is not created until the first entry is written to it. - Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. + Use to register a new source for a new or existing event log; do not use to change an existing source. The class does not modify the configuration properties of an existing source to match the specified installation properties. The method throws an exception if the property matches a source name that is registered for a different event log on the computer. The method does not register the source if the property matches a source name that is already registered for the same event log specified in the property. For more detailed information about the behaviors of event logs and sources, see the class documentation for the and properties. @@ -1106,11 +1106,11 @@ SVC_UPDATE.EXE property value is `Remove`, the method deletes the source and the associated log that the installer created if the and properties specified the creation of a new event log and source. + If the property value is `Remove`, the method deletes the source and the associated log that the installer created if the and properties specified the creation of a new event log and source. Typically, you do not call the methods of the from within your code; they are generally called only by the [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool) in uninstall mode. The tool automatically calls the method to restore the parts of the system that were affected by the installation to their pre-installation states. This includes deleting registry information that is associated with the event log being uninstalled. - An application's uninstall routine uses the project installer's property to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool uninstalls each . Usually, it is not necessary for your code to explicitly modify this state information. + An application's uninstall routine uses the project installer's property to automatically maintain information about the components that have already been uninstalled. This state information, which is passed to as the `savedState` parameter, is continuously updated as the tool uninstalls each . Usually, it is not necessary for your code to explicitly modify this state information. ]]> diff --git a/xml/System.Diagnostics/EventLogPermission.xml b/xml/System.Diagnostics/EventLogPermission.xml index fbd60de695a..08dda20634a 100644 --- a/xml/System.Diagnostics/EventLogPermission.xml +++ b/xml/System.Diagnostics/EventLogPermission.xml @@ -45,21 +45,21 @@ Controls code access permissions for event logging. - to partially trusted code. The ability to read and write the event log enables code to perform actions such as issuing event log messages in the name of another application. - + Do not grant to partially trusted code. The ability to read and write the event log enables code to perform actions such as issuing event log messages in the name of another application. + > [!NOTE] -> If the event source that is specified by the property for the event log does not exist, a new event source is created. To create an event source in Windows Vista and later versions of Windows, or Windows Server 2003, you must have administrative privileges. -> -> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. -> -> Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - +> If the event source that is specified by the property for the event log does not exist, a new event source is created. To create an event source in Windows Vista and later versions of Windows, or Windows Server 2003, you must have administrative privileges. +> +> The reason for this requirement is that all event logs, including security, must be searched to determine whether the event source is unique. Starting with Windows Vista, users do not have permission to access the security log; therefore, a is thrown. +> +> Starting with Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. + ]]> diff --git a/xml/System.Diagnostics/EventLogTraceListener.xml b/xml/System.Diagnostics/EventLogTraceListener.xml index 602b841799e..d837f2a6cee 100644 --- a/xml/System.Diagnostics/EventLogTraceListener.xml +++ b/xml/System.Diagnostics/EventLogTraceListener.xml @@ -61,16 +61,16 @@ To add an using a .NET Framework > > In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that accesses the security log, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - The class provides the property to get or set the event log that receives the tracing or debugging output, and the property to hold the name of the . + The class provides the property to get or set the event log that receives the tracing or debugging output, and the property to hold the name of the . The method closes the event log so it no longer receives tracing or debugging output. The and methods write a message to the event log. > [!NOTE] -> To avoid the possibility of writing large amounts of data to the event log, the does not output the optional trace data specified by the property. +> To avoid the possibility of writing large amounts of data to the event log, the does not output the optional trace data specified by the property. ## Examples The following example creates a trace listener that sends output to an event log. First, the code creates a new that uses the source `myEventLogSource`. Next, `myTraceListener` is added to the collection. Finally, the example sends a line of output to the object. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventLogTraceListener/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventLogTraceListener/Overview/source.vb" id="Snippet1"::: @@ -488,7 +488,7 @@ To add an using a .NET Framework The method, like the method is intended for automated tools but also allows the attaching of additional objects, for example an exception instance, to the trace. - The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `data` object, formatted as a string, using the method. + The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `data` object, formatted as a string, using the method. > [!NOTE] > The maximum value of the `id` parameter is 65,535. If the `id` value specified is greater than 65,535, the maximum value is used. @@ -570,7 +570,7 @@ To add an using a .NET Framework The `severity` and `id` parameter data is used to create an object, which is written to the event log with the data from the array of data objects. - The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `data` object array, formatted as a string array, using the method. + The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `data` object array, formatted as a string array, using the method. > [!NOTE] > The maximum value of the `id` parameter is 65,535. If the `id` value specified is greater than 65,535, the maximum value is used. @@ -652,7 +652,7 @@ To add an using a .NET Framework The method is intended to trace events that can be processed automatically by tools. For example a monitoring tool can notify an administrator if a specific event is traced by a specific source. - The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `message` data using the method. + The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log with the `message` data using the method. > [!NOTE] > The maximum value of the `id` parameter is 65,535. If the `id` value specified is greater than 65,535, the maximum value is used. @@ -734,7 +734,7 @@ To add an using a .NET Framework The method is intended to trace events that can be processed automatically by tools. For example a monitoring tool can notify an administrator if a specific event is traced by a specific source. - The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log, using the method, with the message obtained from the `format` and `args` parameters. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message for the event log. + The `eventCache` and `source` parameters are used to determine if the event should be traced. `id` is used to create an object and the is equated to an for the property. The is written to the event log, using the method, with the message obtained from the `format` and `args` parameters. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message for the event log. > [!NOTE] > The maximum value of the `id` parameter is 65,535. If the `id` value specified is greater than 65,535, the maximum value is used. diff --git a/xml/System.Diagnostics/EventSchemaTraceListener.xml b/xml/System.Diagnostics/EventSchemaTraceListener.xml index 1f8b64c3471..344a43d7728 100644 --- a/xml/System.Diagnostics/EventSchemaTraceListener.xml +++ b/xml/System.Diagnostics/EventSchemaTraceListener.xml @@ -55,7 +55,7 @@ You can create an object in y ``` - The class inherits the property from the base class . The property allows for an additional level of trace output filtering at the listener. If a filter is present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. + The class inherits the property from the base class . The property allows for an additional level of trace output filtering at the listener. If a filter is present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. If an attempt is made to write to a file that is being used or is unavailable, a GUID suffix is automatically added to the file name. @@ -66,24 +66,24 @@ You can create an object in y |Element|Attributes|Output|Notes| |-------------|----------------|------------|-----------| -|`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table in the next table.| -|`Computer`|None|Always present.|This element represents the value of the property.| +|`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table in the next table.| +|`Computer`|None|Always present.|This element represents the value of the property.| |`Correlation`|`ActivityID`|Always present.|If `ActivityID` is not specified, the default is an empty GUID.| ||`RelatedActivityID`|Depends on the presence of the `relatedActivityId` parameter in the `Trace` method call.|The `RelatedActivityID` attribute corresponds to the `relatedActivityId` parameter of the method.| |`Data`|None|Always present.|This element represents parameter input (`data`). One element is provided for each data object. In the case of event logs, the `Data` element contains escaped XML data. In the case of data logs, the `Data` element contains unescaped data. The data log output uses the `ToString` method of the passed-in data objects.| |`Event`|None|Always present.|This element contains a trace event.| |`EventData`|None|Present for event logs.|This element represents parameter input (`message`, `args`). It contains `Data` elements with escaped XML data that is created by calling the method.| |`EventID`|None|Always present.|This element represents parameter input (`id`).| -|`Execution`|`ProcessID`|Depends on the presence of the flag in the property.|The `ProcessID` attribute is specified in the .| +|`Execution`|`ProcessID`|Depends on the presence of the flag in the property.|The `ProcessID` attribute is specified in the .| ||`ThreadID`|Present when `ProcessID` is present.|The `ThreadID` attribute is specified in the .| |`Level`|None|Always present.|This element represents parameter input (the numeric value of `eventType`). Parameter values that are larger than 255 are output as a level 8, which represents . Trace event types , , , , and are output as levels 1, 2, 4, 8, and 10, respectively.| -|`LogicalOperationStack`|None|Depends on the presence of the flag in the property.|Only one logical operation can exist. Therefore, the values are written as `LogicalOperation` nodes under the `LogicalOperationStack` element.| +|`LogicalOperationStack`|None|Depends on the presence of the flag in the property.|Only one logical operation can exist. Therefore, the values are written as `LogicalOperation` nodes under the `LogicalOperationStack` element.| |`OpCode`|None|Present when `Level` is greater than 255.|This element represents Trace event types that have numeric values greater than 255. , , , , or are output as levels 1, 2, 4, 8, and 10, respectively.| |`Provider`|`GUID`|Always present.|Always empty.| |`RenderingInfo`|`Culture`|Always present.|This attribute represents a resource string for the event type. It is always "en-EN\\".| |`System`|`Name`|Always present.|| -|`TimeCreated`|`SystemTime`|Depends on the presence of the flag in the property.|The time is the value of the property. This property is expressed as Coordinated Universal Time| -|`TimeStamp`|None|Depends on the presence of the flag in the property.|This element is specified in the .| +|`TimeCreated`|`SystemTime`|Depends on the presence of the flag in the property.|The time is the value of the property. This property is expressed as Coordinated Universal Time| +|`TimeStamp`|None|Depends on the presence of the flag in the property.|This element is specified in the .| |`UserData`|None|Present for data logs.|This element contains `Data` elements with unescaped, user-provided data from a method.| The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes except for the `UserData` element, which contains user-provided, unescaped data. The `UserData` element is a result of calls to the method. @@ -430,7 +430,7 @@ You can create an object in y ## Examples - The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. + The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet5"::: @@ -569,7 +569,7 @@ You can create an object in y property. This code example is part of a larger example that is provided for the class. + The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet4"::: @@ -601,9 +601,9 @@ You can create an object in y property value is not an absolute; it is a threshold that can be exceeded up to the size of the last message. + The property value is set by the `maximumFileSize` parameter in the constructor or the `maximumFileSize` attribute in the configuration file. For performance reasons, you should set the maximum file size to a multiple of 1024 bytes. The property value is not an absolute; it is a threshold that can be exceeded up to the size of the last message. - The following table shows the possible and default values for file size that are associated with each trace log retention option. The values marked as N/A indicate that the property is not checked for that value. + The following table shows the possible and default values for file size that are associated with each trace log retention option. The values marked as N/A indicate that the property is not checked for that value. |TraceLogRetentionOption|Maximum file size|Default file size| |-----------------------------|-----------------------|-----------------------| @@ -616,7 +616,7 @@ You can create an object in y ## Examples - The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. + The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet6"::: @@ -650,7 +650,7 @@ You can create an object in y ## Remarks The property value is set by the `maximumNumberOfFiles` parameter in the constructor or the `maximumNumberOfFiles` attribute in the configuration file. - The following table shows the possible and default values for file size and file count that are associated with each trace log retention option. The values marked as N/A indicate that the property is not checked for that value. + The following table shows the possible and default values for file size and file count that are associated with each trace log retention option. The values marked as N/A indicate that the property is not checked for that value. |TraceLogRetentionOption|Maximum number of files|Default number of files| |-----------------------------|-----------------------------|-----------------------------| @@ -663,7 +663,7 @@ You can create an object in y ## Examples - The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. + The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet7"::: @@ -925,7 +925,7 @@ You can create an object in y property. This code example is part of a larger example that is provided for the class. + The following code example demonstrates how to display the value of the property. This code example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet9"::: @@ -1082,7 +1082,7 @@ You can create an object in y property raises a . + An attempt to use the set accessor for the property raises a . ]]> diff --git a/xml/System.Diagnostics/EventSourceCreationData.xml b/xml/System.Diagnostics/EventSourceCreationData.xml index 169e9eb007e..e135301dd96 100644 --- a/xml/System.Diagnostics/EventSourceCreationData.xml +++ b/xml/System.Diagnostics/EventSourceCreationData.xml @@ -38,7 +38,7 @@ ## Remarks Use the class to configure a new source for writing localized entries to an event log. It is not necessary to use this class to read from an event log. - This class defines the configuration settings for a new event source and its associated event log. The associated event log can be on the local computer or a remote computer. To create a new source for a new or existing event log on the local computer, set the and properties of an and call the method. This method creates the event source you specify in the property and registers it for the event log specified in . This behavior is similar to using the class to register an event source for an event log. + This class defines the configuration settings for a new event source and its associated event log. The associated event log can be on the local computer or a remote computer. To create a new source for a new or existing event log on the local computer, set the and properties of an and call the method. This method creates the event source you specify in the property and registers it for the event log specified in . This behavior is similar to using the class to register an event source for an event log. Use the and methods to write events to an event log. You must specify an event source to write events; you must create and configure the event source before writing the first entry with the source. @@ -60,7 +60,7 @@ ## Examples The following code example sets the configuration properties for an event source from command-line arguments. The input arguments specify the event source name, event log name, computer name, and event message resource file. The code example verifies that the source does not conflict with an existing event source, and then creates the new event source for the specified event log. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSourceCreationData/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSourceCreationData/Overview/source.vb" id="Snippet1"::: @@ -651,14 +651,14 @@ SVC_UPDATE.EXE property to identify the event log that your application writes entries to using the new source. The event log can be a new log or an existing log. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. If you do not explicitly set the property, the event log defaults to the Application log. + Use the property to identify the event log that your application writes entries to using the new source. The event log can be a new log or an existing log. Applications and services should write to the Application log or a custom log. Device drivers should write to the System log. If you do not explicitly set the property, the event log defaults to the Application log. > [!NOTE] > The Security log is read-only. - To target an existing log for the new source, set the property to the existing event log name. To create a new event log for the source, you must set the property. Event log names must consist of printable characters, and cannot include the characters '*', '?', or '\\'. The first 8 characters of the event log name must be different from the first 8 characters of existing names of event logs on the specified computer. + To target an existing log for the new source, set the property to the existing event log name. To create a new event log for the source, you must set the property. Event log names must consist of printable characters, and cannot include the characters '*', '?', or '\\'. The first 8 characters of the event log name must be different from the first 8 characters of existing names of event logs on the specified computer. - The operating system stores event logs as files. When you use or the method to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. + The operating system stores event logs as files. When you use or the method to create a new event log, the associated file is stored in the %SystemRoot%\System32\Config directory on the specified computer. The file name is set by appending the first 8 characters of the property with the ".evt" file name extension. @@ -784,13 +784,13 @@ SVC_UPDATE.EXE property to configure an event log source to write localized event messages. Event messages are application-defined strings that describe the event to the user. + Use the property to configure an event log source to write localized event messages. Event messages are application-defined strings that describe the event to the user. Your application can write event log entries using resource identifiers. A resource identifier indexes a message located in the . The Event Viewer uses the resource identifier to find and display the corresponding string from the localized message resource file based on current language settings. The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. - If your application writes event message strings directly, rather than using a resource identifier in a localized resource file, do not set the property. + If your application writes event message strings directly, rather than using a resource identifier in a localized resource file, do not set the property. For details about defining event messages and building event resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. @@ -965,7 +965,7 @@ SVC_UPDATE.EXE property to configure an event log source to write localized event messages with inserted parameter strings. Each localized event message specified in the property can contain placeholders for insertion strings. These placeholders are used to specify the position and resource identifier for a language-independent string within the event message. The Event Viewer fills in the placeholders using the corresponding strings from the and formats the event log message for the localized event entry. + Use the property to configure an event log source to write localized event messages with inserted parameter strings. Each localized event message specified in the property can contain placeholders for insertion strings. These placeholders are used to specify the position and resource identifier for a language-independent string within the event message. The Event Viewer fills in the placeholders using the corresponding strings from the and formats the event log message for the localized event entry. For example, the following section of a message text file defines a string with a parameter placeholder: @@ -994,7 +994,7 @@ TRIGGER.EXE The event source must be configured either for writing localized entries or for writing direct strings. Use the method to write localized entries for a source configured with a message resource file. - If your application writes event message strings directly to the event log, or if your property does not contain messages with parameter insertion placeholders, do not set the property. + If your application writes event message strings directly to the event log, or if your property does not contain messages with parameter insertion placeholders, do not set the property. For details about defining event messages and building event resource files, see the [Message Compiler](/windows/win32/wes/message-compiler--mc-exe-) article in the Platform SDK documentation. diff --git a/xml/System.Diagnostics/EventTypeFilter.xml b/xml/System.Diagnostics/EventTypeFilter.xml index ae4e7383b20..80f33f3c16f 100644 --- a/xml/System.Diagnostics/EventTypeFilter.xml +++ b/xml/System.Diagnostics/EventTypeFilter.xml @@ -46,30 +46,30 @@ Indicates whether a listener should trace based on the event type. - property to provide a layer of screening beyond that provided by the . The filter can be used to control the event types that are produced by the listener. - - This class filters events based on the value of the property. This property can be set by code or, for .NET Framework apps, in a configuration file to specify the event type of messages that should be traced by the listener. The value of the property indicates the threshold at which to begin tracing. Event types at and above the specified level are traced. The method, called by listeners to determine if an event should be traced, uses the value of the property. - -To set the event type at which to begin tracing in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its filter type, and specify the event type to trace. The configuration file should be formatted as follows. - -```xml - - - - - - - - - -``` - - For more information about how to initialize data for an , see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/filter-element-for-add-for-sharedlisteners). - + property to provide a layer of screening beyond that provided by the . The filter can be used to control the event types that are produced by the listener. + + This class filters events based on the value of the property. This property can be set by code or, for .NET Framework apps, in a configuration file to specify the event type of messages that should be traced by the listener. The value of the property indicates the threshold at which to begin tracing. Event types at and above the specified level are traced. The method, called by listeners to determine if an event should be traced, uses the value of the property. + +To set the event type at which to begin tracing in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a listener, set its filter type, and specify the event type to trace. The configuration file should be formatted as follows. + +```xml + + + + + + + + + +``` + + For more information about how to initialize data for an , see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/filter-element-for-add-for-sharedlisteners). + ]]> @@ -120,11 +120,11 @@ To set the event type at which to begin tracing in a .NET Framework app, edit th A bitwise combination of the values that specifies the event type of the messages to trace. Initializes a new instance of the class. - property. - + property. + ]]> @@ -179,11 +179,11 @@ To set the event type at which to begin tracing in a .NET Framework app, edit th Gets or sets the event type of the messages to trace. A bitwise combination of the values. - property indicates the level at which to trace. - + property indicates the level at which to trace. + ]]> @@ -262,11 +262,11 @@ To set the event type at which to begin tracing in a .NET Framework app, edit th if the trace should be produced; otherwise, . - property, the method returns `true`. - + property, the method returns `true`. + ]]> diff --git a/xml/System.Diagnostics/FileVersionInfo.xml b/xml/System.Diagnostics/FileVersionInfo.xml index 405f1fd2a7a..d28f3b94edf 100644 --- a/xml/System.Diagnostics/FileVersionInfo.xml +++ b/xml/System.Diagnostics/FileVersionInfo.xml @@ -66,11 +66,11 @@ - The last 16 bits are the number. - Use the method of this class to get a containing information about a file, then look at the properties for information about the file. The property provides version information about the file. The , , , , and properties provide version information for the product that the specified file is a part of. Call to get a partial list of properties and their values for this file. + Use the method of this class to get a containing information about a file, then look at the properties for information about the file. The property provides version information about the file. The , , , , and properties provide version information for the product that the specified file is a part of. Call to get a partial list of properties and their values for this file. The properties are based on version resource information built into the file. Version resources are often built into binary files such as .exe or .dll files; text files do not have version resource information. - Version resources are typically specified in a Win32 resource file, or in assembly attributes. For example the property reflects the `VS_FF_DEBUG` flag value in the file's `VS_FIXEDFILEINFO` block, which is built from the `VERSIONINFO` resource in a Win32 resource file. For more information about specifying version resources in a Win32 resource file, see "About Resource Files" and "VERSIONINFO Resource" in the Platform SDK. For more information about specifying version resources in a .NET module, see the [Setting Assembly Attributes](/dotnet/standard/assembly/set-attributes) topic. + Version resources are typically specified in a Win32 resource file, or in assembly attributes. For example the property reflects the `VS_FF_DEBUG` flag value in the file's `VS_FIXEDFILEINFO` block, which is built from the `VERSIONINFO` resource in a Win32 resource file. For more information about specifying version resources in a Win32 resource file, see "About Resource Files" and "VERSIONINFO Resource" in the Platform SDK. For more information about specifying version resources in a .NET module, see the [Setting Assembly Attributes](/dotnet/standard/assembly/set-attributes) topic. > [!NOTE] > This class makes a link demand at the class level that applies to all members. A is thrown when the immediate caller does not have full trust permission. For details about link demands, see [Link Demands](/dotnet/framework/misc/link-demands). @@ -916,7 +916,7 @@ ## Remarks The properties are based on version resource information built into the file. Version resources are often built into binary files such as .exe or .dll files; text files do not have version resource information. - Version resources are typically specified in a Win32 resource file, or in assembly attributes. The property reflects the `VS_FF_DEBUG` flag value in the file's `VS_FIXEDFILEINFO` block, which is built from the `VERSIONINFO` resource in a Win32 resource file. For more information about specifying version resources in a Win32 resource file, see the Platform SDK `About Resource Files` topic and `VERSIONINFO Resource` topic topics. + Version resources are typically specified in a Win32 resource file, or in assembly attributes. The property reflects the `VS_FF_DEBUG` flag value in the file's `VS_FIXEDFILEINFO` block, which is built from the `VERSIONINFO` resource in a Win32 resource file. For more information about specifying version resources in a Win32 resource file, see the Platform SDK `About Resource Files` topic and `VERSIONINFO Resource` topic topics. @@ -1143,7 +1143,7 @@ property must specify how this file differs from the standard version. + A file that is a special build was built using standard release procedures, but the file differs from a standard file of the same version number. If this value is `true`, the property must specify how this file differs from the standard version. diff --git a/xml/System.Diagnostics/InstanceData.xml b/xml/System.Diagnostics/InstanceData.xml index 2a9a6374237..fba5a57831b 100644 --- a/xml/System.Diagnostics/InstanceData.xml +++ b/xml/System.Diagnostics/InstanceData.xml @@ -38,7 +38,7 @@ ## Examples The following code example displays the contents of the objects that exist in a particular on the local computer. It first displays a numbered list of categories. After the user enters the number of one of the categories, the sample displays, for each in the , the instance data associated with each instance of the . - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet1"::: @@ -141,7 +141,7 @@ and displays the value of its property and other properties. + The following code example creates an and displays the value of its property and other properties. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet3"::: @@ -186,7 +186,7 @@ and displays the value of its property and other properties. + The following code example creates an and displays the value of its property and other properties. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet3"::: @@ -237,7 +237,7 @@ and gets the value of its property, which is a reference to a . The example then displays the fields of the . + The following code example creates an and gets the value of its property, which is a reference to a . The example then displays the fields of the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet3"::: diff --git a/xml/System.Diagnostics/InstanceDataCollection.xml b/xml/System.Diagnostics/InstanceDataCollection.xml index 56bd62fc892..722f189e05d 100644 --- a/xml/System.Diagnostics/InstanceDataCollection.xml +++ b/xml/System.Diagnostics/InstanceDataCollection.xml @@ -34,19 +34,19 @@ Provides a strongly typed collection of objects. - class represents a collection containing all the instance data for a counter. This collection is contained in the when using the method. - - - -## Examples - The following code example displays the instance data for a particular on the local computer. It first displays a numbered list of names. After the user enters the number of one of the categories, the example gets the for that . It then converts the collection returned by to an array of objects. The example also displays the instance data associated with each of each . - + class represents a collection containing all the instance data for a counter. This collection is contained in the when using the method. + + + +## Examples + The following code example displays the instance data for a particular on the local computer. It first displays a numbered list of names. After the user enters the number of one of the categories, the example gets the for that . It then converts the collection returned by to an array of objects. The example also displays the instance data associated with each of each . + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet1"::: + ]]> @@ -143,19 +143,19 @@ if the instance exists in the collection; otherwise, . - category name, counter name, and instance name from the command line. It gets the for the category, which is a collection of objects. From that it gets the particular for the specified counter. It then uses the method to determine if the specified instance exists, using the default single-instance name if none is entered. - + category name, counter name, and instance name from the command line. It gets the for the category, which is a collection of objects. From that it gets the particular for the specified counter. It then uses the method to determine if the specified instance exists, using the default single-instance name if none is entered. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollection/Contains/instdatacolitemcontains.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Contains/instdatacolitemcontains.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Contains/instdatacolitemcontains.vb" id="Snippet2"::: + ]]> The parameter is . @@ -199,14 +199,14 @@ The zero-based index value at which to add the new instances. Copies the items in the collection to the specified one-dimensional array at the specified index. - method to convert an into an array of objects. The values of the and properties of each element of the array are passed to a function for further processing. - + method to convert an into an array of objects. The values of the and properties of each element of the array are passed to a function for further processing. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet4"::: + ]]> @@ -250,14 +250,14 @@ Gets the name of the performance counter whose instance data you want to get. The performance counter name. - property of an . - + property of an . + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet4"::: + ]]> @@ -299,19 +299,19 @@ Gets the instance data associated with this counter. This is typically a set of raw counter values. An item, by which the object is indexed. - category name, counter name, and instance name from the command line. It gets the for the category, which is a collection of objects. From that it gets the particular for the specified counter. Then, if the instance exists, the example uses the property (referenced as an indexer) to obtain the associated object. - + category name, counter name, and instance name from the command line. It gets the for the category, which is a collection of objects. From that it gets the particular for the specified counter. Then, if the instance exists, the example uses the property (referenced as an indexer) to obtain the associated object. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollection/Contains/instdatacolitemcontains.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Contains/instdatacolitemcontains.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Contains/instdatacolitemcontains.vb" id="Snippet2"::: + ]]> The parameter is . @@ -350,19 +350,19 @@ Gets the object and counter registry keys for the objects associated with this instance data. An that represents a set of object-specific registry keys. - property of an to return a collection of instance names, which it converts to an array of . It generates an array of objects using the property. For each element in the array of instance names, it displays the name and calls a function to process the associated object. - + property of an to return a collection of instance names, which it converts to an array of . It generates an array of objects using the property. For each element in the array of instance names, it displays the name and calls a function to process the associated object. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet3"::: + ]]> @@ -400,14 +400,14 @@ Gets the raw counter values that comprise the instance data for the counter. An that represents the counter's raw data values. - property of an to return a collection of objects, which it converts to an array. It generates an array of instance names using the property. For each element in the array of objects, it displays the associated instance name and calls a function to process the object. - + property of an to return a collection of objects, which it converts to an array. It generates an array of instance names using the property. For each element in the array of objects, it displays the associated instance name and calls a function to process the object. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Diagnostics/InstanceDataCollectionCollection.xml b/xml/System.Diagnostics/InstanceDataCollectionCollection.xml index 77ca719f5e6..6c2daac463c 100644 --- a/xml/System.Diagnostics/InstanceDataCollectionCollection.xml +++ b/xml/System.Diagnostics/InstanceDataCollectionCollection.xml @@ -34,19 +34,19 @@ Provides a strongly typed collection of objects. - class represents the collection returned from the method. This collection contains all the counter and instance data. The collection contains an object for each counter. Each object contains the performance data for all counters for that instance. Thus, the data is indexed by counter name and then by instance name. - - - -## Examples - The following code example displays the instance data for a particular on the local computer. It first displays a numbered list of names. After the user enters the number of one of the categories, the example gets the for that . It then converts the collection returned by the property to an array of objects. The example displays the instance data associated with each of each . - + class represents the collection returned from the method. This collection contains all the counter and instance data. The collection contains an object for each counter. Each object contains the performance data for all counters for that instance. Thus, the data is indexed by counter name and then by instance name. + + + +## Examples + The following code example displays the instance data for a particular on the local computer. It first displays a numbered list of names. After the user enters the number of one of the categories, the example gets the for that . It then converts the collection returned by the property to an array of objects. The example displays the instance data associated with each of each . + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet1"::: + ]]> @@ -141,21 +141,21 @@ if an instance data collection containing the specified counter exists in the collection; otherwise, . - object in the collection contains the performance data for all counters for an instance. The data is indexed by counter name and then by instance name. returns `true` if there is an object whose associated counter has the name specified by the `counterName` parameter. - - - -## Examples - The following code example accepts a category name and counter name from the command line. It gets the for the and then uses the method to determine if the specified counter exists. If the counter exists, the example gets the associated and displays the instance names from the collection. - + object in the collection contains the performance data for all counters for an instance. The data is indexed by counter name and then by instance name. returns `true` if there is an object whose associated counter has the name specified by the `counterName` parameter. + + + +## Examples + The following code example accepts a category name and counter name from the command line. It gets the for the and then uses the method to determine if the specified counter exists. If the counter exists, the example gets the associated and displays the instance names from the collection. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollectionCollection/Contains/instdatacolcolitermcontains.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollectionCollection/Contains/instdatacolcolitemcontains.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollectionCollection/Contains/instdatacolcolitemcontains.vb" id="Snippet2"::: + ]]> The parameter is . @@ -199,14 +199,14 @@ The location at which to add the new instances. Copies an array of instances to the collection, at the specified index. - method to convert an into an array of objects. Each element of the array is passed to a function for further processing. - + method to convert an into an array of objects. Each element of the array is passed to a function for further processing. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceData/Overview/instdatacopyto.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceData/Overview/instdatacopyto.vb" id="Snippet5"::: + ]]> @@ -248,21 +248,21 @@ Gets the instance data for the specified counter. An item, by which the object is indexed. - object in the collection contains the performance data for all counters for an instance. The data is indexed by counter name and then by instance name. The indexer uses the `counterName` parameter to step through the counters associated with this collection of instance data. - - - -## Examples - The following code example accepts a category name and counter name from the command line. It gets the for the . Then, if the exists, the example uses the property (referenced as an indexer) to obtain the associated and displays the instance names from the collection. - + object in the collection contains the performance data for all counters for an instance. The data is indexed by counter name and then by instance name. The indexer uses the `counterName` parameter to step through the counters associated with this collection of instance data. + + + +## Examples + The following code example accepts a category name and counter name from the command line. It gets the for the . Then, if the exists, the example uses the property (referenced as an indexer) to obtain the associated and displays the instance names from the collection. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollectionCollection/Contains/instdatacolcolitermcontains.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollectionCollection/Contains/instdatacolcolitemcontains.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollectionCollection/Contains/instdatacolcolitemcontains.vb" id="Snippet2"::: + ]]> The parameter is . @@ -301,19 +301,19 @@ Gets the object and counter registry keys for the objects associated with this instance data collection. An that represents a set of object-specific registry keys. - property of an to return a collection of counter names, which it converts to an array of . It generates an array of objects using the property. For each element in the array of counter names, it displays the name and calls a function to process the associated . - + property of an to return a collection of counter names, which it converts to an array of . It generates an array of objects using the property. For each element in the array of counter names, it displays the name and calls a function to process the associated . + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet4"::: + ]]> @@ -351,14 +351,14 @@ Gets the instance data values that comprise the collection of instances for the counter. An that represents the counter's instances and their associated data values. - property of an to return a collection of objects, which it converts to an array. It generates an array of counter names using the property. For each element in the array of objects, it displays the associated counter name and calls a function to process the . - + property of an to return a collection of objects, which it converts to an array. It generates an array of counter names using the property. For each element in the array of objects, it displays the associated counter name and calls a function to process the . + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/InstanceDataCollection/Overview/instdatakeysvalues.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.Diagnostics/MonitoringDescriptionAttribute.xml b/xml/System.Diagnostics/MonitoringDescriptionAttribute.xml index d1b6672f57f..0d114452693 100644 --- a/xml/System.Diagnostics/MonitoringDescriptionAttribute.xml +++ b/xml/System.Diagnostics/MonitoringDescriptionAttribute.xml @@ -56,11 +56,11 @@ Specifies a description for a property or event. - property to get or set the text associated with this attribute. - + property to get or set the text associated with this attribute. + ]]> @@ -114,11 +114,11 @@ The application-defined description text. Initializes a new instance of the class, using the specified description. - constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies - + constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies + ]]> diff --git a/xml/System.Diagnostics/OverflowAction.xml b/xml/System.Diagnostics/OverflowAction.xml index 3f6de1fee6a..49e5e018c7e 100644 --- a/xml/System.Diagnostics/OverflowAction.xml +++ b/xml/System.Diagnostics/OverflowAction.xml @@ -41,7 +41,7 @@ - New entries will overwrite older entries. - Use the method to set the overflow behavior for an . Check the current configured behavior of an through its property. + Use the method to set the overflow behavior for an . Check the current configured behavior of an through its property. > [!WARNING] > The `OverwriteOlder` behavior is deprecated. Using this value might cause the Event Log to behave as if the `DoNotOverwrite` value was used instead, which will cause events to be discarded when the log is full. diff --git a/xml/System.Diagnostics/PerformanceCounter.xml b/xml/System.Diagnostics/PerformanceCounter.xml index 03f4e811452..9ce5f36ddce 100644 --- a/xml/System.Diagnostics/PerformanceCounter.xml +++ b/xml/System.Diagnostics/PerformanceCounter.xml @@ -72,10 +72,10 @@ To read from a performance counter, create an instance of the class, set the , , and, optionally, the or properties, and then call the method to take a performance counter reading. - To publish performance counter data, create one or more custom counters using the method, create an instance of the class, set the , and, optionally, or properties, and then call the , , or methods, or set the property to change the value of your custom counter. + To publish performance counter data, create one or more custom counters using the method, create an instance of the class, set the , and, optionally, or properties, and then call the , , or methods, or set the property to change the value of your custom counter. > [!NOTE] -> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. +> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. The counter is the mechanism by which performance data is collected. The registry stores the names of all the counters, each of which is related to a specific area of system functionality. Examples include a processor's busy time, memory usage, or the number of bytes received over a network connection. @@ -146,15 +146,15 @@ , , and properties to empty strings (""), and sets the property to the local computer, ("."). + This overload of the constructor sets the , , and properties to empty strings (""), and sets the property to the local computer, ("."). - This constructor does not initialize the performance counter, so it does not associate the instance with an existing counter on the local computer. To point to a specific performance counter, set the , , and, optionally, the and properties before reading any other properties or attempting to read from a counter. To write to a performance counter, set the property to `false`. + This constructor does not initialize the performance counter, so it does not associate the instance with an existing counter on the local computer. To point to a specific performance counter, set the , , and, optionally, the and properties before reading any other properties or attempting to read from a counter. To write to a performance counter, set the property to `false`. > [!NOTE] -> The attribute applied to this member has the following property value: | . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). +> The attribute applied to this member has the following property value: | . The does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the class or [SQL Server Programming and Host Protection Attributes](/dotnet/framework/performance/sql-server-programming-and-host-protection-attributes). ## Examples - The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. + The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.vb" id="Snippet1"::: @@ -211,7 +211,7 @@ Use this overload to access a counter on the local computer that belongs to a category containing a single performance counter category instance. If you attempt to use this constructor to point this instance to a category that contains multiple instances, the constructor throws an exception. This overload can access any read-only or read/write counter, but does so in a read-only mode. A instance created using this overload cannot write to the counter, even if the counter itself is read/write. - This overload of the constructor sets the and properties to the values you pass in, sets the property to the local computer, ".", and sets the property to an empty string (""). + This overload of the constructor sets the and properties to the values you pass in, sets the property to the local computer, ".", and sets the property to an empty string (""). This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the and properties must point to an existing performance counter on the local computer. @@ -299,7 +299,7 @@ Use this overload to access a read-only or read/write counter on the local computer that belongs to a category containing a single performance counter category instance. If you attempt to use this constructor to point this instance to a category that contains multiple instances, the constructor throws an exception. - This overload of the constructor sets the , , and properties to the values you pass in, sets the property to the local computer, ".", and sets the property to an empty string (""). + This overload of the constructor sets the , , and properties to the values you pass in, sets the property to the local computer, ".", and sets the property to an empty string (""). This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the and properties must point to an existing performance counter on the local computer. If the performance counter instance that you point to is not valid, calling the constructor throws an exception. @@ -396,7 +396,7 @@ ## Remarks The parameter strings are not case-sensitive. - This overload of the constructor sets the , , and properties to the values you pass in, and sets the property to the local computer, ".". + This overload of the constructor sets the , , and properties to the values you pass in, and sets the property to the local computer, ".". This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the , , and properties must point to an existing performance counter on the local computer. If the performance counter instance you point to is not valid, calling the constructor throws an exception. @@ -488,7 +488,7 @@ Use this overload to access a performance counter in either read-only or read/write mode. - This overload of the constructor sets the , , and properties to the values you pass in, it and sets the property to the local computer, ".". + This overload of the constructor sets the , , and properties to the values you pass in, it and sets the property to the local computer, ".". This constructor initializes the performance counter and associates the instance with an existing counter (either a system or a custom counter) on the local computer. The values that you pass in for the , , and properties must point to an existing performance counter on the local computer. If the performance counter instance that you point to is not valid, calling the constructor throws an exception. @@ -770,7 +770,7 @@ Although your system makes many more counter categories available, the categories that you will probably interact with most frequently are the Cache, Memory, Objects, PhysicalDisk, Process, Processor, Server, System, and Thread categories. ## Examples - The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. + The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.vb" id="Snippet1"::: @@ -913,7 +913,7 @@ When you create a new counter, use the text to describe what the counter monitors do so the user can determine whether to add the counter to the System Monitor's display. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1007,7 +1007,7 @@ ## Examples - The following code example shows how to set the property to a typical counter name. + The following code example shows how to set the property to a typical counter name. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.vb" id="Snippet1"::: @@ -1076,7 +1076,7 @@ When you create a counter whose type requires the use of a corresponding base counter, you must declare the counter and the base in the you pass into the method. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1136,10 +1136,10 @@ You can write only to custom counters. All system counters are read-only. > [!NOTE] -> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. +> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. ]]> @@ -1333,10 +1333,10 @@ You can write only to custom counters. All system counters are read-only. > [!NOTE] -> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. +> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. ]]> @@ -1402,10 +1402,10 @@ You can write only to custom counters. All system counters are read-only. > [!NOTE] -> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. +> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. @@ -1478,7 +1478,7 @@ If the performance counter category is created with the .NET Framework version 1.0 or 1.1, it uses global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] -> If the value of the property is , the value for the performance counter must be . +> If the value of the property is , the value for the performance counter must be . ]]> @@ -1582,12 +1582,12 @@ |\\|_| |/|_| - The property of the object obtained from the property is a common source of instance names that can contain invalid characters. + The property of the object obtained from the property is a common source of instance names that can contain invalid characters. ## Examples - The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. + The following code example creates a default instance of the class. After the instance is created, the , , and property values are set, and the results of a call to the method are displayed. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounter/.ctor/perfcounter.vb" id="Snippet1"::: @@ -1656,7 +1656,7 @@ ## Remarks You can write values only to counters that reside on the local computer. However, you can read counter values from any computer in the enterprise for which you have access privileges. - When you set the property to point to a remote computer, the instance attempts to open the counter on that computer. If the counter does not exist, setting this property throws an exception. + When you set the property to point to a remote computer, the instance attempts to open the counter on that computer. If the counter does not exist, setting this property throws an exception. ]]> @@ -1703,7 +1703,7 @@ This method is generally used for counters that contain uncalculated values. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1840,17 +1840,17 @@ property rather than a calculated value can produce significantly better performance in scenarios where the raw value is sufficient. + If the counter type is a 32-bit size and you attempt to set this property to a value that is too large to fit, the property truncates the value to 32 bits. When reading custom counters on the local computer, using the property rather than a calculated value can produce significantly better performance in scenarios where the raw value is sufficient. - If the counter that you are reading is read-only, getting the property samples the counter at the time that the property is called. This action is equivalent to making an initial call to the method. If you subsequently call , you can perform calculations on the values that both calls returned. + If the counter that you are reading is read-only, getting the property samples the counter at the time that the property is called. This action is equivalent to making an initial call to the method. If you subsequently call , you can perform calculations on the values that both calls returned. Because system counters are read-only, you can get but not set their raw values. > [!NOTE] -> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. +> The , , and methods use interlocks to update the counter value. This helps keep the counter value accurate in multithreaded or multiprocess scenarios, but also results in a performance penalty. If you do not need the accuracy that interlocked operations provide, you can update the property directly for up to a 5 times performance improvement. However, in multithreaded scenarios, some updates to the counter value might be ignored, resulting in inaccurate data. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. > [!NOTE] > To read performance counters in Windows Vista, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1862,7 +1862,7 @@ ## Examples - The following example uses the class to display the value of the property for a counter. + The following example uses the class to display the value of the property for a counter. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/CounterCreationData/Overview/averagecount32.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/CounterCreationData/Overview/averagecount32.vb" id="Snippet1"::: @@ -1993,7 +1993,7 @@ To create a performance category instance, specify an `instanceName` on the constructor. If the category instance specified by `instanceName` already exists the new object will reference the existing category instance. > [!NOTE] -> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. +> If the value for the property is and the performance counter category was created with .NET Framework version 1.0 or 1.1, an is thrown. Performance counter categories created with earlier versions use global shared memory, and the value for must be . If the category is not used by applications running on versions 1.0 or 1.1 of the .NET Framework, delete and recreate the category. ]]> diff --git a/xml/System.Diagnostics/PerformanceCounterCategory.xml b/xml/System.Diagnostics/PerformanceCounterCategory.xml index e0c15f5b447..e17cb720173 100644 --- a/xml/System.Diagnostics/PerformanceCounterCategory.xml +++ b/xml/System.Diagnostics/PerformanceCounterCategory.xml @@ -41,7 +41,7 @@ > [!IMPORTANT] > Creating or deleting a performance counter requires synchronization of the underlying code by using a named mutex. If a highly privileged application locks the named mutex, attempts to create or delete a performance counter causes the application to stop responding until the lock is released. To help avoid this problem, never grant permission to untrusted code. In addition, permission potentially allows other permissions to be bypassed and should only be granted to highly trusted code. - The instance's property is displayed in the Performance Object field of the Performance Viewer application's Add Counter dialog box. + The instance's property is displayed in the Performance Object field of the Performance Viewer application's Add Counter dialog box. The class provides several methods for interacting with counters and categories on the computer. The methods enable you to define custom categories. The method provides a way to remove categories from the computer. The method enables you to view the list of categories, while retrieves all the counter and instance data associated with a single category. @@ -120,7 +120,7 @@ property must be set before associating this instance with a performance object on the server. Otherwise, an exception is thrown. + The property must be set before associating this instance with a performance object on the server. Otherwise, an exception is thrown. @@ -390,7 +390,7 @@ property indicates whether the object can have multiple instances. The possible values are , , or . + The property indicates whether the object can have multiple instances. The possible values are , , or . There are two types of performance counter categories: single-instance and multi-instance. By default, a category is single-instance when it is created and becomes multi-instance when another instance is added. Categories are created when an application is set up, and instances are added at run time. The enumeration is used to indicate whether a performance counter can have multiple instances. @@ -448,9 +448,9 @@ property before calling this method. Otherwise, an exception is thrown. + You must set the property before calling this method. Otherwise, an exception is thrown. - If you have not set the property, this method uses the local computer ("."). + If you have not set the property, this method uses the local computer ("."). > [!NOTE] > To read performance counters from a non-interactive logon session in Windows Vista and later, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1652,7 +1652,7 @@ is not `static`. It requires you to create a object and to set the property. + This overload of is not `static`. It requires you to create a object and to set the property. > [!NOTE] > To read performance counters from a non-interactive logon session in Windows Vista and later, Windows XP Professional x64 Edition, or Windows Server 2003, you must either be a member of the Performance Monitor Users group or have administrative privileges. @@ -1939,7 +1939,7 @@ property before you call . + You must set the property before you call . Reading the entire category at once can be as efficient as reading a single counter because of the way that the system provides the data. diff --git a/xml/System.Diagnostics/PerformanceCounterInstaller.xml b/xml/System.Diagnostics/PerformanceCounterInstaller.xml index ff2a1a2b0f3..adef879a6e3 100644 --- a/xml/System.Diagnostics/PerformanceCounterInstaller.xml +++ b/xml/System.Diagnostics/PerformanceCounterInstaller.xml @@ -27,7 +27,7 @@ ## Examples The following code example demonstrates how to create a object and add it to an . - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/PerformanceCounterInstaller/Overview/performancecounterinstaller.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/PerformanceCounterInstaller/Overview/performancecounterinstaller.vb" id="Snippet1"::: @@ -164,7 +164,7 @@ property specifies whether the performance counter category can have multiple instances. + The property specifies whether the performance counter category can have multiple instances. ]]> diff --git a/xml/System.Diagnostics/PerformanceCounterInstanceLifetime.xml b/xml/System.Diagnostics/PerformanceCounterInstanceLifetime.xml index 7048bb999d9..61231f80a30 100644 --- a/xml/System.Diagnostics/PerformanceCounterInstanceLifetime.xml +++ b/xml/System.Diagnostics/PerformanceCounterInstanceLifetime.xml @@ -32,14 +32,14 @@ Specifies the lifetime of a performance counter instance. - [!NOTE] -> If the property is , the value for the performance counter must be `Global`. - +> If the property is , the value for the performance counter must be `Global`. + ]]> diff --git a/xml/System.Diagnostics/Process.xml b/xml/System.Diagnostics/Process.xml index 5fd8534149e..17abad93c55 100644 --- a/xml/System.Diagnostics/Process.xml +++ b/xml/System.Diagnostics/Process.xml @@ -110,7 +110,7 @@ If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. - A system process is uniquely identified on the system by its process identifier. Like many Windows resources, a process is also identified by its handle, which might not be unique on the computer. A handle is the generic term for an identifier of a resource. The operating system persists the process handle, which is accessed through the property of the component, even when the process has exited. Thus, you can get the process's administrative information, such as the (usually either zero for success or a nonzero error code) and the . Handles are an extremely valuable resource, so leaking handles is more virulent than leaking memory. + A system process is uniquely identified on the system by its process identifier. Like many Windows resources, a process is also identified by its handle, which might not be unique on the computer. A handle is the generic term for an identifier of a resource. The operating system persists the process handle, which is accessed through the property of the component, even when the process has exited. Thus, you can get the process's administrative information, such as the (usually either zero for success or a nonzero error code) and the . Handles are an extremely valuable resource, so leaking handles is more virulent than leaking memory. On macOS, the following properties return 0: @@ -127,7 +127,7 @@ On macOS, the following properties return 0: If a object depends on specific code page encodings, you can still make them available by doing the following *before* you call any methods: -1. Retrieve the object from the property. +1. Retrieve the object from the property. 2. Pass the object to the method to make the additional encodings supported by the encoding provider available. @@ -203,15 +203,15 @@ On macOS, the following properties return 0: property, the default is the local computer, ("."). + If you do not specify the property, the default is the local computer, ("."). - You have two options for associating a new component with a process on the computer. The first option is to use the constructor to create the component, set the appropriate members of the property and call to associate the with a new system process. The second option is to associate the with a running system process by using or one of the return values. + You have two options for associating a new component with a process on the computer. The first option is to use the constructor to create the component, set the appropriate members of the property and call to associate the with a new system process. The second option is to associate the with a running system process by using or one of the return values. If you use a `static` overload of the method to start a new system process, the method creates a new component and associates it with the process. - When the property is set to its default value, `true`, you can start applications and documents in a way that is similar to using the `Run` dialog box of the Windows `Start` menu. When is `false`, you can start only executables. + When the property is set to its default value, `true`, you can start applications and documents in a way that is similar to using the `Run` dialog box of the Windows `Start` menu. When is `false`, you can start only executables. - Any executable file that you can call from the command line can be started in one of two ways: by setting the appropriate members of the property and calling the method with no parameters, or by passing the appropriate parameter to the `static` member. + Any executable file that you can call from the command line can be started in one of two ways: by setting the appropriate members of the property and calling the method with no parameters, or by passing the appropriate parameter to the `static` member. You can create a component by using the constructor, one of the static overloads, or any of the , , or methods. After you have done so, you have a view into the associated process. This is not a dynamic view that updates itself automatically when the process properties have changed in memory. Instead, you must call for the component to update the property information in your application. @@ -279,7 +279,7 @@ On macOS, the following properties return 0: Based on the time elapsed or other boosts, the operating system can change the base priority when a process should be placed ahead of others. - The property lets you view the starting priority assigned to a process. However, because it is read-only, you cannot use the to set the priority of the process. To change the priority, use the property. The is viewable using the System Monitor, while the is not. Both the and the can be viewed programmatically. The following table shows the relationship between values and values. + The property lets you view the starting priority assigned to a process. However, because it is read-only, you cannot use the to set the priority of the process. To change the priority, use the property. The is viewable using the System Monitor, while the is not. Both the and the can be viewed programmatically. The following table shows the relationship between values and values. |BasePriority|PriorityClass| |------------------|-------------------| @@ -970,10 +970,10 @@ process.BeginOutputReadLine(); property suggests whether the component should be notified when the operating system has shut down a process. The property is used in asynchronous processing to notify your application that a process has exited. To force your application to synchronously wait for an exit event (which interrupts processing of the application until the exit event has occurred), use the method. +The property suggests whether the component should be notified when the operating system has shut down a process. The property is used in asynchronous processing to notify your application that a process has exited. To force your application to synchronously wait for an exit event (which interrupts processing of the application until the exit event has occurred), use the method. > [!NOTE] -> If you're using Visual Studio and double-click a component in your project, an event delegate and event handler are automatically generated. Additional code sets the property to `false`. You must change this property to `true` for your event handler to execute when the associated process exits. +> If you're using Visual Studio and double-click a component in your project, an event delegate and event handler are automatically generated. Additional code sets the property to `false`. You must change this property to `true` for your event handler to execute when the associated process exits. If the component's value is `true`, or when is `false` and a check is invoked by the component, the component can access the administrative information for the associated process, which remains stored by the operating system. Such information includes the and the . @@ -984,7 +984,7 @@ There's a cost associated with watching for a process to exit. If to `false` can save system resources. ## Examples -The following code example creates a process that prints a file. It sets the property to cause the process to raise the event when it exits. The event handler displays process information. +The following code example creates a process that prints a file. It sets the property to cause the process to raise the event when it exits. The event handler displays process information. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/EnableRaisingEvents/processexitedevent.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/EnableRaisingEvents/processexitedevent.fs" id="Snippet1"::: @@ -1199,7 +1199,7 @@ The following code example creates a process that prints a file. It sets the value of zero, and designate errors by nonzero values that the calling method can use to identify the cause of an abnormal process termination. It is not necessary to follow these guidelines, but they are the convention. - If you try to get the before the process has exited, the attempt throws an exception. Examine the property first to verify whether the associated process has terminated. + If you try to get the before the process has exited, the attempt throws an exception. Examine the property first to verify whether the associated process has terminated. > [!NOTE] > When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . @@ -1285,7 +1285,7 @@ The following code example creates a process that prints a file. It sets the event indicates that the associated process exited. This occurrence means either that the process terminated (aborted) or successfully closed. This event can occur only if the value of the property is `true`. + The event indicates that the associated process exited. This occurrence means either that the process terminated (aborted) or successfully closed. This event can occur only if the value of the property is `true`. There are two ways of being notified when the associated process exits: synchronously and asynchronously. Synchronous notification means calling the method to block the current thread until the process exits. Asynchronous notification uses the event, which allows the calling thread to continue execution in the meantime. In the latter case, must be set to `true` for the calling application to receive the Exited event. @@ -1294,12 +1294,12 @@ The following code example creates a process that prints a file. It sets the [!NOTE] > Even if you have a handle to an exited process, you cannot call again to reconnect to the same process. Calling automatically releases the associated process and connects to a process with the same file but an entirely new . - For more information about the use of the event in Windows Forms applications, see the property. + For more information about the use of the event in Windows Forms applications, see the property. ## Examples - The following code example creates a process that prints a file. It raises the event when the process exits because the property was set when the process was created. The event handler displays process information. + The following code example creates a process that prints a file. It raises the event when the process exits because the property was set when the process was created. The event handler displays process information. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/EnableRaisingEvents/processexitedevent.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/EnableRaisingEvents/processexitedevent.fs" id="Snippet1"::: @@ -1367,12 +1367,12 @@ The following code example creates a process that prints a file. It sets the property throws an exception. Use before getting the property to determine whether the associated process has terminated. + If the process has not terminated, attempting to retrieve the property throws an exception. Use before getting the property to determine whether the associated process has terminated. ## Examples - The following code example creates a process that prints a file. The process raises the event when it exits, and the event handler displays the property and other process information. + The following code example creates a process that prints a file. The process raises the event when it exits, and the event handler displays the property and other process information. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/EnableRaisingEvents/processexitedevent.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/EnableRaisingEvents/processexitedevent.fs" id="Snippet1"::: @@ -2084,7 +2084,7 @@ There are problems accessing the performance counter APIs used to get process in This process handle is private to an application. In other words, process handles cannot be shared. A process also has a process that, unlike the , is unique and, therefore, valid throughout the system. - Only processes started through a call to set the property of the corresponding instances. + Only processes started through a call to set the property of the corresponding instances. ]]> @@ -2308,11 +2308,11 @@ There are problems accessing the performance counter APIs used to get process in is not valid if the associated process is not running. Therefore, you should ensure that the process is running before attempting to retrieve the property. Until the process terminates, the process identifier uniquely identifies the process throughout the system. + The process is not valid if the associated process is not running. Therefore, you should ensure that the process is running before attempting to retrieve the property. Until the process terminates, the process identifier uniquely identifies the process throughout the system. - You can connect a process that is running on a local or remote computer to a new instance by passing the process identifier to the method. is a `static` method that creates a new component and sets the property for the new instance automatically. + You can connect a process that is running on a local or remote computer to a new instance by passing the process identifier to the method. is a `static` method that creates a new component and sets the property for the new instance automatically. - Process identifiers can be reused by the system. The property value is unique only while the associated process is running. After the process has terminated, the system can reuse the property value for an unrelated process. + Process identifiers can be reused by the system. The property value is unique only while the associated process is running. After the process has terminated, the system can reuse the property value for an unrelated process. Because the identifier is unique on the system, you can pass it to other threads as an alternative to passing a instance. This action can save system resources yet guarantee that the process is correctly identified. @@ -2357,10 +2357,10 @@ Therefore, the request to exit the process by closing the main window does not f > [!NOTE] > The method executes asynchronously. -> After calling the `Kill` method, call the method to wait for the process to exit, or check the property to determine if the process has exited. +> After calling the `Kill` method, call the method to wait for the process to exit, or check the property to determine if the process has exited. > [!NOTE] -> The method and the property do not reflect the status of descendant processes. +> The method and the property do not reflect the status of descendant processes. > When `Kill(entireProcessTree: true)` is used, and will indicate that exiting has completed after the given process exits, even if all descendants have not yet exited. Data edited by the process or resources allocated to the process can be lost if you call `Kill`. @@ -2620,7 +2620,7 @@ The calling process is a member of the associated process's descendant tree., , or on remote computers. > [!NOTE] -> When the associated process is executing on the local machine, this property returns a period (".") for the machine name. You should use the property to get the correct machine name. +> When the associated process is executing on the local machine, this property returns a period (".") for the machine name. You should use the property to get the correct machine name. @@ -2774,7 +2774,7 @@ If no main module is found, it could be because the process hasn't finished load ## Remarks The main window is the window opened by the process that currently has the focus (the form). You must use the method to refresh the object to get the most up to date main window handle if it has changed. In general, because the window handle is cached, use beforehand to guarantee that you'll retrieve the current handle. - You can get the property only for processes that are running on the local computer. The property is a value that uniquely identifies the window that is associated with the process. + You can get the property only for processes that are running on the local computer. The property is a value that uniquely identifies the window that is associated with the process. A process has a main window associated with it only if the process has a graphical interface. If the associated process does not have a main window, the value is zero. The value is also zero for processes that have been hidden, that is, processes that are not visible in the taskbar. This can be the case for processes that appear as icons in the notification area, at the far right of the taskbar. @@ -3579,7 +3579,7 @@ If no main module is found, it could be because the process hasn't finished load ## Remarks The value returned by this property represents the most recently refreshed size of memory in the virtual memory paging file used by the process, in bytes. To get the most up to date size, you need to call method first. - The operating system uses the virtual memory paging file in conjunction with physical memory to manage the virtual address space for each process. When pageable memory is not in use, it can be transferred to the virtual memory paging file on disk. To obtain the size of memory used by the operating system for the process, use the property. + The operating system uses the virtual memory paging file in conjunction with physical memory to manage the virtual address space for each process. When pageable memory is not in use, it can be transferred to the virtual memory paging file on disk. To obtain the size of memory used by the operating system for the process, use the property. This property can be used to monitor memory usage on computers with 32-bit processors or 64-bit processors. The property value is equivalent to the **Page File Bytes** performance counter for the process. @@ -3720,7 +3720,7 @@ If no main module is found, it could be because the process hasn't finished load property. + The value returned by this property value represents the current size of pageable system memory used by the process, in bytes. System memory is the physical memory used by the operating system, and is divided into paged and nonpaged pools. When pageable memory is not in use, it can be transferred to the virtual memory paging file on disk. To obtain the size of the application memory used by the process, use the property. This property can be used to monitor memory usage on computers with 32-bit processors or 64-bit processors. The property value is equivalent to the **Pool Paged Bytes** performance counter for the process. @@ -4232,7 +4232,7 @@ If no main module is found, it could be because the process hasn't finished load ## Remarks The value returned by this property represents the most recently refreshed temporary priority boost. To get the most up to date value, you need to call method first. - When a thread runs in a process for which the priority class has one of the dynamic priority enumeration values (, , or ), the system temporarily boosts the thread's priority when it is taken out of a wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all the existing threads and any threads subsequently created by the process. To restore normal behavior, set the property to `false`. + When a thread runs in a process for which the priority class has one of the dynamic priority enumeration values (, , or ), the system temporarily boosts the thread's priority when it is taken out of a wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all the existing threads and any threads subsequently created by the process. To restore normal behavior, set the property to `false`. > [!NOTE] > Boosting the priority too high can drain resources from essential operating system and network functions, causing problems with other operating system tasks. @@ -4305,7 +4305,7 @@ If no main module is found, it could be because the process hasn't finished load A process priority class encompasses a range of thread priority levels. Threads with different priorities that are running in the process run relative to the priority class of the process. Win32 uses four priority classes with seven base priority levels per class. These process priority classes are captured in the enumeration, which lets you set the process priority to , , , , , or . Based on the time elapsed or other boosts, the base priority level can be changed by the operating system when a process needs to be put ahead of others for access to the processor. In addition, you can set the to temporarily boost the priority level of threads that have been taken out of the wait state. The priority is reset when the process returns to the wait state. - The property lets you view the starting priority that is assigned to a process. However, because it is read-only, you cannot use the property to set the priority of a process. To change the priority, use the property, which gets or sets the overall priority category for the process. + The property lets you view the starting priority that is assigned to a process. However, because it is read-only, you cannot use the property to set the priority of a process. To change the priority, use the property, which gets or sets the overall priority category for the process. The priority class cannot be viewed using System Monitor. The following table shows the relationship between the and values. @@ -4611,10 +4611,10 @@ If no main module is found, it could be because the process hasn't finished load property holds an executable file name, such as Outlook, that does not include the .exe extension or the path. It is helpful for getting and manipulating all the processes that are associated with the same executable file. + The property holds an executable file name, such as Outlook, that does not include the .exe extension or the path. It is helpful for getting and manipulating all the processes that are associated with the same executable file. > [!NOTE] -> On Windows 2000 operating systems, the property may be truncated to 15 characters if the process module information cannot be obtained. +> On Windows 2000 operating systems, the property may be truncated to 15 characters if the process module information cannot be obtained. You can call , passing it an executable file name, to retrieve an array that contains every running instance on the specified computer. You can use this array, for example, to shut down all the running instances of the executable file. @@ -4840,7 +4840,7 @@ If no main module is found, it could be because the process hasn't finished load ## Remarks The value returned by this property represents the most recently refreshed status. To get the most up to date status, you need to call method first. - If a process has a user interface, the property contacts the user interface to determine whether the process is responding to user input. If the interface does not respond immediately, the property returns `false`. Use this property to determine whether the interface of the associated process has stopped responding. + If a process has a user interface, the property contacts the user interface to determine whether the process is responding to user input. If the interface does not respond immediately, the property returns `false`. Use this property to determine whether the interface of the associated process has stopped responding. If the process does not have a , this property returns `true`. @@ -4971,7 +4971,7 @@ If no main module is found, it could be because the process hasn't finished load property identifies the session in which the application is currently running. + The property identifies the session in which the application is currently running. ]]> @@ -5357,7 +5357,7 @@ There is a similar issue when you read all text from both the standard output an component. The return value `true` indicates that a new process resource was started. If the process resource specified by the member of the property is already running on the computer, no additional process resource is started. Instead, the running process resource is reused and `false` is returned. + Use this overload to start a process resource and associate it with the current component. The return value `true` indicates that a new process resource was started. If the process resource specified by the member of the property is already running on the computer, no additional process resource is started. Instead, the running process resource is reused and `false` is returned. You can start a ClickOnce application by specifying the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard drive. @@ -5366,22 +5366,22 @@ There is a similar issue when you read all text from both the standard output an > [!NOTE] > If you are using Visual Studio, this overload of the method is the one that you insert into your code after you drag a component onto the designer. Use the `Properties` window to expand the `StartInfo` category and write the appropriate value into the `FileName` property. Your changes will appear in the form's `InitializeComponent` procedure. - This overload of is not a `static` method. You must call it from an instance of the class. Before calling , you must first specify property information for this instance, because that information is used to determine the process resource to start. + This overload of is not a `static` method. You must call it from an instance of the class. Before calling , you must first specify property information for this instance, because that information is used to determine the process resource to start. The other overloads of the method are `static` members. You do not need to create an instance of the component before you call those overloads of the method. Instead, you can call for the class itself, and a new component is created if the process was started. Or, `null` is returned if a process was reused. The process resource is automatically associated with the new component that is returned by the method. - The members can be used to duplicate the functionality of the `Run` dialog box of the Windows `Start` menu. Anything that can be typed into a command line can be started by setting the appropriate values in the property. The only property that must be set is the property. The property does not have to be an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. + The members can be used to duplicate the functionality of the `Run` dialog box of the Windows `Start` menu. Anything that can be typed into a command line can be started by setting the appropriate values in the property. The only property that must be set is the property. The property does not have to be an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. - In the command line, you can specify actions to take for certain types of files. For example, you can print documents or edit text files. Specify these actions using the member of the property. For other types of files, you can specify command-line arguments when you start the file from the `Run` dialog box. For example, you can pass a URL as an argument if you specify your browser as the . These arguments can be specified in the property's member. + In the command line, you can specify actions to take for certain types of files. For example, you can print documents or edit text files. Specify these actions using the member of the property. For other types of files, you can specify command-line arguments when you start the file from the `Run` dialog box. For example, you can pass a URL as an argument if you specify your browser as the . These arguments can be specified in the property's member. If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. > [!NOTE] > ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. @@ -5487,11 +5487,11 @@ The member This overload lets you start a process without first creating a new instance. Using this overload with a parameter is an alternative to the explicit steps of creating a new instance, setting its properties, and calling for the instance. - Using a instance as the parameter lets you call with the most control over what is passed into the call to start the process. If you need to pass only a file name or a file name and arguments, it is not necessary to create a new instance, although that is an option. The only property that must be set is the property. The property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. + Using a instance as the parameter lets you call with the most control over what is passed into the call to start the process. If you need to pass only a file name or a file name and arguments, it is not necessary to create a new instance, although that is an option. The only property that must be set is the property. The property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. You can start a ClickOnce application by specifying the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard drive. - If the and properties of the instance are set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . If the property is `null`, the property must be in UPN format, *user*@*DNS_domain_name*. + If the and properties of the instance are set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . If the property is `null`, the property must be in UPN format, *user*@*DNS_domain_name*. Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the start information for the process resource by using a instance. @@ -5500,7 +5500,7 @@ The member > [!NOTE] > ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. A note about apartment states in managed threads is necessary here. When is `true` on the `startInfo` parameter, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. @@ -5614,7 +5614,7 @@ The member > [!NOTE] > If the address of the executable file to start is a URL, the process is not started and `null` is returned. - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the member of the property, and calling for the instance. + This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the member of the property, and calling for the instance. You can start a ClickOnce application by setting the `fileName` parameter to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard drive. @@ -5629,9 +5629,9 @@ The member > [!NOTE] > ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. @@ -5787,7 +5787,7 @@ The file specified in the could not be found. [!NOTE] > If the address of the executable file to start is a URL, the process is not started and `null` is returned. - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the and members of the property, and calling for the instance. + This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the and members of the property, and calling for the instance. Starting a process by specifying its file name and arguments is similar to typing the file name and command-line arguments in the `Run` dialog box of the Windows `Start` menu. Therefore, the file name does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the file name can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the `Run` dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. If the `fileName` parameter represents a command (.cmd) file, the `arguments` parameter must include either a "`/c`" or "`/k`" argument to specify whether the command window exits or remains after completion. @@ -5798,9 +5798,9 @@ The file specified in the could not be found. [!NOTE] > ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. @@ -5911,14 +5911,14 @@ The file specified in the could not be found. > [!NOTE] > If the address of the executable file to start is a URL, the process is not started and `null` is returned. - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , and properties of the property, and calling for the instance. + This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , and properties of the property, and calling for the instance. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. > [!NOTE] > The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. @@ -6022,14 +6022,14 @@ The file specified in the could not be found. [!NOTE] > If the address of the executable file to start is a URL, the process is not started and `null` is returned. - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , , and properties of the property, and calling for the instance. + This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , , and properties of the property, and calling for the instance. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. > [!NOTE] > The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. ]]> @@ -6105,17 +6105,17 @@ The file specified in the could not be found. represents the set of parameters to use to start a process. When is called, the is used to specify the process to start. The only necessary member to set is the property. Starting a process by specifying the property is similar to typing the information in the **Run** dialog box of the Windows **Start** menu. Therefore, the property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the member. For example, you can set the property to either "Notepad.exe" or "Notepad". + represents the set of parameters to use to start a process. When is called, the is used to specify the process to start. The only necessary member to set is the property. Starting a process by specifying the property is similar to typing the information in the **Run** dialog box of the Windows **Start** menu. Therefore, the property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the member. For example, you can set the property to either "Notepad.exe" or "Notepad". - You can start a ClickOnce application by setting the property to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard drive. + You can start a ClickOnce application by setting the property to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard drive. - If the file name involves a nonexecutable file, such as a .doc file, you can include a verb specifying what action to take on the file. For example, you could set the to "Print" for a file ending in the .doc extension. The file name specified in the property does not need to have an extension if you manually enter a value for the property. However, if you use the property to determine what verbs are available, you must include the extension. + If the file name involves a nonexecutable file, such as a .doc file, you can include a verb specifying what action to take on the file. For example, you could set the to "Print" for a file ending in the .doc extension. The file name specified in the property does not need to have an extension if you manually enter a value for the property. However, if you use the property to determine what verbs are available, you must include the extension. - You can change the parameters specified in the property up to the time that you call the method on the process. After you start the process, changing the values does not affect or restart the associated process. If you call the method with the and properties set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . + You can change the parameters specified in the property up to the time that you call the method on the process. After you start the process, changing the values does not affect or restart the associated process. If you call the method with the and properties set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . - You should only access the property on a object returned by the method. For example, you should not access the property on a object returned by . Otherwise, on .NET Core the property will throw an and on .NET Framework it will return a dummy object. + You should only access the property on a object returned by the method. For example, you should not access the property on a object returned by . Otherwise, on .NET Core the property will throw an and on .NET Framework it will return a dummy object. - When the process is started, the file name is the file that populates the (read-only) property. If you want to retrieve the executable file that is associated with the process after the process has started, use the property. If you want to set the executable file of a instance for which an associated process has not been started, use the property's member. Because the members of the property are arguments that are passed to the method of a process, changing the property after the associated process has started will not reset the property. These properties are used only to initialize the associated process. + When the process is started, the file name is the file that populates the (read-only) property. If you want to retrieve the executable file that is associated with the process after the process has started, use the property. If you want to set the executable file of a instance for which an associated process has not been started, use the property's member. Because the members of the property are arguments that are passed to the method of a process, changing the property after the associated process has started will not reset the property. These properties are used only to initialize the associated process. ## Examples The following example populates a with the file to execute, the action performed on it and whether it should displays a user interface. For additional examples, refer to the reference pages for properties of the class. @@ -6274,7 +6274,7 @@ The file specified in the could not be found. When the event is handled by a visual Windows Forms component, such as a , accessing the component through the system thread pool might not work, or might result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods handling the event 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, is automatically set 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`: + If the is used inside Visual Studio 2005 in a Windows Forms designer, is automatically set 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`: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/SynchronizingObject/remarks.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Diagnostics/Process/SynchronizingObject/remarks.fs" id="Snippet2"::: @@ -6790,12 +6790,12 @@ The file specified in the could not be found. When an associated process exits (that is, when it is shut down by the operation system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. - Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. + Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. ## Examples - See the Remarks section of the property reference page. + See the Remarks section of the property reference page. ]]> @@ -6874,16 +6874,16 @@ The file specified in the could not be found. > [!NOTE] > In the .NET Framework 3.5 and earlier versions, if `milliseconds` was -1, the overload waited for milliseconds (approximately 24 days), not indefinitely. - When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this method returns. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter after receiving a `true` from this overload. To help ensure that the event is handled correctly in Windows Forms applications, set the property. + When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this method returns. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter after receiving a `true` from this overload. To help ensure that the event is handled correctly in Windows Forms applications, set the property. When an associated process exits (is shut down by the operating system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. - Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. + Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. ## Examples - See the code example for the property. + See the code example for the property. ]]> diff --git a/xml/System.Diagnostics/ProcessModule.xml b/xml/System.Diagnostics/ProcessModule.xml index cae4eb9c4f6..878d3718ea9 100644 --- a/xml/System.Diagnostics/ProcessModule.xml +++ b/xml/System.Diagnostics/ProcessModule.xml @@ -83,7 +83,7 @@ ## Examples The following code sample demonstrates how to use the class to get and display information about all the modules that are used by the Notepad.exe application. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessModule/Overview/processmodule.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessModule/Overview/processmodule.vb" id="Snippet1"::: @@ -460,7 +460,7 @@ ## Examples - The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The property is used to display the name of each module. + The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The property is used to display the name of each module. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessModule/ModuleName/processmodule_modulename.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessModule/ModuleName/processmodule_modulename.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/ProcessStartInfo.xml b/xml/System.Diagnostics/ProcessStartInfo.xml index d10cf5c4c3d..4a99f7fec7f 100644 --- a/xml/System.Diagnostics/ProcessStartInfo.xml +++ b/xml/System.Diagnostics/ProcessStartInfo.xml @@ -62,13 +62,13 @@ ## Remarks is used together with the component. When you start a process using the class, you have access to process information in addition to that available when attaching to a running process. - You can use the class for better control over the process you start. You must at least set the property, either manually or using the constructor. The file name is any application or document. Here a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + You can use the class for better control over the process you start. You must at least set the property, either manually or using the constructor. The file name is any application or document. Here a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. - In addition, you can set other properties that define actions to take with that file. You can specify a value specific to the type of the property for the property. For example, you can specify "print" for a document type. Additionally, you can specify property values to be command-line arguments to pass to the file's open procedure. For example, if you specify a text editor application in the property, you can use the property to specify a text file to be opened by the editor. + In addition, you can set other properties that define actions to take with that file. You can specify a value specific to the type of the property for the property. For example, you can specify "print" for a document type. Additionally, you can specify property values to be command-line arguments to pass to the file's open procedure. For example, if you specify a text editor application in the property, you can use the property to specify a text file to be opened by the editor. Standard input is usually the keyboard, and standard output and standard error are usually the monitor screen. However, you can use the , , and properties to cause the process to get input from or return output to a file or other device. If you use the , , or properties on the component, you must first set the corresponding value on the property. Otherwise, the system throws an exception when you read or write to the stream. - Set the property to specify whether to start the process by using the operating system shell. If is set to `false`, the new process inherits the standard input, standard output, and standard error streams of the calling process, unless the , , or properties, respectively, are set to `true`. + Set the property to specify whether to start the process by using the operating system shell. If is set to `false`, the new process inherits the standard input, standard output, and standard error streams of the calling process, unless the , , or properties, respectively, are set to `true`. You can change the value of any property up to the time that the process starts. After you start the process, changing these values has no effect. @@ -138,9 +138,9 @@ property before you start the process. The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + You must set at least the property before you start the process. The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. - Optionally, you can also set other properties before you start the process. The property supplies actions to take, such as "print", with the file indicated in the property. The property supplies a way to pass command-line arguments to the file when the system opens it. + Optionally, you can also set other properties before you start the process. The property supplies actions to take, such as "print", with the file indicated in the property. The property supplies a way to pass command-line arguments to the file when the system opens it. [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] @@ -194,7 +194,7 @@ ## Remarks The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. - You can change the property after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect. + You can change the property after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect. [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] @@ -568,7 +568,7 @@ If you use this property to set command-line arguments, property is `true` or the and properties are not `null`, the property value is ignored and a new window is created. + If the property is `true` or the and properties are not `null`, the property value is ignored and a new window is created. .NET Core does not support creating windows directly on Unix-like platforms, including macOS and Linux. This property is ignored on such platforms. @@ -699,9 +699,9 @@ If you use this property to set command-line arguments, property, you can modify the generic dictionary returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.Environment.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. + The environment variables contain search paths for files, directories for temporary files, application-specific options, and other similar information. Although you cannot directly set the property, you can modify the generic dictionary returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.Environment.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. - On .NET Framework applications, using the property is the same as using the property. + On .NET Framework applications, using the property is the same as using the property. ]]> @@ -783,7 +783,7 @@ If you use this property to set command-line arguments, property, you can modify the returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.EnvironmentVariables.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. + Although you cannot set the property, you can modify the returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.EnvironmentVariables.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. ]]> @@ -924,7 +924,7 @@ If you use this property to set command-line arguments, is `true`, the property specifies the parent window for the dialog box that is shown. It is useful to specify a parent to keep the dialog box in front of the application. + If is `true`, the property specifies the parent window for the dialog box that is shown. It is useful to specify a parent to keep the dialog box in front of the application. ]]> @@ -1024,11 +1024,11 @@ If you use this property to set command-line arguments, property before you start the process. The file name is any application or document. A document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + You must set at least the property before you start the process. The file name is any application or document. A document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. - The set of file types available to you depends in part on the value of the property. If is `true`, you can start any document and perform operations on the file, such as printing, with the component. When is `false`, you can start only executables with the component. + The set of file types available to you depends in part on the value of the property. If is `true`, you can start any document and perform operations on the file, such as printing, with the component. When is `false`, you can start only executables with the component. - You can start a ClickOnce application by setting the property to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard disk. + You can start a ClickOnce application by setting the property to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard disk. [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] @@ -1181,7 +1181,7 @@ If you use this property to set command-line arguments, [!IMPORTANT] -> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. +> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. > [!NOTE] > Setting the , , and the properties in a object is the recommended practice for starting a process with user credentials. @@ -1191,7 +1191,7 @@ If you use this property to set command-line arguments, class. > [!NOTE] -> If you provide a value for the property, the property must be `false`, or an will be thrown when the method is called. +> If you provide a value for the property, the property must be `false`, or an will be thrown when the method is called. ]]> @@ -1621,7 +1621,7 @@ You can use asynchronous read operations to avoid these dependencies and their d property is `null`, the process uses the default standard error encoding for error output. The property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding; the process will use only those encodings that it supports. The application should be tested to determine which encodings are supported. + If the value of the property is `null`, the process uses the default standard error encoding for error output. The property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding; the process will use only those encodings that it supports. The application should be tested to determine which encodings are supported. ]]> @@ -1732,7 +1732,7 @@ You can use asynchronous read operations to avoid these dependencies and their d property is `null`, the process uses the default standard output encoding for the standard output. The property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding. The application should be tested to determine which encodings the process supports. + If the value of the property is `null`, the process uses the default standard output encoding for the standard output. The property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding. The application should be tested to determine which encodings the process supports. ]]> @@ -1834,9 +1834,9 @@ You can use asynchronous read operations to avoid these dependencies and their d ## Remarks > [!IMPORTANT] -> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. +> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. - If the property is not `null` or an empty string, the property must be `false`, or an will be thrown when the method is called. + If the property is not `null` or an empty string, the property must be `false`, or an will be thrown when the method is called. ]]> @@ -1996,13 +1996,13 @@ You can use asynchronous read operations to avoid these dependencies and their d ## Remarks -Each file name extension has its own set of verbs, which can be obtained by using the property. For example, the "`print`" verb prints a document specified by using . The default verb can be specified by using an empty string (""). Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". You should use only verbs that appear in the set of verbs returned by the property. +Each file name extension has its own set of verbs, which can be obtained by using the property. For example, the "`print`" verb prints a document specified by using . The default verb can be specified by using an empty string (""). Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". You should use only verbs that appear in the set of verbs returned by the property. -When you use the property, you must include the file name extension when you set the value of the property. The file name does not need to have an extension if you manually enter a value for the property. +When you use the property, you must include the file name extension when you set the value of the property. The file name does not need to have an extension if you manually enter a value for the property. ## Examples -The following code example starts a new process by using the specified verb and file name. This code example is part of a larger example provided for the property. +The following code example starts a new process by using the specified verb and file name. This code example is part of a larger example provided for the property. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessStartInfo/Verb/source.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessStartInfo/Verb/source.vb" id="Snippet4"::: @@ -2065,11 +2065,11 @@ The following code example starts a new process by using the specified verb and property enables you to determine the verbs that can be used with the file specified by the property. You can set the property to the value of any verb in the set. Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". + The property enables you to determine the verbs that can be used with the file specified by the property. You can set the property to the value of any verb in the set. Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". Be aware that the resulting list of verbs may not contain all possible values, e.g. "New" is by design not added to the list and other possible verbs are not always detected depending on your system setup. - When you use the property, you must include the file name extension when you set the value of the property. The file name extension determines the set of possible verbs. + When you use the property, you must include the file name extension when you set the value of the property. The file name extension determines the set of possible verbs. ## Examples The following code example displays the defined verbs for the chosen file name. If the user selects one of the defined verbs, the example starts a new process using the selected verb and the input file name. @@ -2251,16 +2251,16 @@ The following code example starts a new process by using the specified verb and ## Remarks > [!IMPORTANT] -> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. +> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. If the directory is already part of the system path variable, you do not have to repeat the directory's location in this property. - The property behaves differently when is `true` than when is `false`. When is `true`, the property specifies the location of the executable. If is an empty string, the current directory is understood to contain the executable. + The property behaves differently when is `true` than when is `false`. When is `true`, the property specifies the location of the executable. If is an empty string, the current directory is understood to contain the executable. > [!NOTE] > When is `true`, the working directory of the application that starts the executable is also the working directory of the executable. - When is `false`, the property is not used to find the executable. Instead, its value applies to the process that is started and only has meaning within the context of the new process. + When is `false`, the property is not used to find the executable. Instead, its value applies to the process that is started and only has meaning within the context of the new process. ]]> diff --git a/xml/System.Diagnostics/ProcessThread.xml b/xml/System.Diagnostics/ProcessThread.xml index b4b0eb7c7be..05b2b66f8b9 100644 --- a/xml/System.Diagnostics/ProcessThread.xml +++ b/xml/System.Diagnostics/ProcessThread.xml @@ -67,31 +67,31 @@ Represents an operating system process thread. - to obtain information about a thread that is currently running on the system. Doing so allows you, for example, to monitor the thread's performance characteristics. - + to obtain information about a thread that is currently running on the system. Doing so allows you, for example, to monitor the thread's performance characteristics. + > [!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. - - A thread is a path of execution through a program. It is the smallest unit of execution that Win32 schedules. It consists of a stack, the state of the CPU registers, and an entry in the execution list of the system scheduler. - - A process consists of one or more threads and the code, data, and other resources of a program in memory. Typical program resources are open files, semaphores, and dynamically allocated memory. Each resource of a process is shared by all that process's threads. - - A program executes when the system scheduler gives execution control to one of the program's threads. The scheduler determines which threads should run and when. A lower-priority thread might be forced to wait while higher-priority threads complete their tasks. On multiprocessor computers, the scheduler can move individual threads to different processors, thus balancing the CPU load. - - Each process starts with a single thread, which is known as the primary thread. Any thread can create additional threads. All the threads within a process share the address space of that process. - - The primary thread is not necessarily located at the first index in the collection. - +> 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. + + A thread is a path of execution through a program. It is the smallest unit of execution that Win32 schedules. It consists of a stack, the state of the CPU registers, and an entry in the execution list of the system scheduler. + + A process consists of one or more threads and the code, data, and other resources of a program in memory. Typical program resources are open files, semaphores, and dynamically allocated memory. Each resource of a process is shared by all that process's threads. + + A program executes when the system scheduler gives execution control to one of the program's threads. The scheduler determines which threads should run and when. A lower-priority thread might be forced to wait while higher-priority threads complete their tasks. On multiprocessor computers, the scheduler can move individual threads to different processors, thus balancing the CPU load. + + Each process starts with a single thread, which is known as the primary thread. Any thread can create additional threads. All the threads within a process share the address space of that process. + + The primary thread is not necessarily located at the first index in the collection. + > [!NOTE] -> Starting with the .NET Framework version 2.0, the ability to reference performance counter data on other computers has been eliminated for many of the .NET Framework methods and properties. This change was made to improve performance and to enable non-administrators to use the class. As a result, some applications that did not get exceptions in earlier versions of the .NET Framework may now get a . The methods and properties affected are too numerous to list here, but the exception information has been added to the affected member topics. - - The threads of a process execute individually and are unaware of each other unless you make them visible to each other. Threads that share common resources, however, must coordinate their work by using semaphores or another method of interprocess communication. - - To get a collection of all the objects associated with the current process, get the property of the instance. - +> Starting with the .NET Framework version 2.0, the ability to reference performance counter data on other computers has been eliminated for many of the .NET Framework methods and properties. This change was made to improve performance and to enable non-administrators to use the class. As a result, some applications that did not get exceptions in earlier versions of the .NET Framework may now get a . The methods and properties affected are too numerous to list here, but the exception information has been added to the affected member topics. + + The threads of a process execute individually and are unaware of each other unless you make them visible to each other. Threads that share common resources, however, must coordinate their work by using semaphores or another method of interprocess communication. + + To get a collection of all the objects associated with the current process, get the property of the instance. + ]]> @@ -145,15 +145,15 @@ Gets the base priority of the thread. The base priority of the thread, which the operating system computes by combining the process priority class with the priority level of the associated thread. - is the starting priority for the process thread. You can view information about the base priority through the System Monitor's Priority Base counter. - - The operating system computes a thread's base priority by combining the thread's priority level range with the process's priority class. You can set the process's property to one of the values in the enumeration, which are , , , , , or . You can set the thread's property to a range of values that bounds the thread's base priority. Win32 uses four priority classes with seven base priority levels per class. - - The thread's current priority might deviate from the base priority. For example, the operating system can change the property based on the time elapsed or other boosts when a process must be put ahead of others for access to the processor. In addition, you can set the property to cause the system to temporarily boost the priority of a thread whenever the process is taken out of the wait state. The priority is reset when the process returns to the wait state. - + is the starting priority for the process thread. You can view information about the base priority through the System Monitor's Priority Base counter. + + The operating system computes a thread's base priority by combining the thread's priority level range with the process's priority class. You can set the process's property to one of the values in the enumeration, which are , , , , , or . You can set the thread's property to a range of values that bounds the thread's base priority. Win32 uses four priority classes with seven base priority levels per class. + + The thread's current priority might deviate from the base priority. For example, the operating system can change the property based on the time elapsed or other boosts when a process must be put ahead of others for access to the processor. In addition, you can set the property to cause the system to temporarily boost the priority of a thread whenever the process is taken out of the wait state. The priority is reset when the process returns to the wait state. + ]]> @@ -209,11 +209,11 @@ Gets the current priority of the thread. The current priority of the thread, which may deviate from the base priority based on how the operating system is scheduling the thread. The priority may be temporarily boosted for an active thread. - property based on the time elapsed, or other boosts, when a process must be put ahead of others for access to the processor. In addition, you can set the property to cause the system to temporarily boost the priority of a thread whenever the process is taken out of the wait state. The priority is reset when the process returns to the wait state. - + property based on the time elapsed, or other boosts, when a process must be put ahead of others for access to the processor. In addition, you can set the property to cause the system to temporarily boost the priority of a thread whenever the process is taken out of the wait state. The priority is reset when the process returns to the wait state. + ]]> @@ -267,11 +267,11 @@ Gets the unique identifier of the thread. The unique identifier associated with a specific thread. - @@ -323,23 +323,23 @@ Sets the preferred processor for this thread to run on. The preferred processor for the thread, used when the system schedules threads, to determine which processor to run the thread on. - value is zero-based. In other words, to set the thread affinity for the first processor, set the property to zero. - - The system schedules threads on their preferred processors whenever possible. - - A process thread can migrate from processor to processor, with each migration reloading the processor cache. Specifying a processor for a thread can improve performance under heavy system loads by reducing the number of times the processor cache is reloaded. - - - -## Examples - The following example demonstrates how to set the property for an instance of Notepad to the first processor. - + value is zero-based. In other words, to set the thread affinity for the first processor, set the property to zero. + + The system schedules threads on their preferred processors whenever possible. + + A process thread can migrate from processor to processor, with each migration reloading the processor cache. Specifying a processor for a thread can improve performance under heavy system loads by reducing the number of times the processor cache is reloaded. + + + +## Examples + The following example demonstrates how to set the property for an instance of Notepad to the first processor. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessThread/IdealProcessor/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessThread/IdealProcessor/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessThread/IdealProcessor/program.vb" id="Snippet1"::: + ]]> The system could not set the thread to start on the specified processor. @@ -394,22 +394,22 @@ to boost the thread's priority when the user interacts with the process's interface; otherwise, . The default is . - is `true`, the system temporarily boosts the thread's priority whenever its associated process is taken out of the wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all existing threads as well as any threads subsequently created by the process. To restore normal behavior, set the property to `false`. - - has an effect only when the thread is running in a process that has a set to one of the dynamic priority enumeration values (, , or ). - + is `true`, the system temporarily boosts the thread's priority whenever its associated process is taken out of the wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all existing threads as well as any threads subsequently created by the process. To restore normal behavior, set the property to `false`. + + has an effect only when the thread is running in a process that has a set to one of the dynamic priority enumeration values (, , or ). + > [!NOTE] -> Boosting the priority too high can drain resources from essential operating system and network functions. This could cause problems with other operating system tasks. - +> Boosting the priority too high can drain resources from essential operating system and network functions. This could cause problems with other operating system tasks. + ]]> - The priority boost information could not be retrieved. - - -or- - + The priority boost information could not be retrieved. + + -or- + The priority boost information could not be set. The process is on a remote computer. @@ -478,17 +478,17 @@ Gets or sets the priority level of the thread. One of the values, specifying a range that bounds the thread's priority. - to choose a value from the range specified in the property. - + to choose a value from the range specified in the property. + ]]> - The thread priority level information could not be retrieved. - - -or- - + The thread priority level information could not be retrieved. + + -or- + The thread priority level could not be set. The process is on a remote computer. @@ -556,13 +556,13 @@ Gets the amount of time that the thread has spent running code inside the operating system core. A indicating the amount of time that the thread has spent running code inside the operating system core. - corresponds to the amount of time that the application has spent running in privileged mode, inside the operating system core. The property indicates the amount of time that the application has spent running code in user mode, outside the system core. - - User mode restricts the application in two important ways. First, the application cannot directly access the peripherals, but instead must call the operating system core to get or set peripheral data. The operating system can thus ensure that one application does not destroy peripheral data that is needed by another. Second, the application cannot read or change data that the operating system itself maintains. This restriction prevents applications from either inadvertently or intentionally corrupting the core. If the application needs the operating system to perform an operation, it calls one of the system's routines. Many of these transition into privileged mode, perform the operation, and smoothly return to user mode. - + corresponds to the amount of time that the application has spent running in privileged mode, inside the operating system core. The property indicates the amount of time that the application has spent running code in user mode, outside the system core. + + User mode restricts the application in two important ways. First, the application cannot directly access the peripherals, but instead must call the operating system core to get or set peripheral data. The operating system can thus ensure that one application does not destroy peripheral data that is needed by another. Second, the application cannot read or change data that the operating system itself maintains. This restriction prevents applications from either inadvertently or intentionally corrupting the core. If the application needs the operating system to perform an operation, it calls one of the system's routines. Many of these transition into privileged mode, perform the operation, and smoothly return to user mode. + ]]> The thread time could not be retrieved. @@ -622,33 +622,33 @@ Sets the processors on which the associated thread can run. An that points to a set of bits, each of which represents a processor that the thread can run on. - represents each processor as a bit. Bit 0 represents processor one, bit 1 represents processor two, and so on. The following table shows a subset of the possible for a four-processor system. - -|Property value (in hexadecimal)|Valid processors| -|---------------------------------------|----------------------| -|0x0001|1| -|0x0002|2| -|0x0003|1 or 2| -|0x0004|3| -|0x0005|1 or 3| -|0x0007|1, 2, or 3| -|0x000F|1, 2, 3, or 4| - - You can also specify the single, preferred processor for a thread by setting the property. A process thread can migrate from processor to processor, with each migration reloading the processor cache. Specifying a processor for a thread can improve performance under heavy system loads by reducing the number of times the processor cache is reloaded. - - - -## Examples - The following example shows how to set the property for an instance of Notepad to the first processor. - + represents each processor as a bit. Bit 0 represents processor one, bit 1 represents processor two, and so on. The following table shows a subset of the possible for a four-processor system. + +|Property value (in hexadecimal)|Valid processors| +|---------------------------------------|----------------------| +|0x0001|1| +|0x0002|2| +|0x0003|1 or 2| +|0x0004|3| +|0x0005|1 or 3| +|0x0007|1, 2, or 3| +|0x000F|1, 2, 3, or 4| + + You can also specify the single, preferred processor for a thread by setting the property. A process thread can migrate from processor to processor, with each migration reloading the processor cache. Specifying a processor for a thread can improve performance under heavy system loads by reducing the number of times the processor cache is reloaded. + + + +## Examples + The following example shows how to set the property for an instance of Notepad to the first processor. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessThread/IdealProcessor/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessThread/IdealProcessor/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/ProcessThread/IdealProcessor/program.vb" id="Snippet1"::: + ]]> The processor affinity could not be set. @@ -755,15 +755,15 @@ Gets the memory address of the function that the operating system called that started this thread. The thread's starting address, which points to the application-defined function that the thread executes. - property allows you to get the starting function address that is specific to your application. - + property allows you to get the starting function address that is specific to your application. + ]]> The process is on a remote computer. @@ -875,11 +875,11 @@ Gets the current state of this thread. A that indicates the thread's execution, for example, running, waiting, or terminated. - property value is valid only when the value is . Therefore, check the value before you get the property. - + property value is valid only when the value is . Therefore, check the value before you get the property. + ]]> The process is on a remote computer. @@ -944,13 +944,13 @@ Gets the total amount of time that this thread has spent using the processor. A that indicates the amount of time that the thread has had control of the processor. - property indicates the total amount of time that the system has taken the thread out of the wait state and given it priority on any processor. On a multiple processor system, this value would include time spent on each processor, if the thread used more than one processor. - - The property is the sum of the and properties. - + property indicates the total amount of time that the system has taken the thread out of the wait state and given it priority on any processor. On a multiple processor system, this value would include time spent on each processor, if the thread used more than one processor. + + The property is the sum of the and properties. + ]]> The thread time could not be retrieved. @@ -1018,13 +1018,13 @@ Gets the amount of time that the associated thread has spent running code inside the application. A indicating the amount of time that the thread has spent running code inside the application, as opposed to inside the operating system core. - corresponds to the amount of time that the application has spent running in user mode, outside the operating system core. The corresponds to the amount of time that the application has spent running code in privileged mode, inside the system core. - - User mode restricts the application in two important ways. First, the application cannot directly access the peripherals, but instead must call the operating system core to get or set peripheral data. The operating system can thus ensure that one application does not destroy peripheral data that is needed by another. Second, the application cannot read or change data that the operating system itself maintains. This restriction prevents applications from either inadvertently or intentionally corrupting the core. If the application needs the operating system to perform an operation, it calls one of the system's routines. Many of these transition into privileged mode, perform the operation, and smoothly return to user mode. - + corresponds to the amount of time that the application has spent running in user mode, outside the operating system core. The corresponds to the amount of time that the application has spent running code in privileged mode, inside the system core. + + User mode restricts the application in two important ways. First, the application cannot directly access the peripherals, but instead must call the operating system core to get or set peripheral data. The operating system can thus ensure that one application does not destroy peripheral data that is needed by another. Second, the application cannot read or change data that the operating system itself maintains. This restriction prevents applications from either inadvertently or intentionally corrupting the core. If the application needs the operating system to perform an operation, it calls one of the system's routines. Many of these transition into privileged mode, perform the operation, and smoothly return to user mode. + ]]> The thread time could not be retrieved. @@ -1080,11 +1080,11 @@ Gets the reason that the thread is waiting. A representing the reason that the thread is in the wait state. - property is valid only when the is . Therefore, check the value before you get the property. - + property is valid only when the is . Therefore, check the value before you get the property. + ]]> The thread is not in the wait state. diff --git a/xml/System.Diagnostics/SourceFilter.xml b/xml/System.Diagnostics/SourceFilter.xml index f03003ee2c2..8590f04497a 100644 --- a/xml/System.Diagnostics/SourceFilter.xml +++ b/xml/System.Diagnostics/SourceFilter.xml @@ -52,18 +52,18 @@ Indicates whether a listener should trace a message based on the source of a trace. - overrides the method and defines a property that specifies the name of the trace source to be traced by the listener. - + overrides the method and defines a property that specifies the name of the trace source to be traced by the listener. + > [!NOTE] -> This filter is provided because multiple trace sources can simultaneously use the same trace listener. - +> This filter is provided because multiple trace sources can simultaneously use the same trace listener. + ]]> @@ -108,19 +108,19 @@ The name of the trace source. Initializes a new instance of the class, specifying the name of the trace source. - property. - - - -## Examples - The following code example calls the method using two different source filters, one with a fictitious name, the other with the name of the current trace source. In the first case, the trace is not written to the console; in the second case, the trace is written. This code example is part of a larger example provided for the class. - + property. + + + +## Examples + The following code example calls the method using two different source filters, one with a fictitious name, the other with the name of the current trace source. In the first case, the trace is not written to the console; in the second case, the trace is written. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SourceFilter/.ctor/program.cs" id="Snippet28"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet28"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet28"::: + ]]> @@ -199,11 +199,11 @@ if the trace should be produced; otherwise, . - property, the method returns `true`. - + property, the method returns `true`. + ]]> @@ -256,11 +256,11 @@ Gets or sets the name of the trace source. The name of the trace source. - identifies the trace source for which to write trace information. Trace information will not be written for other trace sources. The name of the trace source is the `name` parameter from the constructor for the . - + identifies the trace source for which to write trace information. Trace information will not be written for other trace sources. The name of the trace source is the `name` parameter from the constructor for the . + ]]> The value is . diff --git a/xml/System.Diagnostics/SourceSwitch.xml b/xml/System.Diagnostics/SourceSwitch.xml index 9a970cd7580..1697fbac5f8 100644 --- a/xml/System.Diagnostics/SourceSwitch.xml +++ b/xml/System.Diagnostics/SourceSwitch.xml @@ -52,23 +52,23 @@ Provides a multilevel switch to control tracing and debug output without recompiling your code. - property of the class is a object. The class provides a property to test the event level of the switch. The property gets or sets the switch's value. - - You can set the event level of a through the application configuration file and then use the configured level in your application. Alternatively, you can create a in your code and set the level directly, to instrument a specific section of code. - - To configure a , edit the configuration file that corresponds to the name of your application. Within this file, you can set a switch's value or clear all the switches previously set by the application. The configuration file should be formatted as shown in the following example. - -```xml - - - -``` - - The switch is used to check whether a trace should be propagated or ignored. Each trace method calls the method before calling the listeners. If the method returns `false`, the trace is ignored and the trace method exits. If the method returns `true`, the trace is passed to the listeners. - + property of the class is a object. The class provides a property to test the event level of the switch. The property gets or sets the switch's value. + + You can set the event level of a through the application configuration file and then use the configured level in your application. Alternatively, you can create a in your code and set the level directly, to instrument a specific section of code. + + To configure a , edit the configuration file that corresponds to the name of your application. Within this file, you can set a switch's value or clear all the switches previously set by the application. The configuration file should be formatted as shown in the following example. + +```xml + + + +``` + + The switch is used to check whether a trace should be propagated or ignored. Each trace method calls the method before calling the listeners. If the method returns `false`, the trace is ignored and the trace method exits. If the method returns `true`, the trace is passed to the listeners. + ]]> @@ -123,23 +123,23 @@ The name of the source. Initializes a new instance of the class, specifying the name of the source. - property. - - To set the level of your in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. To add a source switch, the configuration file should be formatted as shown in the following example. - -```xml - - - - - - - -``` - + property. + + To set the level of your in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. To add a source switch, the configuration file should be formatted as shown in the following example. + +```xml + + + + + + + +``` + ]]> @@ -186,32 +186,32 @@ The default value for the switch. Initializes a new instance of the class, specifying the display name and the default value for the source switch. - property; the `defaultSwitchValue` parameter is saved as a field and used to initialize the property on first reference. - + property; the `defaultSwitchValue` parameter is saved as a field and used to initialize the property on first reference. + > [!NOTE] -> For .NET Framework apps, if the switch is defined in a configuration file and the `value` attribute is specified, the configuration file value takes precedence and the `defaultSwitchValue` is ignored. - -To set the level of your in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. To add a source switch, the configuration file should be formatted as shown in the following example. - -```xml - - - - - - - +> For .NET Framework apps, if the switch is defined in a configuration file and the `value` attribute is specified, the configuration file value takes precedence and the `defaultSwitchValue` is ignored. + +To set the level of your in a .NET Framework app, edit the configuration file that corresponds to the name of your application. Within this file, you can add a switch and set its value, remove a switch, or clear all the switches previously set by the application. To add a source switch, the configuration file should be formatted as shown in the following example. + +```xml + + + + + + + ``` - -## Examples - The following code example creates a with the name "SourceSwitch" and a default value of . This code example is part of a larger example provided for the class. - + +## Examples + The following code example creates a with the name "SourceSwitch" and a default value of . This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SourceFilter/.ctor/program.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet7"::: + ]]> @@ -256,22 +256,22 @@ To set the level of your in a .NET Framew Gets or sets the level of the switch. One of the values that represents the event level of the switch. - property. Setting this property also modifies the property. - + property. Setting this property also modifies the property. + > [!NOTE] -> For extensibility, the property can be set to any integer, rather than being limited to a enumeration value. - - - -## Examples - The following code example displays the value of the property for a source switch. This code example is part of a larger example provided for the class. - +> For extensibility, the property can be set to any integer, rather than being limited to a enumeration value. + + + +## Examples + The following code example displays the value of the property for a source switch. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SourceFilter/.ctor/program.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet8"::: + ]]> @@ -316,11 +316,11 @@ To set the level of your in a .NET Framew Invoked when the value of the property changes. - method converts the new value of the property to the integer representation of the matching field in the enumeration, and then uses this integer to set the property. - + method converts the new value of the property to the integer representation of the matching field in the enumeration, and then uses this integer to set the property. + ]]> The new value of is not one of the values. @@ -371,14 +371,14 @@ To set the level of your in a .NET Framew if the trace listeners should be called; otherwise, . - class to determine whether listeners should be called to write a trace. - + class to determine whether listeners should be called to write a trace. + > [!NOTE] -> Application code should not call this method; it is intended to be called only by methods in the class. - +> Application code should not call this method; it is intended to be called only by methods in the class. + ]]> diff --git a/xml/System.Diagnostics/StackFrame.xml b/xml/System.Diagnostics/StackFrame.xml index 10205b23107..97d0b105c44 100644 --- a/xml/System.Diagnostics/StackFrame.xml +++ b/xml/System.Diagnostics/StackFrame.xml @@ -764,7 +764,7 @@ property of the object that is returned by identifies the base class, not the derived class. + The method that is currently executing may be inherited from a base class, although it is called in a derived class. In this case, the property of the object that is returned by identifies the base class, not the derived class. diff --git a/xml/System.Diagnostics/StackTrace.xml b/xml/System.Diagnostics/StackTrace.xml index 50272052e51..1e34017e5ec 100644 --- a/xml/System.Diagnostics/StackTrace.xml +++ b/xml/System.Diagnostics/StackTrace.xml @@ -873,7 +873,7 @@ array to enumerate and examine function calls in the . The length of the returned array is equal to the property value. + Use the returned array to enumerate and examine function calls in the . The length of the returned array is equal to the property value. The array elements are in reverse chronological order. The at array index 0 represents the most recent function call in the stack trace and the last frame pushed onto the call stack. The at array index minus 1 represents the oldest function call in the stack trace and the first frame pushed onto the call stack. diff --git a/xml/System.Diagnostics/Stopwatch.xml b/xml/System.Diagnostics/Stopwatch.xml index 9cbab8ffe16..74019fde41d 100644 --- a/xml/System.Diagnostics/Stopwatch.xml +++ b/xml/System.Diagnostics/Stopwatch.xml @@ -69,7 +69,7 @@ instance can measure elapsed time for one interval, or the total of elapsed time across multiple intervals. In a typical scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. + A instance can measure elapsed time for one interval, or the total of elapsed time across multiple intervals. In a typical scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. A instance is either running or stopped; use to determine the current state of a . Use to begin measuring elapsed time; use to stop measuring elapsed time. Query the elapsed time value through the properties , , or . You can query the elapsed time properties while the instance is running or stopped. The elapsed time properties steadily increase while the is running; they remain constant when the instance is stopped. @@ -209,9 +209,9 @@ scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. + In a typical scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. - Use the property to retrieve the elapsed time value using methods and properties. For example, you can format the returned instance into a text representation, or pass it to another class that requires a parameter. + Use the property to retrieve the elapsed time value using methods and properties. For example, you can format the returned instance into a text representation, or pass it to another class that requires a parameter. You can query the properties , , and while the instance is running or stopped. The elapsed time properties steadily increase while the is running; they remain constant when the instance is stopped. @@ -220,7 +220,7 @@ ## Examples - The following example demonstrates how to use the property to determine the execution time for an application. + The following example demonstrates how to use the property to determine the execution time for an application. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Stopwatch/Overview/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/Stopwatch/Overview/source1.vb" id="Snippet1"::: @@ -571,7 +571,7 @@ class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the current property of the instance. + If the class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the current property of the instance. @@ -872,7 +872,7 @@ scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. + In a typical scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. Once started, a timer measures the current interval, in elapsed timer ticks, until the instance is stopped or reset. Starting a that is already running does not change the timer state or reset the elapsed time properties. @@ -1009,7 +1009,7 @@ scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. + In a typical scenario, you call the method, then eventually call the method, and then you check elapsed time using the property. The method ends the current time interval measurement. Stopping a that is not running does not change the timer state or reset the elapsed time properties. diff --git a/xml/System.Diagnostics/Switch.xml b/xml/System.Diagnostics/Switch.xml index ea5a8b92c2f..820465b1804 100644 --- a/xml/System.Diagnostics/Switch.xml +++ b/xml/System.Diagnostics/Switch.xml @@ -78,7 +78,7 @@ ``` - This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your application, you can use the configured switch value by creating a with the same name, as shown in the following code example. + This example configuration section defines a with the property set to `mySwitch` and the value set to `true`. Within your application, you can use the configured switch value by creating a with the same name, as shown in the following code example. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Switch/Overview/remarks.cs" id="Snippet4"::: @@ -268,7 +268,7 @@ property, and the `description` parameter is use to set the value of the property. The `defaultSwitchValue` parameter is the value for the switch if the property is not set by code or by the configuration file attribute. See the overload for additional information. + The `displayName` parameter is used to set the value of the property, and the `description` parameter is use to set the value of the property. The `defaultSwitchValue` parameter is the value for the switch if the property is not set by code or by the configuration file attribute. See the overload for additional information. ]]> @@ -322,7 +322,7 @@ property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. + The property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. @@ -685,7 +685,7 @@ property to an integer value that it uses to set the property. + The default implementation parses the new value of the property to an integer value that it uses to set the property. ]]> @@ -816,7 +816,7 @@ method is called when the value of the property is changed. The method parses the value of this property and converts it to an integer value, which is then used to set the property. + The method is called when the value of the property is changed. The method parses the value of this property and converts it to an integer value, which is then used to set the property. ]]> diff --git a/xml/System.Diagnostics/SwitchAttribute.xml b/xml/System.Diagnostics/SwitchAttribute.xml index 1f5995ee71a..cde2262de97 100644 --- a/xml/System.Diagnostics/SwitchAttribute.xml +++ b/xml/System.Diagnostics/SwitchAttribute.xml @@ -55,21 +55,21 @@ Identifies a switch used in an assembly, class, or member. - attribute can be used on an assembly, class, constructor, method, property, or event. - - The attribute can be used by tools that inspect an assembly for configuration settings. - - - -## Examples - The following example shows how to use the attribute to identify the switch used in an assembly. This code example is part of a larger example provided for the class. - + attribute can be used on an assembly, class, constructor, method, property, or event. + + The attribute can be used by tools that inspect an assembly for configuration settings. + + + +## Examples + The following example shows how to use the attribute to identify the switch used in an assembly. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet2"::: + ]]> @@ -115,19 +115,19 @@ The type of the switch. Initializes a new instance of the class, specifying the name and the type of the switch. - property of the switch. - - - -## Examples - The following code example shows the use of the constructor to create a switch attribute. This code example is part of a larger example provided for the class. - + property of the switch. + + + +## Examples + The following code example shows the use of the constructor to create a switch attribute. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet2"::: + ]]> @@ -181,14 +181,14 @@ Returns all switch attributes for the specified assembly. An array that contains all the switch attributes for the assembly. - method to identify the switches used in an assembly. This code example is part of a larger example provided for the class. - + method to identify the switches used in an assembly. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet12"::: + ]]> @@ -249,11 +249,11 @@ Gets or sets the description of the switch. The description of the switch. - property typically indicates the function of the switch. - + property typically indicates the function of the switch. + ]]> @@ -303,19 +303,19 @@ Gets or sets the display name of the switch. The display name of the switch. - property should match the property of the switch. - - - -## Examples - The following code example displays the value the property for all switches used in an assembly. This code example is part of a larger example provided for the class. - + property should match the property of the switch. + + + +## Examples + The following code example displays the value the property for all switches used in an assembly. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet12"::: + ]]> @@ -369,14 +369,14 @@ Gets or sets the type of the switch. The type of the switch. - property for all switches used in an assembly. This code example is part of a larger example provided for the class. - + property for all switches used in an assembly. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet12"::: + ]]> diff --git a/xml/System.Diagnostics/SwitchLevelAttribute.xml b/xml/System.Diagnostics/SwitchLevelAttribute.xml index 24c4aba6b23..3080493b95e 100644 --- a/xml/System.Diagnostics/SwitchLevelAttribute.xml +++ b/xml/System.Diagnostics/SwitchLevelAttribute.xml @@ -55,11 +55,11 @@ Identifies the level type for a switch. - class. The purpose of the attribute is to identify the type that specifies the switch criteria of the switch. Each switch determines whether a trace is to be written, based on whether an event type matches or exceeds the value of the property for the switch. The type used for the property varies for different switches. For example, the switch level type for the class is , and the switch level type for the class is . - + class. The purpose of the attribute is to identify the type that specifies the switch criteria of the switch. Each switch determines whether a trace is to be written, based on whether an event type matches or exceeds the value of the property for the switch. The type used for the property varies for different switches. For example, the switch level type for the class is , and the switch level type for the class is . + ]]> @@ -103,11 +103,11 @@ The that determines whether a trace should be written. Initializes a new instance of the class, specifying the type that determines whether a trace should be written. - property of the class is . - + property of the class is . + ]]> @@ -157,19 +157,19 @@ Gets or sets the type that determines whether a trace should be written. The that determines whether a trace should be written. - class is . - - - -## Examples - The following code example displays the value of the property for the . - + class is . + + + +## Examples + The following code example displays the value of the property for the . + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SourceFilter/.ctor/program.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SourceFilter/.ctor/program.vb" id="Snippet13"::: + ]]> The set operation failed because the value is . diff --git a/xml/System.Diagnostics/TextWriterTraceListener.xml b/xml/System.Diagnostics/TextWriterTraceListener.xml index fb4df265962..01e2a393baa 100644 --- a/xml/System.Diagnostics/TextWriterTraceListener.xml +++ b/xml/System.Diagnostics/TextWriterTraceListener.xml @@ -56,7 +56,7 @@ class provides the property to get or set the text writer that receives the tracing or debugging output. + The class provides the property to get or set the text writer that receives the tracing or debugging output. > [!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. @@ -165,12 +165,12 @@ stream as the recipient of the tracing or debugging output. Its property is initialized to an empty string ("", or ). + This constructor uses the stream as the recipient of the tracing or debugging output. Its property is initialized to an empty string ("", or ). ## Examples - The following example creates a using the constructor. It sets the property to console output, and then adds the to the . It writes a message in two segments, and then closes the . + The following example creates a using the constructor. It sets the property to console output, and then adds the to the . It writes a message in two segments, and then closes the . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TextWriterTraceListener/.ctor/source1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TextWriterTraceListener/.ctor/source1.vb" id="Snippet1"::: @@ -232,7 +232,7 @@ property to an empty string (""). + This constructor initializes the property to an empty string (""). @@ -300,7 +300,7 @@ property to an empty string (""). + This constructor initializes the property to an empty string (""). @@ -374,7 +374,7 @@ property to an empty string (""). + This constructor initializes the property to an empty string (""). @@ -452,7 +452,7 @@ property to the `name` parameter or to an empty string (""), if the `name` parameter is `null`. + This constructor initializes the property to the `name` parameter or to an empty string (""), if the `name` parameter is `null`. @@ -601,7 +601,7 @@ property to the `name` parameter or to an empty string (""), if the `name` parameter is `null`. + This constructor initializes the property to the `name` parameter or to an empty string (""), if the `name` parameter is `null`. diff --git a/xml/System.Diagnostics/ThreadPriorityLevel.xml b/xml/System.Diagnostics/ThreadPriorityLevel.xml index 80413d65201..3ef75dcf6fe 100644 --- a/xml/System.Diagnostics/ThreadPriorityLevel.xml +++ b/xml/System.Diagnostics/ThreadPriorityLevel.xml @@ -46,13 +46,13 @@ Specifies the priority level of a thread. - property, to set the thread's priority. - + property, to set the thread's priority. + ]]> diff --git a/xml/System.Diagnostics/Trace.xml b/xml/System.Diagnostics/Trace.xml index 46797fbee79..f5a69563d44 100644 --- a/xml/System.Diagnostics/Trace.xml +++ b/xml/System.Diagnostics/Trace.xml @@ -197,9 +197,9 @@ In .NET Framework apps, you can set the [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -309,9 +309,9 @@ For .NET Framework apps, you can change the behavior of the [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -414,9 +414,9 @@ For .NET Framework apps, you can change the behavior of the [!NOTE] -> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. +> The display of the message box depends on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). For .NET Framework apps, you can also use the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace) and the [\ element](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace) in your app's configuration file. -For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: +For .NET Framework apps, you can change the behavior of the in the configuration file that corresponds to the name of your application. In this file, you can enable and disable the assert message box or set the property. The configuration file should be formatted as follows: ```xml @@ -720,7 +720,7 @@ For .NET Framework apps, you can change the behavior of the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). You can customize this behavior by adding a to, or by removing one from, the collection. @@ -811,7 +811,7 @@ For .NET Framework apps, you can change the behavior of the instances in the collection. > [!NOTE] -> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). +> The display of the message box is dependent on the presence of the . If the is not in the collection, the message box is not displayed. The can be removed by the [<clear>](/dotnet/framework/configure-apps/file-schema/trace-debug/clear-element-for-listeners-for-trace), the [<remove>](/dotnet/framework/configure-apps/file-schema/trace-debug/remove-element-for-listeners-for-trace), or by calling the method on the property (`System.Diagnostics.Trace.Listeners.Clear()`). You can customize this behavior by adding a to, or by removing one from, the collection. @@ -1025,7 +1025,7 @@ End of list of errors property represents the number of times the indent of size is applied. This property is stored on per-thread/per-request basis. + The property represents the number of times the indent of size is applied. This property is stored on per-thread/per-request basis. @@ -1881,7 +1881,7 @@ End of list of errors . The property is used to determine if the listener is thread safe. The global lock is not used only if the value of is `false` and the value of is `true`. The default behavior is to use the global lock. + The global lock is always used if the trace listener is not thread safe, regardless of the value of . The property is used to determine if the listener is thread safe. The global lock is not used only if the value of is `false` and the value of is `true`. The default behavior is to use the global lock. To set the for in .NET Framework apps, you can also edit the configuration file that corresponds to the name of your application. The configuration file should be formatted like the following example: @@ -1966,9 +1966,9 @@ End of list of errors This method calls the method of the trace listener. > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. @@ -2052,9 +2052,9 @@ End of list of errors This method calls the method of the trace listener. > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. @@ -2142,9 +2142,9 @@ End of list of errors This method calls the method of the trace listener. > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. @@ -2232,9 +2232,9 @@ End of list of errors This method calls the method of the trace listener. > [!NOTE] -> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. +> ASP.NET supplies tracing functionality tailored for Web pages. To write trace messages in ASP.NET pages, use the property. - By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. + By default, in code associated with an ASP.NET Web page, the statement `Trace.Write("...")` is a call to the method of the property. To use the class in Web pages, you must include the namespace, for example, `System.Diagnostics.Trace.Write("...")`. diff --git a/xml/System.Diagnostics/TraceEventCache.xml b/xml/System.Diagnostics/TraceEventCache.xml index 3d42baa03eb..1f183e41c85 100644 --- a/xml/System.Diagnostics/TraceEventCache.xml +++ b/xml/System.Diagnostics/TraceEventCache.xml @@ -52,15 +52,15 @@ Provides trace event data specific to a thread and a process. - [!NOTE] -> The class, designed as a performance optimization for trace listener calls, is of interest only to developers creating custom trace listeners. - - The class is used as a parameter in tracing methods to accurately identify the source of a trace event. Examples of methods that use are and . The property contains data that can be used to correlate the trace with related traces. - +> The class, designed as a performance optimization for trace listener calls, is of interest only to developers creating custom trace listeners. + + The class is used as a parameter in tracing methods to accurately identify the source of a trace event. Examples of methods that use are and . The property contains data that can be used to correlate the trace with related traces. + ]]> @@ -142,11 +142,11 @@ Gets the call stack for the current thread. A string containing stack trace information. This value can be an empty string (""). - property gets the call stack from the property of the class. The property value lists method calls in reverse chronological order. That is, the most recent method call is described first. One line of stack trace information is listed for each method call on the stack. For more information, see . - + property gets the call stack from the property of the class. The property value lists method calls in reverse chronological order. That is, the most recent method call is described first. One line of stack trace information is listed for each method call on the stack. For more information, see . + ]]> @@ -191,11 +191,11 @@ Gets the date and time at which the event trace occurred. A structure whose value is a date and time expressed in Coordinated Universal Time (UTC). - class, the current time is returned. Subsequent queries of this property in that instance return that same value, allowing it to be used as a timestamp. - + class, the current time is returned. Subsequent queries of this property in that instance return that same value, allowing it to be used as a timestamp. + ]]> @@ -239,11 +239,11 @@ Gets the correlation data, contained in a stack. A containing correlation data. - class provides methods used to store a logical operation identity in a thread-bound context and automatically tag each trace event generated by the thread with the stored identity. The is accessed through the property. Each call to the method pushes a new logical operation identity onto the stack. Each call to the method pops a logical operation identity from the stack - + class provides methods used to store a logical operation identity in a thread-bound context and automatically tag each trace event generated by the thread with the stored identity. The is accessed through the property. Each call to the method pushes a new logical operation identity onto the stack. Each call to the method pops a logical operation identity from the stack + ]]> @@ -294,11 +294,11 @@ Gets the unique identifier of the current process. The system-generated unique identifier of the current process. - @@ -343,11 +343,11 @@ Gets a unique identifier for the current managed thread. A string that represents a unique integer identifier for this managed thread. - property formatted as a string. - + property formatted as a string. + ]]> @@ -392,11 +392,11 @@ Gets the current number of ticks in the timer mechanism. The tick counter value of the underlying timer mechanism. - method to get the timestamp. If the class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the property of . - + method to get the timestamp. If the class uses a high-resolution performance counter, returns the current value of that counter. If the class uses the system timer, returns the property of . + ]]> diff --git a/xml/System.Diagnostics/TraceFilter.xml b/xml/System.Diagnostics/TraceFilter.xml index 38294f47641..4703ec685a6 100644 --- a/xml/System.Diagnostics/TraceFilter.xml +++ b/xml/System.Diagnostics/TraceFilter.xml @@ -49,7 +49,7 @@ property. Trace switches determine if a trace is to be sent to the trace listeners. Trace filters allow the individual trace listeners to determine whether or not the trace is to be written to the associated output medium. For example, as determined by each trace filter, a trace may be written to the console by a , but not to the event log by a . + Trace filters can be used by trace listeners to provide an extra layer of filtering beyond that provided by trace switches. The trace filter for a trace listener can be found in the listener's property. Trace switches determine if a trace is to be sent to the trace listeners. Trace filters allow the individual trace listeners to determine whether or not the trace is to be written to the associated output medium. For example, as determined by each trace filter, a trace may be written to the console by a , but not to the event log by a . Filters that inherit from the class can be used by trace listeners that inherit from the class to perform filtering of events being traced. contains a single method, , which takes event data and returns a flag indicating whether the event should be traced. diff --git a/xml/System.Diagnostics/TraceListener.xml b/xml/System.Diagnostics/TraceListener.xml index f9c32122372..80bac8a79d6 100644 --- a/xml/System.Diagnostics/TraceListener.xml +++ b/xml/System.Diagnostics/TraceListener.xml @@ -274,7 +274,7 @@ class can add custom attributes by overriding the method and returning a string array of custom attribute names. The property identifies the custom attributes that are referenced in the application's configuration file. For example, in the following configuration file excerpt the custom attribute "delimiter" is referenced. In this case, the property returns a containing the string "delimiter". + Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. The property identifies the custom attributes that are referenced in the application's configuration file. For example, in the following configuration file excerpt the custom attribute "delimiter" is referenced. In this case, the property returns a containing the string "delimiter". ```xml @@ -680,7 +680,7 @@ ## Examples - The following code example shows how to use the property to add a source filter to a console trace listener. This code example is part of a larger example provided for the class. + The following code example shows how to use the property to add a source filter to a console trace listener. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet28"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet28"::: @@ -867,7 +867,7 @@ property represents the number of times that the indent specified by the property is applied. This property is stored on per-thread/per-request basis. + The property represents the number of times that the indent specified by the property is applied. This property is stored on per-thread/per-request basis. ]]> @@ -1116,7 +1116,7 @@ method, called by the and classes, sets the property value to `false` to prevent later, unnecessary indents. You must set the property to `true` each time you wish to indent trace output. + **Note** The method, called by the and classes, sets the property value to `false` to prevent later, unnecessary indents. You must set the property to `true` each time you wish to indent trace output. ]]> @@ -1303,7 +1303,7 @@ > [!IMPORTANT] > This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The data objects are converted to strings using the `ToString` method of each object. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. + The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The data objects are converted to strings using the `ToString` method of each object. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. ]]> @@ -1396,7 +1396,7 @@ > [!IMPORTANT] > This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. + The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. ]]> @@ -1481,7 +1481,7 @@ > [!IMPORTANT] > This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header, followed by the `message` data. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. + The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header, followed by the `message` data. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. ]]> @@ -1583,7 +1583,7 @@ > [!IMPORTANT] > This method is not intended to be called directly by application code but by members of the , , and classes to write trace data to output. - The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. + The default implementation writes the values of the `source`, `eventType` and `id` parameters as a header. The `args` object array is converted to a string using the method, passing the `format` string and `args` array to format the string as the message portion of the trace. The `eventCache` data is written as a footer, the nature of the output data being dependent on the value of the property. ]]> @@ -1649,7 +1649,7 @@ property determines the optional content of trace output. The property can be set in the configuration file or programmatically during execution to include additional data specifically for a section of code. For example, you can set the property for the console trace listener to to add call stack information to the trace output. + The property determines the optional content of trace output. The property can be set in the configuration file or programmatically during execution to include additional data specifically for a section of code. For example, you can set the property for the console trace listener to to add call stack information to the trace output. The enumeration is not used by the following classes and methods: @@ -1662,7 +1662,7 @@ ## Examples - The following example shows the setting of the property for a console trace listener. The console trace listener is one of the listeners enumerated in the property of a trace source. This code example is part of a larger example provided for the class. + The following example shows the setting of the property for a console trace listener. The console trace listener is one of the listeners enumerated in the property of a trace source. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet16"::: @@ -2033,7 +2033,7 @@ property to `false`. Call this method if is `true` when you are overriding the and methods. By default, this method uses blank spaces for indentation. The size of the indent is determined by the values of the and properties. The property represents the number of times the indent of the size specified by the property is applied. This method is called by the and classes. + This method writes the indent and resets the property to `false`. Call this method if is `true` when you are overriding the and methods. By default, this method uses blank spaces for indentation. The size of the indent is determined by the values of the and properties. The property represents the number of times the indent of the size specified by the property is applied. This method is called by the and classes. ]]> diff --git a/xml/System.Diagnostics/TraceListenerCollection.xml b/xml/System.Diagnostics/TraceListenerCollection.xml index 293f967e1b5..2fd6bef630c 100644 --- a/xml/System.Diagnostics/TraceListenerCollection.xml +++ b/xml/System.Diagnostics/TraceListenerCollection.xml @@ -71,7 +71,7 @@ This list is thread-safe, however the methods used to access the list and the enumerator do not take synchronization locks. Instead, the collection is copied, the copy is modified, and a reference is set to the copy of the collection. Methods like , , and modify the elements in the collection. - The class provides the property for information about the list. It also provides the following methods: , , . + The class provides the property for information about the list. It also provides the following methods: , , . This class also provides the following methods to modify the list: , , , and . The method copies a part of the list to an array. The method deletes the list member at a specified index number. @@ -804,7 +804,7 @@ property is case-sensitive when searching for names. That is, if two listeners exist with the names "Lname" and "lname", property will find only the with the that you specify, not both. + The property is case-sensitive when searching for names. That is, if two listeners exist with the names "Lname" and "lname", property will find only the with the that you specify, not both. ]]> @@ -1570,7 +1570,7 @@ This member is an explicit interface member implementation. It can be used only property or the indexer of the class to get or set a in the collection. + Use the property or the indexer of the class to get or set a in the collection. ]]> diff --git a/xml/System.Diagnostics/TraceLogRetentionOption.xml b/xml/System.Diagnostics/TraceLogRetentionOption.xml index cb893d24e9b..7260aa69c8a 100644 --- a/xml/System.Diagnostics/TraceLogRetentionOption.xml +++ b/xml/System.Diagnostics/TraceLogRetentionOption.xml @@ -16,23 +16,23 @@ Specifies the file structure that will be used for the log. - enumeration is used to specify the value of the property in the class. That property setting determines the possible and default values for the and properties. - - You can set the and properties through the `maximumFileSize` and `maximumNumberOfFiles` custom attributes in the configuration file or by using the `maximumFileSize` or `maximumNumberOfFiles` parameters in the constructor. If the `maximumFileSize` or `maximumNumberOfFiles` attributes in the configuration file specify an out-of-range value, the properties are set to their default values. If you specify an out-of-range value in the `maximumFileSize` or `maximumNumberOfFiles` parameter when you call the constructor, an is thrown. - - The following table shows the possible and default values for file size and file count that are associated with each trace log retention option. "N/A" indicates that the associated property is not checked for that value. - -|TraceLogRetentionOption|Maximum file size|Default file size|Maximum number of files|Default number of files| -|-----------------------------|-----------------------|-----------------------|-----------------------------|-----------------------------| -|LimitedCircularFiles|N/A|-1|N/A|1| -|LimitedSequentialFiles|>0|4 kB|N/A|1| -|SingleFileBoundedSize|>0|4 kB|N/A|-1| -|SingleFileUnboundedSize|>0|4 kB|>0|1| -|UnlimitedSequentialFiles|>0|4 kB|>1|2| - + enumeration is used to specify the value of the property in the class. That property setting determines the possible and default values for the and properties. + + You can set the and properties through the `maximumFileSize` and `maximumNumberOfFiles` custom attributes in the configuration file or by using the `maximumFileSize` or `maximumNumberOfFiles` parameters in the constructor. If the `maximumFileSize` or `maximumNumberOfFiles` attributes in the configuration file specify an out-of-range value, the properties are set to their default values. If you specify an out-of-range value in the `maximumFileSize` or `maximumNumberOfFiles` parameter when you call the constructor, an is thrown. + + The following table shows the possible and default values for file size and file count that are associated with each trace log retention option. "N/A" indicates that the associated property is not checked for that value. + +|TraceLogRetentionOption|Maximum file size|Default file size|Maximum number of files|Default number of files| +|-----------------------------|-----------------------|-----------------------|-----------------------------|-----------------------------| +|LimitedCircularFiles|N/A|-1|N/A|1| +|LimitedSequentialFiles|>0|4 kB|N/A|1| +|SingleFileBoundedSize|>0|4 kB|N/A|-1| +|SingleFileUnboundedSize|>0|4 kB|>0|1| +|UnlimitedSequentialFiles|>0|4 kB|>1|2| + ]]> diff --git a/xml/System.Diagnostics/TraceOptions.xml b/xml/System.Diagnostics/TraceOptions.xml index 968177ef065..73aadea3215 100644 --- a/xml/System.Diagnostics/TraceOptions.xml +++ b/xml/System.Diagnostics/TraceOptions.xml @@ -54,7 +54,7 @@ property. + This enumeration is used by trace listeners to determine which options, or elements, should be included in the trace output. Trace listeners store the trace options in the property. The following example shows the use of the `traceOutputOptions` attribute to specify the trace output options for a . Using a configuration file like this is only possible in .NET Framework apps. @@ -83,7 +83,7 @@ - The and methods of the class when they are not overridden in a derived class. ## Examples - The following code example shows the use of the enumeration to programmatically set the property for a console trace listener. The console trace listener is one of the listeners enumerated in the property of a trace source. This code example is part of a larger example provided for the class. + The following code example shows the use of the enumeration to programmatically set the property for a console trace listener. The console trace listener is one of the listeners enumerated in the property of a trace source. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet16"::: diff --git a/xml/System.Diagnostics/TraceSource.xml b/xml/System.Diagnostics/TraceSource.xml index 53e9abd7a47..240bc64fee5 100644 --- a/xml/System.Diagnostics/TraceSource.xml +++ b/xml/System.Diagnostics/TraceSource.xml @@ -98,7 +98,7 @@ In .NET Framework apps, trace output from > [!NOTE] > You should not call the tracing methods during finalization. Doing so can result in an being thrown. - You can customize the tracing output's target by adding or removing instances to or from the collection stored in the property. By default, trace output is produced using an instance of the class. + You can customize the tracing output's target by adding or removing instances to or from the collection stored in the property. By default, trace output is produced using an instance of the class. The preceding .NET Framework app configuration file example demonstrates removing the and adding a to produce the trace output for the trace source. For more information, see [\](/dotnet/framework/configure-apps/file-schema/trace-debug/listeners-element-for-source) and [\](/dotnet/framework/configure-apps/file-schema/trace-debug/sharedlisteners-element). @@ -114,7 +114,7 @@ The preceding .NET Framework app configuration file example demonstrates removin The trace listeners can optionally have an additional layer of filtering through a trace filter. If a trace listener has an associated filter, the listener calls the method on that filter to determine whether or not to produce the trace information. - The trace listeners use the values of the class properties , , and to format trace output. In .NET Framework apps, you can use configuration file attributes to set the , , and properties. The following example sets the property to `false` and the property to 3. + The trace listeners use the values of the class properties , , and to format trace output. In .NET Framework apps, you can use configuration file attributes to set the , , and properties. The following example sets the property to `false` and the property to 3. ```xml @@ -126,7 +126,7 @@ The preceding .NET Framework app configuration file example demonstrates removin ## Examples The following code example shows the use of the class to forward traces to listeners. The example also demonstrates switch and filter usage. - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/SwitchAttribute/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/SwitchAttribute/Overview/program.vb" id="Snippet1"::: @@ -316,7 +316,7 @@ The preceding .NET Framework app configuration file example demonstrates removin property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. + The property identifies the custom attributes referenced in the application's configuration file. Unreferenced custom attributes are not enumerated. Classes that inherit from the class can add custom attributes by overriding the method and returning a string array of custom attribute names. The following is a sample of a trace source element specifying the custom attribute `SecondTraceSourceAttribute`: @@ -754,7 +754,7 @@ You can refer to the trace source by using the `name` attribute in the configura property allows the filtering of messages before the trace source calls the listeners. + The property allows the filtering of messages before the trace source calls the listeners. The switch is used to check whether trace calls should be generated or ignored. Each trace method calls the method of the to determine whether to proceed with the trace. If the call returns `true`, the listeners are called. @@ -833,7 +833,7 @@ You can refer to the trace source by using the `name` attribute in the configura ## Remarks The method, like the method, is intended for automated tools, but it also allows the attaching of an additional object, such as an exception instance, to the trace. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods. > [!NOTE] > The object is limited to a maximum `id` value of 65,535. If the `id` value specified is greater than 65,535, the object uses 65,535. @@ -917,7 +917,7 @@ You can refer to the trace source by using the `name` attribute in the configura ## Remarks The method, like the method, is intended for automated tools, but it also allows the attaching of additional objects, such as an exception instance and a stack trace, to the trace. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method on all listeners. Otherwise, returns without calling the listeners' methods. > [!NOTE] > The object is limited to a maximum `id` value of 65,535. If the `id` value specified is greater than 65,535, the object uses 65,535. @@ -993,9 +993,9 @@ You can refer to the trace source by using the `name` attribute in the configura ## Remarks The method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. - The trace content is listener specific. If the method is not overridden by the listener implementation, the default output is the name of the trace source, its numeric identity, and the event type. Additional trace content is dependent upon the listener's property value. + The trace content is listener specific. If the method is not overridden by the listener implementation, the default output is the name of the trace source, its numeric identity, and the event type. Additional trace content is dependent upon the listener's property value. > [!NOTE] > The object is limited to a maximum `id` value of 65,535. If the `id` value specified is greater than 65,535, the uses 65,535. @@ -1072,9 +1072,9 @@ You can refer to the trace source by using the `name` attribute in the configura ## Remarks The method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. - The trace content is listener specific. If the method is not overridden by the listener implementation, the default output is the name of the trace source, its numeric identity, the event type, and the message. Additional trace content is dependent upon the listener's property value. + The trace content is listener specific. If the method is not overridden by the listener implementation, the default output is the name of the trace source, its numeric identity, the event type, and the message. Additional trace content is dependent upon the listener's property value. > [!NOTE] > The object is limited to a maximum `id` value of 65,535. If the `id` value specified is greater than 65,535, the object uses 65,535. @@ -1170,7 +1170,7 @@ You can refer to the trace source by using the `name` attribute in the configura The method is intended to trace events that can be processed automatically by tools. For example, a monitoring tool can notify an administrator if a specific event is traced by a specific source. - The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. + The method calls the method of the object returned by the property. If returns `true`, calls the corresponding method of each listener. Otherwise, returns without calling the listeners' methods. The trace content is listener specific. The default method writes the source name, event type, and numeric identity in the trace header, then calls the method, passing the `format` string and `args` array and using the property to format the string as the message output. @@ -1437,9 +1437,9 @@ You can refer to the trace source by using the `name` attribute in the configura method calls the method of each trace listener in the property to write the trace information. The default method in the base class calls the method to process the call, setting `eventType` to and appending a string representation of the `relatedActivityId` GUID to `message`. + The method calls the method of each trace listener in the property to write the trace information. The default method in the base class calls the method to process the call, setting `eventType` to and appending a string representation of the `relatedActivityId` GUID to `message`. - is intended to be used with the logical operations of a . The `relatedActivityId` parameter relates to the property of a object. If a logical operation begins in one activity and transfers to another, the second activity logs the transfer by calling the method. The call relates the new activity identity to the previous identity. The most likely consumer of this functionality is a trace viewer that can report logical operations that span multiple activities. + is intended to be used with the logical operations of a . The `relatedActivityId` parameter relates to the property of a object. If a logical operation begins in one activity and transfers to another, the second activity logs the transfer by calling the method. The call relates the new activity identity to the previous identity. The most likely consumer of this functionality is a trace viewer that can report logical operations that span multiple activities. ]]> diff --git a/xml/System.Diagnostics/TraceSwitch.xml b/xml/System.Diagnostics/TraceSwitch.xml index 4f66a311469..036d4a85910 100644 --- a/xml/System.Diagnostics/TraceSwitch.xml +++ b/xml/System.Diagnostics/TraceSwitch.xml @@ -60,7 +60,7 @@ class provides the , , , and properties to test the level of the switch. The property gets or sets the switch's . + You can use a trace switch to filter out messages based on their importance. The class provides the , , , and properties to test the level of the switch. The property gets or sets the switch's . You can create a in your code and set the level directly to instrument a specific section of code. @@ -82,13 +82,13 @@ In .NET Framework apps only, you can also set the level of a You can also use text to specify the value for a switch. For example, `true` for a , or the text representing an enumeration value, such as `Error` for a . The line `` is equivalent to ``. In your application, you can use the configured switch level by creating a with the same name, as shown in the following example: - + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/remarks.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Overview/remarks.vb" id="Snippet3"::: In .NET Core and .NET 5+ apps, the of the new switch defaults to . -In .NET Framework apps, the switch property defaults to the value specified in the configuration file. If the constructor cannot find initial switch settings in the configuration file, of the new switch defaults to . +In .NET Framework apps, the switch property defaults to the value specified in the configuration file. If the constructor cannot find initial switch settings in the configuration file, of the new switch defaults to . You must enable tracing or debugging to use a switch. The following syntax is compiler specific. If you use compilers other than C# or Visual Basic, refer to the documentation for your compiler. @@ -105,7 +105,7 @@ In .NET Framework apps, the switch To improve performance, you can make members `static` in your class. ## Examples - The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Overview/source.vb" id="Snippet1"::: @@ -211,13 +211,13 @@ You can also use text to specify the value for a switch. For example, `true` for This constructor sets the property of the new switch to . Or, for .NET Framework apps, the switch settings are obtained from the configuration file, if available. - The class provides the , , , and properties to test the of the switch. The property gets or sets the switch's . + The class provides the , , , and properties to test the of the switch. The property gets or sets the switch's . > [!NOTE] > To improve performance, you can make members `static` in your class. ## Examples - The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Overview/source.vb" id="Snippet1"::: @@ -292,7 +292,7 @@ This constructor sets the property o property, the `description` parameter is use to set the value of the property, and the `defaultSwitchValue` parameter is saved as a field and used to initialize the property on first reference. See the constructor for more information and a code example. + The `displayName` parameter is used to set the value of the property, the `description` parameter is use to set the value of the property, and the `defaultSwitchValue` parameter is saved as a field and used to initialize the property on first reference. See the constructor for more information and a code example. ]]> @@ -365,7 +365,7 @@ The default value of the property is Setting this property updates the , , , and properties to reflect the new value. ## Examples - The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to print error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Level/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Level/source.vb" id="Snippet1"::: @@ -427,7 +427,7 @@ The default value of the property is ## Remarks The method is used by the .NET framework to validate and correct the value of a switch initialized via a configuration file. A message is written to all trace listeners if the switch value specified in the configuration file is not defined by the enumeration and the switch is set to a defined value. - If you attempt in your code to set the property to a value that is not defined by the enumeration, an exception is thrown. + If you attempt in your code to set the property to a value that is not defined by the enumeration, an exception is thrown. ]]> @@ -480,7 +480,7 @@ The default value of the property is property of the switch changes. The method ensures that the properties relating to the switch's value reflect the new value. + This method is called internally when the property of the switch changes. The method ensures that the properties relating to the switch's value reflect the new value. ]]> @@ -534,12 +534,12 @@ The default value of the property is , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to the highest importance, , , only error-handling messages are emitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to the highest importance, , , only error-handling messages are emitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Overview/source.vb" id="Snippet1"::: @@ -598,12 +598,12 @@ The default value of the property is , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , informational messages, warnings, and error-handling messages are emitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , informational messages, warnings, and error-handling messages are emitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message if the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/TraceInfo/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/TraceInfo/source.vb" id="Snippet1"::: @@ -662,12 +662,12 @@ The default value of the property is , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , all debugging and tracing messages are transmitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , all debugging and tracing messages are transmitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes both error messages when the property is set to . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes both error messages when the property is set to . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/Overview/source.vb" id="Snippet1"::: @@ -726,12 +726,12 @@ The default value of the property is , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , warnings and error-handling messages are emitted. + You can use the , , , and properties in conjunction with the and classes to emit all messages with a specified importance or greater. When the property is set to , warnings and error-handling messages are emitted. ## Examples - The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message when the is less than . + The following code example creates a new and uses the switch to determine whether to emit error messages. The switch is created at the class level. `MyMethod` writes the first error message if the property is set to or higher. However, `MyMethod` does not write the second error message when the is less than . :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/TraceSwitch/TraceWarning/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/TraceSwitch/TraceWarning/source.vb" id="Snippet1"::: diff --git a/xml/System.Diagnostics/UnescapedXmlDiagnosticData.xml b/xml/System.Diagnostics/UnescapedXmlDiagnosticData.xml index 8e7ba0157d1..baa33d8e411 100644 --- a/xml/System.Diagnostics/UnescapedXmlDiagnosticData.xml +++ b/xml/System.Diagnostics/UnescapedXmlDiagnosticData.xml @@ -17,22 +17,22 @@ Provides unescaped XML data for the logging of user-provided trace data. - methods. It can also be used to pass XML data to the methods. - + methods. It can also be used to pass XML data to the methods. + > [!NOTE] -> The user-provided data is not checked for schema validity. - - - -## Examples - The following code example demonstrates how to use class. This code example is part of a larger example that is provided for the class. - +> The user-provided data is not checked for schema validity. + + + +## Examples + The following code example demonstrates how to use class. This code example is part of a larger example that is provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet11"::: + ]]> @@ -57,22 +57,22 @@ The XML data to be logged in the node of the event schema. Initializes a new instance of the class by using the specified XML data string. - property is an empty string. - + property is an empty string. + > [!NOTE] -> `xmlPayload` is not checked for XML validity. - - - -## Examples - The following code example demonstrates how to use the constructor. This code example is part of a larger example that is provided for the class. - +> `xmlPayload` is not checked for XML validity. + + + +## Examples + The following code example demonstrates how to use the constructor. This code example is part of a larger example that is provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/EventSchemaTraceListener/Overview/program.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Diagnostics/EventSchemaTraceListener/Overview/program.vb" id="Snippet11"::: + ]]> @@ -130,11 +130,11 @@ Gets or sets the unescaped XML data string. An unescaped XML string. - property value must be an XML fragment that can be validated against the end-to-end event schema. - + property value must be an XML fragment that can be validated against the end-to-end event schema. + ]]> diff --git a/xml/System.Diagnostics/XmlWriterTraceListener.xml b/xml/System.Diagnostics/XmlWriterTraceListener.xml index fb348251c42..94be22816b8 100644 --- a/xml/System.Diagnostics/XmlWriterTraceListener.xml +++ b/xml/System.Diagnostics/XmlWriterTraceListener.xml @@ -62,7 +62,7 @@ You can create an in your code. ``` - The class inherits the property from the base class . The property allows an additional level of trace output filtering at the listener. If there is a filter present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. + The class inherits the property from the base class . The property allows an additional level of trace output filtering at the listener. If there is a filter present, the `Trace` methods of the trace listener call the method of the filter to determine whether to emit the trace. > [!NOTE] > If an attempt is made to write to a file that is in use or unavailable, the file name is automatically prefixed by a GUID. @@ -74,8 +74,8 @@ You can create an in your code. |Element|Attributes|Output|Notes| |-------------|----------------|------------|-----------| -|`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table that follows.| -|`Computer`|None|Always present.|The value of the property.| +|`CallStack`|None|Depends on the presence of the flag in the property.|Special characters such as > or < are replaced with escape sequences. See the escaped character translation table that follows.| +|`Computer`|None|Always present.|The value of the property.| |`Correlation`|`ActivityID`|Always present|If not specified, the default is an empty GUID.| ||`RelatedActivityID`|Depends on the presence of the `relatedActivityId` parameter in the Trace method call.|The `relatedActivityId` parameter of the method.| |`DataItem`|None|Depends on the `data` parameter of the method.|This element can contain an array of elements or one element, so the values are written as a set of `DataItem` nodes under the `TraceData` element.

The data output uses the `ToString` method of the passed-in data objects.| @@ -84,12 +84,12 @@ You can create an in your code. ||`ProcessID`|Always present.|From the .| ||`ThreadID`|Always present.|From the .| |`Level`|None|Always present.|Parameter input (the numeric value of `eventType`). Parameter values greater than 255 are output as 255.| -|`LogicalOperationStack`|None|Depends on the presence of the flag in the property.|There can be more than one logical operation, so the values are written as `LogicalOperation` nodes under the `LogicalOperationStack` element.| +|`LogicalOperationStack`|None|Depends on the presence of the flag in the property.|There can be more than one logical operation, so the values are written as `LogicalOperation` nodes under the `LogicalOperationStack` element.| |`Message`|None|Depends on the presence of a message in the Trace method call.|This element is a formatted message if formatting arguments are provided.| |`Source`|`Name`|Always present.|Parameter input.| |`SubType`|`Name`|Always present.|Parameter input.| |`TimeCreated`|`SystemTime`|Always present.|If not present in the , the default is the current time.| -|`TimeStamp`|None|Depends on the presence of the flag in the property.|From the .| +|`TimeStamp`|None|Depends on the presence of the flag in the property.|From the .| |`Type`|None|Always present.|Always the value 3.| The following table shows the characters that are escaped in the XML output. Escaping occurs in all the elements and attributes with the exception of the `DataItem` element, which is not escaped if the object passed to the `data` parameter of the method is an object. If an is used for the data object, the method is called and the entire root node is traced as unescaped data. @@ -158,7 +158,7 @@ You can create an in your code. property is initialized to an empty string (""). + The property is initialized to an empty string (""). ]]> @@ -201,7 +201,7 @@ You can create an in your code. property is initialized to an empty string (""). + The property is initialized to an empty string (""). ]]> @@ -250,7 +250,7 @@ You can create an in your code. > [!NOTE] > To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. - The property is initialized to an empty string (""). + The property is initialized to an empty string (""). ]]>
@@ -303,7 +303,7 @@ You can create an in your code. property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + This constructor initializes the property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". ```csharp ((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = @@ -361,7 +361,7 @@ You can create an in your code. property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + This constructor initializes the property to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". ```csharp ((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = @@ -417,7 +417,7 @@ You can create an in your code. > [!NOTE] > To reduce the chance of an exception, any character that might invalidate the output is replaced with a "?" character. - The property is set to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". + The property is set to the `name` parameter value or to an empty string ("") if the `name` parameter is `null`. The name can be used as an index into the collection to programmatically change the properties for the listener. For example, the following code sets the property for an instance of whose property is "xmlListener". ```csharp ((XmlWriterTraceListener)Trace.Listeners["xmlListener"]).TraceOutputOptions = diff --git a/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml b/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml index e34f7bb3e92..21f04f03c3b 100644 --- a/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml +++ b/xml/System.DirectoryServices.AccountManagement/AdvancedFilters.xml @@ -29,7 +29,7 @@ class is accessed from a object through the property, and is effectually treated like a property of the object, and isn't intended to be used on its own. + The class is accessed from a object through the property, and is effectually treated like a property of the object, and isn't intended to be used on its own. @@ -71,7 +71,7 @@ through the property of the user object. + Applications should access through the property of the user object. ]]> @@ -107,7 +107,7 @@ property of your object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of your object as . @@ -170,7 +170,7 @@ foreach (UserPrincipal u in results) property of your object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of your object as . @@ -347,7 +347,7 @@ foreach (UserPrincipal u in results) property of your object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of your object as . @@ -410,7 +410,7 @@ foreach (UserPrincipal u in results) property of your object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of your object as . @@ -471,7 +471,7 @@ foreach (UserPrincipal u in results) property of your object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of your object as . diff --git a/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml b/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml index 662f648b393..c5460d84ae6 100644 --- a/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/AuthenticablePrincipal.xml @@ -147,7 +147,7 @@ ## Remarks As with all properties in , the time returned is in UTC form. To convert it to local time, call the method on the return object. - When you set the , the time will default to UTC. If you want to write in local time, then specify the property of your object as . + When you set the , the time will default to UTC. If you want to write in local time, then specify the property of your object as . ]]> @@ -465,7 +465,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -507,7 +507,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -551,7 +551,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -593,7 +593,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -637,7 +637,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -679,7 +679,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -723,7 +723,7 @@ property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . @@ -793,7 +793,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -837,7 +837,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> @@ -879,7 +879,7 @@ ctx.Dispose(); property of the `time` object as . + The time will default to UTC. If you want to specify the time in local time, then specify the property of the `time` object as . ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/ComputerPrincipal.xml b/xml/System.DirectoryServices.AccountManagement/ComputerPrincipal.xml index a085799b083..9ad366331ca 100644 --- a/xml/System.DirectoryServices.AccountManagement/ComputerPrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/ComputerPrincipal.xml @@ -46,11 +46,11 @@ Initializes a new instance of the class. The Context property must be set on the object prior to calling . - method. - + method. + ]]> @@ -76,11 +76,11 @@ The that specifies the server or domain against which operations are performed. Initializes a new instance of the class and assigns it to the specified context. - method. - + method. + ]]> @@ -112,11 +112,11 @@ A Boolean value that specifies whether the account is enabled. Initializes a new instance of the class by using the specified context, SAM account name, password, and enabled value. - method. - + method. + ]]> @@ -150,11 +150,11 @@ Returns a collection of objects that have had bad password attempts within the parameters specified. A that contains one or more objects that match the search parameters, or an empty collection if no matches are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -188,11 +188,11 @@ Returns a collection of objects that have an expiration time within the specified date and time range. A that contains one or more objects that match the search parameters, or an empty collection if no matches are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -298,11 +298,11 @@ Returns a collection of objects that have a lockout time within the specified date and time range. A that contains one or more objects that match the search parameters, or an empty collection if no matches are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -336,11 +336,11 @@ Returns a collection of objects that have a logon time within the specified date and time range. A that contains one or more objects that match the search parameters, or an empty collection if no matches are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -374,11 +374,11 @@ Returns a collection of objects that have a password set time within the specified date and time range. A that contains one or more objects that match the search parameters, or an empty collection if no matches are found. - property of the `time` object as . - + property of the `time` object as . + ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/GroupPrincipal.xml b/xml/System.DirectoryServices.AccountManagement/GroupPrincipal.xml index ec62a74c024..841db332aa9 100644 --- a/xml/System.DirectoryServices.AccountManagement/GroupPrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/GroupPrincipal.xml @@ -400,7 +400,7 @@ ctx.Dispose(); property includes user principals that are members of the group because of their primaryId Attribute. When the group contains these types of members, the following restrictions apply: + For AD DS groups, the property includes user principals that are members of the group because of their primaryId Attribute. When the group contains these types of members, the following restrictions apply: - The method cannot be used to remove members that are part of the group because of their primaryId Attribute. diff --git a/xml/System.DirectoryServices.AccountManagement/MultipleMatchesException.xml b/xml/System.DirectoryServices.AccountManagement/MultipleMatchesException.xml index b40d89eabcc..ca00171c4c1 100644 --- a/xml/System.DirectoryServices.AccountManagement/MultipleMatchesException.xml +++ b/xml/System.DirectoryServices.AccountManagement/MultipleMatchesException.xml @@ -67,11 +67,11 @@ Instantiates a new instance of the class. - class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The is initialized to `null`. - + class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The is initialized to `null`. + ]]> @@ -103,11 +103,11 @@ The text of the error message. Instantiates a new instance of the class with the specified error message. - instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. - + instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. + ]]> @@ -180,11 +180,11 @@ A nested exception. Instantiates a new instance of the class with the specified error message and specified nested exception. - instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. - + instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/NoMatchingPrincipalException.xml b/xml/System.DirectoryServices.AccountManagement/NoMatchingPrincipalException.xml index 82d5d0924b3..f8c1938d358 100644 --- a/xml/System.DirectoryServices.AccountManagement/NoMatchingPrincipalException.xml +++ b/xml/System.DirectoryServices.AccountManagement/NoMatchingPrincipalException.xml @@ -67,11 +67,11 @@ Instantiates a new instance of the class. - class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The property is initialized to `null`. - + class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The property is initialized to `null`. + ]]> @@ -103,11 +103,11 @@ The text of the error message. Instantiates a new instance of the class with the specified error message. - instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. - + instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. + ]]> @@ -180,11 +180,11 @@ A nested exception. Instantiates a new instance of the class with the specified error message and specified nested exception. - instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. - + instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/PasswordException.xml b/xml/System.DirectoryServices.AccountManagement/PasswordException.xml index 113c8b8bdc9..e876201cbc2 100644 --- a/xml/System.DirectoryServices.AccountManagement/PasswordException.xml +++ b/xml/System.DirectoryServices.AccountManagement/PasswordException.xml @@ -67,11 +67,11 @@ Instantiates a new instance of the class. - class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The property is initialized to `null`. - + class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The property is initialized to `null`. + ]]> @@ -103,11 +103,11 @@ The text of the error message. Instantiates a new instance of the class with the specified error message. - instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. - + instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. + ]]> @@ -180,11 +180,11 @@ A nested exception. Instantiates a new instance of the class with the specified error message and specified nested exception. - instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. - + instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/Principal.xml b/xml/System.DirectoryServices.AccountManagement/Principal.xml index 25c0c41b2c1..16893baa762 100644 --- a/xml/System.DirectoryServices.AccountManagement/Principal.xml +++ b/xml/System.DirectoryServices.AccountManagement/Principal.xml @@ -239,7 +239,7 @@ constructor. The value stored in this class is associated with the property. + The context type is set on the principal context object in the constructor. The value stored in this class is associated with the property. ]]> @@ -910,7 +910,7 @@ property is set to Machine. + This property will always return null when the property is set to Machine. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalExistsException.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalExistsException.xml index 000737bf0d5..6abae347da8 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalExistsException.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalExistsException.xml @@ -67,11 +67,11 @@ Instantiates a new instance of the class. - class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The property is initialized to `null`. - + class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The property is initialized to `null`. + ]]> @@ -103,11 +103,11 @@ The text of the error message. Instantiates a new instance of the class with the specified error message. - instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. - + instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. + ]]> @@ -180,11 +180,11 @@ A nested exception. Instantiates a new instance of the class with the specified error message and specified nested exception. - instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. - + instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalOperationException.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalOperationException.xml index 434b5586b1b..b32f41eea67 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalOperationException.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalOperationException.xml @@ -67,11 +67,11 @@ Instantiates a new instance of the class. - class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The property is initialized to `null`. - + class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The property is initialized to `null`. + ]]> @@ -103,11 +103,11 @@ The text of the error message. Instantiates a new instance of the class with the specified error message. - instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. - + instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. + ]]> @@ -176,11 +176,11 @@ A nested exception. Instantiates a new instance of the class with the specified error message and specified nested exception. - instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. - + instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + ]]> @@ -214,11 +214,11 @@ An error code. Instantiates a new instance of the class with the specified error message and specified error code. - instance is initialized with the property set to the value of `message` and the property set to the value of `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. - + instance is initialized with the property set to the value of `message` and the property set to the value of `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. + ]]> @@ -254,11 +254,11 @@ An error code. Instantiates a new instance of the class with the specified error message, the specified nested exception, and the specified error code. - instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, and the is set to `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. - + instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, and the is set to `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + ]]> @@ -332,11 +332,11 @@ The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml index 3a062602351..ff091c4443d 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalSearcher.xml @@ -33,7 +33,7 @@ class performs a query for domain principals. The application may override the default value by setting the property in the underlying object that is returned from the method. + The default page size of 256 KB is used when the class performs a query for domain principals. The application may override the default value by setting the property in the underlying object that is returned from the method. ]]> @@ -147,7 +147,7 @@ object contained in this property is obtained from the context property of the principal object set in the property. Queries are performed using the credentials specified in the principal context object and the container specified in the property. For and context types, the container is the Distinguished Name (DN) of a container object. + The object contained in this property is obtained from the context property of the principal object set in the property. Queries are performed using the credentials specified in the principal context object and the container specified in the property. For and context types, the container is the Distinguished Name (DN) of a container object. ]]> @@ -218,7 +218,7 @@ property. The search is conducted in the context specified in the property. For more information, see the Query by Example overview topic. + The principal objects returned in the principal search result match the type of object contained in the property. The search is conducted in the context specified in the property. For more information, see the Query by Example overview topic. ]]> @@ -262,7 +262,7 @@ ## Remarks If there is exactly one match of the object specified in the , this method returns that object. If there are multiple matches of the object, this method arbitrarily returns one of the matching principals. - The object returned from this method matches the type of object contained in the property. The search is conducted in the context specified in the property. For more information, see the [Query by Example](https://learn.microsoft.com/previous-versions/bb384378(v=vs.90)) overview topic. + The object returned from this method matches the type of object contained in the property. The search is conducted in the context specified in the property. For more information, see the [Query by Example](https://learn.microsoft.com/previous-versions/bb384378(v=vs.90)) overview topic. ]]> @@ -304,7 +304,7 @@ object before executing the query. The query will then execute using the modified properties. For example, the default page size of 256 KB is used when the class performs a query for principals. The application may override the default value by setting the property in the underlying object that is returned from this method. + The application can modify the properties directly on the object before executing the query. The query will then execute using the modified properties. For example, the default page size of 256 KB is used when the class performs a query for principals. The application may override the default value by setting the property in the underlying object that is returned from this method. ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/PrincipalServerDownException.xml b/xml/System.DirectoryServices.AccountManagement/PrincipalServerDownException.xml index 89b7c6d3627..cec9173485a 100644 --- a/xml/System.DirectoryServices.AccountManagement/PrincipalServerDownException.xml +++ b/xml/System.DirectoryServices.AccountManagement/PrincipalServerDownException.xml @@ -67,11 +67,11 @@ Instantiates a new instance of the class. - class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The property is initialized to `null`. - + class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The property is initialized to `null`. + ]]> @@ -103,11 +103,11 @@ An error message. Instantiates a new instance of the class with the specified error message. - instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. - + instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. + ]]> @@ -176,11 +176,11 @@ A nested exception. Instantiates a new instance of the class with the specified error message and specified nested exception. - instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. - + instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + ]]> @@ -214,11 +214,11 @@ An error code. Instantiates a new instance of the class with the specified error message and specified error code. - instance is initialized with the property set to the value of `message` and the property set to the value of `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. - + instance is initialized with the property set to the value of `message` and the property set to the value of `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. + ]]> @@ -254,11 +254,11 @@ An error code. Instantiates a new instance of the class with the specified error message, the specified nested exception, and the specified error code. - instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, and the private `errorCode` property is set to `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. - + instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, and the private `errorCode` property is set to `errorCode`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + ]]> @@ -296,11 +296,11 @@ A server name. Instantiates a new instance of the class with the specified error message, the specified nested exception, the specified error code, and the specified server name. - instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, the private `errorCode` property is set to `errorCode`, and the private `serverName` property is set to `serverName`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. - + instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`, the private `errorCode` property is set to `errorCode`, and the private `serverName` property is set to `serverName`. If `message` is `null`, the property is initialized to a system-supplied message. The is initialized to `null`. + ]]> @@ -345,13 +345,13 @@ A object that will hold contextual information about the source or destination. Sets the with the parameter name and additional exception information. - sets a with all the exception object data targeted for serialization. During deserialization, the exception object is reconstituted from the transmitted over the stream. - - For more information, see . - + sets a with all the exception object data targeted for serialization. During deserialization, the exception object is reconstituted from the transmitted over the stream. + + For more information, see . + ]]> diff --git a/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml b/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml index 61986391fda..87b36b16a19 100644 --- a/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml +++ b/xml/System.DirectoryServices.AccountManagement/UserPrincipal.xml @@ -68,39 +68,39 @@ The that specifies the server or domain against which operations are performed. Initializes a new instance of the class by using the specified context. - method. - - - -## Examples - The following code example connects to the LDAP domain "fabrikam.com" with the username and password initialized in the constructor to "administrator" and "securelyStoredPassword." - - The properties set in the example, such as user name and email address, are created under the container specified in the constructor: "CN=Users,DC=fabrikam,DC=com." - -``` - -PrincipalContext ctx = new PrincipalContext( - ContextType.Domain, - "fabrikam.com", - "CN=Users,DC=fabrikam,DC=com", - "administrator", - "securelyStoredPassword"); - -UserPrincipal usr = new UserPrincipal(ctx); - -usr.Name = "Jim Daly"; -usr.Description = "This is the user account for Jim Daly"; -usr.EmailAddress = "jimdaly@fabrikam.com"; -usr.SetPassword("securelyStoredPassword"); -usr.Save(); - -usr.Dispose(); -ctx.Dispose(); -``` - + method. + + + +## Examples + The following code example connects to the LDAP domain "fabrikam.com" with the username and password initialized in the constructor to "administrator" and "securelyStoredPassword." + + The properties set in the example, such as user name and email address, are created under the container specified in the constructor: "CN=Users,DC=fabrikam,DC=com." + +``` + +PrincipalContext ctx = new PrincipalContext( + ContextType.Domain, + "fabrikam.com", + "CN=Users,DC=fabrikam,DC=com", + "administrator", + "securelyStoredPassword"); + +UserPrincipal usr = new UserPrincipal(ctx); + +usr.Name = "Jim Daly"; +usr.Description = "This is the user account for Jim Daly"; +usr.EmailAddress = "jimdaly@fabrikam.com"; +usr.SetPassword("securelyStoredPassword"); +usr.Save(); + +usr.Dispose(); +ctx.Dispose(); +``` + ]]> @@ -132,11 +132,11 @@ ctx.Dispose(); A Boolean value that specifies whether the account is enabled. Initializes a new instance of the class by using the specified context, SAM account name, password, and enabled value. - method. - + method. + ]]> @@ -274,11 +274,11 @@ ctx.Dispose(); Returns a collection of objects for users that have an incorrect password attempt recorded in the specified date and time range. A that contains one or more objects, or an empty collection if no results are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -312,11 +312,11 @@ ctx.Dispose(); Returns a collection of objects for users that have an account expiration time in the specified date and time range. A that contains one or more objects, or an empty collection if no results are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -389,33 +389,33 @@ ctx.Dispose(); Returns a user principal object that matches the specified identity type, and value. This version of the method determines the format of the identity value. A object that matches the specified identity value and type, or null if no matches are found. - constructor, the credentials of the user running the current thread are used. - - A search is performed to find the user who has SamAccountName "Guest". - - If the user is found, a check is performed to determine whether this user's account is enabled. If the account is not enabled, the example code enables it. - -``` -PrincipalContext ctx = new PrincipalContext(ContextType.Machine); - -UserPrincipal usr = UserPrincipal.FindByIdentity(ctx, - IdentityType.SamAccountName, - "Guest"); - -if(usr != null) -{ - if (!usr.Enabled) - usr.Enabled = true; - - usr.Save(); - usr.Dispose(); -} -ctx.Dispose(); -``` - + constructor, the credentials of the user running the current thread are used. + + A search is performed to find the user who has SamAccountName "Guest". + + If the user is found, a check is performed to determine whether this user's account is enabled. If the account is not enabled, the example code enables it. + +``` +PrincipalContext ctx = new PrincipalContext(ContextType.Machine); + +UserPrincipal usr = UserPrincipal.FindByIdentity(ctx, + IdentityType.SamAccountName, + "Guest"); + +if(usr != null) +{ + if (!usr.Enabled) + usr.Enabled = true; + + usr.Save(); + usr.Dispose(); +} +ctx.Dispose(); +``` + ]]> Multiple user principal objects matching the current user object were found. @@ -451,11 +451,11 @@ ctx.Dispose(); Returns a collection of objects for users that have an account lockout time in the specified date and time range. A that contains one or more objects, or an empty collection if no results are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -489,11 +489,11 @@ ctx.Dispose(); Returns a collection of objects for users that have account logon recorded in the specified date and time range. A that contains one or more objects, or an empty collection if no results are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -527,11 +527,11 @@ ctx.Dispose(); Returns a collection of objects for users that have set their password within the specified date and time range. A that contains one or more objects, or an empty collection if no results are found. - property of the `time` object as . - + property of the `time` object as . + ]]> @@ -558,13 +558,13 @@ ctx.Dispose(); Returns a collection of principal objects that contains all the authorization groups of which this user is a member. This function only returns groups that are security groups; distribution groups are not returned. A collection of objects that contain the groups of which the user is a member, or null if the user does not belong to any security groups. - The attempt to retrieve authorization groups failed. diff --git a/xml/System.DirectoryServices.ActiveDirectory/ApplicationPartition.xml b/xml/System.DirectoryServices.ActiveDirectory/ApplicationPartition.xml index 8fbcce5b3dd..9b2e6051d30 100644 --- a/xml/System.DirectoryServices.ActiveDirectory/ApplicationPartition.xml +++ b/xml/System.DirectoryServices.ActiveDirectory/ApplicationPartition.xml @@ -176,7 +176,7 @@ property returns the same collection of objects as the method if the object has been committed to the underlying directory services store. + The property returns the same collection of objects as the method if the object has been committed to the underlying directory services store. ]]> diff --git a/xml/System.DirectoryServices.Protocols/AddRequest.xml b/xml/System.DirectoryServices.Protocols/AddRequest.xml index b9f7edd196e..f4014e6c40b 100644 --- a/xml/System.DirectoryServices.Protocols/AddRequest.xml +++ b/xml/System.DirectoryServices.Protocols/AddRequest.xml @@ -25,11 +25,11 @@ The class adds an entry to the directory. - or it can be used as the parameter for . - + or it can be used as the parameter for . + ]]> @@ -117,11 +117,11 @@ The object class for this object. If this parameter is , an exception is thrown. The constructor creates an instance of the class using the specified and the object class. - property. This value can be modified after this constructor is called. - + property. This value can be modified after this constructor is called. + ]]> The parameter contains a null reference ( in Visual Basic). @@ -148,11 +148,11 @@ The property contains a of attribute-value pairs for the object. A of attribute-value pairs for the object. - diff --git a/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml b/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml index a088f9c4e66..c1765c51049 100644 --- a/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml +++ b/xml/System.DirectoryServices.Protocols/DsmlRequestDocument.xml @@ -531,7 +531,7 @@ using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + Derived classes can provide synchronized versions of the using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. ]]> diff --git a/xml/System.DirectoryServices.Protocols/DsmlResponseDocument.xml b/xml/System.DirectoryServices.Protocols/DsmlResponseDocument.xml index de82826ad39..13071e05cdc 100644 --- a/xml/System.DirectoryServices.Protocols/DsmlResponseDocument.xml +++ b/xml/System.DirectoryServices.Protocols/DsmlResponseDocument.xml @@ -57,9 +57,9 @@ is less than zero.
is multidimensional. - - -or- - + + -or- + The number of elements in the source is greater than the available space from *i* to the end of the destination . The type of the source cannot be cast automatically to the type of the destination . @@ -225,11 +225,11 @@ The property contains the RequestID associated with the document. The RequestID associated with the document. - You attempted to set the property value. @@ -255,11 +255,11 @@ The property contains an object that can be used to synchronize access to the . An object that can be used to synchronize access to the . - using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. - + using the property. The synchronizing code must perform operations on the of the , not directly on the . This ensures proper operation of collections derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + ]]> diff --git a/xml/System.DirectoryServices.Protocols/DsmlSoapConnection.xml b/xml/System.DirectoryServices.Protocols/DsmlSoapConnection.xml index 3c33117eff3..3a45c33bc8b 100644 --- a/xml/System.DirectoryServices.Protocols/DsmlSoapConnection.xml +++ b/xml/System.DirectoryServices.Protocols/DsmlSoapConnection.xml @@ -57,11 +57,11 @@ Instructs the DSML server to start a new session. - property. - + property. + ]]> A session is already open on the connection. @@ -89,13 +89,13 @@ Ends the session with the DSML server and clears the property. - property. - - If the DSML server terminates the session, a is thrown. If is still valid after the exception is thrown, the request never reached the server and the connection is still considered valid. - + property. + + If the DSML server terminates the session, a is thrown. If is still valid after the exception is thrown, the request never reached the server and the connection is still considered valid. + ]]> A communications failure occurred with the DSML server. @@ -144,15 +144,15 @@ Gets or sets the SOAP Header attached to outgoing requests. The SOAP Header attached to outgoing requests. - and to track the lifetime of a session. - +The API uses and to track the lifetime of a session. + > [!CAUTION] -> Attaching an `EndSession` header to the causes the API to become inconsistent with the connection and should be avoided. - +> Attaching an `EndSession` header to the causes the API to become inconsistent with the connection and should be avoided. + ]]> diff --git a/xml/System.DirectoryServices.Protocols/DsmlSoapHttpConnection.xml b/xml/System.DirectoryServices.Protocols/DsmlSoapHttpConnection.xml index 2efdd052ff1..463f7869b14 100644 --- a/xml/System.DirectoryServices.Protocols/DsmlSoapHttpConnection.xml +++ b/xml/System.DirectoryServices.Protocols/DsmlSoapHttpConnection.xml @@ -237,11 +237,11 @@ Instructs the DSML server to start a new session. - property. - + property. + ]]> A session is already open on the connection. @@ -302,13 +302,13 @@ Ends the session with the DSML server and clears the property. - property. - - If the DSML server has already terminated the session on its own, a will be thrown. If the is still valid after the exception is thrown, the request never reached the server and the connection is still considered valid. - + property. + + If the DSML server has already terminated the session on its own, a will be thrown. If the is still valid after the exception is thrown, the request never reached the server and the connection is still considered valid. + ]]> There is a communications failure with the DSML server. @@ -424,11 +424,11 @@ Gets or sets the SOAP Action Header sent with other HTTP headers. The SOAP Action Header sent with other HTTP headers. - diff --git a/xml/System.DirectoryServices.Protocols/LdapConnection.xml b/xml/System.DirectoryServices.Protocols/LdapConnection.xml index 442f4ab4676..f80a298d5dd 100644 --- a/xml/System.DirectoryServices.Protocols/LdapConnection.xml +++ b/xml/System.DirectoryServices.Protocols/LdapConnection.xml @@ -33,7 +33,7 @@ property on the object and property on the object are both set, the certificate specified in the property is ignored. + If the property on the object and property on the object are both set, the certificate specified in the property is ignored. ]]> @@ -667,7 +667,7 @@ If a connection was created using `ldap_connect`, and if no binding function is property on the object and property on the object are both set, the certificate specified in the property is ignored. + If the property on the object and property on the object are both set, the certificate specified in the property is ignored. ]]> diff --git a/xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml b/xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml index e9619e6d335..e8c07efcb2f 100644 --- a/xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml +++ b/xml/System.DirectoryServices.Protocols/LdapSessionOptions.xml @@ -296,7 +296,7 @@ property on the object is also set, the certificate specified in the property is ignored. + If the property on the object is also set, the certificate specified in the property is ignored. ]]> diff --git a/xml/System.DirectoryServices/DirectoryEntries.xml b/xml/System.DirectoryServices/DirectoryEntries.xml index 1ba7389101e..267d8ac4d40 100644 --- a/xml/System.DirectoryServices/DirectoryEntries.xml +++ b/xml/System.DirectoryServices/DirectoryEntries.xml @@ -457,7 +457,7 @@ class MyClass1 property is empty, child objects of all types are visible in the collection; otherwise, only those of the specified types are visible. + If the property is empty, child objects of all types are visible in the collection; otherwise, only those of the specified types are visible. ]]> diff --git a/xml/System.DirectoryServices/DirectoryEntry.xml b/xml/System.DirectoryServices/DirectoryEntry.xml index ab4b7346857..978b50211ce 100644 --- a/xml/System.DirectoryServices/DirectoryEntry.xml +++ b/xml/System.DirectoryServices/DirectoryEntry.xml @@ -43,15 +43,15 @@ , along with helper classes, provides support for life-cycle management and navigation methods. These include creating, deleting, renaming, moving a child node, and enumerating children. After you modify a node, you must commit your changes in order for them to be saved to the tree. For more information, see the property. + Use this class for binding to objects, or reading and updating attributes. , along with helper classes, provides support for life-cycle management and navigation methods. These include creating, deleting, renaming, moving a child node, and enumerating children. After you modify a node, you must commit your changes in order for them to be saved to the tree. For more information, see the property. can be used to access regular entries and some, but not all, information from schema entries. The Active Directory Domain Services hierarchy contains up to several thousand nodes. Each node represents an object, such as a network printer or a user in a domain. Corporate networks constantly change as new employees are hired and objects such as network printers and computers are added. Active Directory Service Interfaces (ADSI) technology provides ways to programmatically add these objects to the directory tree. - To create a directory entry in the hierarchy, use the property. The property is a collection that provides an method, through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. + To create a directory entry in the hierarchy, use the property. The property is a collection that provides an method, through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. - This class also contains attribute caching, which can be useful for optimizing network traffic. To use attribute caching, see the property. + This class also contains attribute caching, which can be useful for optimizing network traffic. To use attribute caching, see the property. The classes associated with the component can be used with any of the Active Directory Domain Services service providers. Some of the current providers are Internet Information Services (IIS), Lightweight Directory Access Protocol (LDAP), Novell NetWare Directory Service (NDS), and WinNT. @@ -158,7 +158,7 @@ ## Examples -The following example binds a object to the directory entry at the specified path, and displays the property of each child entry that is specified by the node's property. +The following example binds a object to the directory entry at the specified path, and displays the property of each child entry that is specified by the node's property. ```vb Public Class PrintChildren @@ -373,7 +373,7 @@ public class PrintChildren{ Use this property to find, retrieve, or create a directory entry in the hierarchy. This property is a collection that, along with the usual iteration capabilities, provides an method through which you add a node to the collection directly below the parent node that you are currently bound to. When adding a node to the collection, you must specify a name for the new node and the name of a schema template that you want to associate with the node. For example, you might want to use a schema titled "Computer" to add new computers to the hierarchy. > [!NOTE] -> By default, changes are made locally to a cache. After you modify or add a node, you must call the method to commit your changes in order for them to be saved to the tree. If you call before calling , any uncommitted changes to the property cache will be lost. For more information, see the and methods, and the property. +> By default, changes are made locally to a cache. After you modify or add a node, you must call the method to commit your changes in order for them to be saved to the tree. If you call before calling , any uncommitted changes to the property cache will be lost. For more information, see the and methods, and the property. ]]> @@ -763,7 +763,7 @@ if (DirectoryEntry.Exists(myADSPath)) property. + When binding to an object in Active Directory Domain Services, use the property. ## Examples @@ -895,7 +895,7 @@ Console.WriteLine("The Native GUID of the ADS"+ property should be used to access the properties of the object. + This method should not be used. The property should be used to access the properties of the object. ]]> @@ -952,7 +952,7 @@ Console.WriteLine("The Native GUID of the ADS"+ property should be used to access the properties of the object. + This method should not be used. The property should be used to access the properties of the object. ]]> @@ -1183,7 +1183,7 @@ foreach(DirectoryEntry myDirectoryEntryChild in property when binding an object in Active Directory Domain Services. + Use the property when binding an object in Active Directory Domain Services. > [!NOTE] > The Lightweight Directory Access Protocol (LDAP) provider returns the globally unique identifier of a in a different format than the Internet Information Services (IIS), Novell NetWare Directory Server (NDS), and WinNT providers. @@ -1575,7 +1575,7 @@ foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) property uniquely identifies this entry in a networked environment. This entry can always be retrieved using this . + The property uniquely identifies this entry in a networked environment. This entry can always be retrieved using this . Setting the retrieves a new entry from the directory store; it does not change the path of the currently bound entry. @@ -1584,7 +1584,7 @@ foreach(DirectoryEntry myChildDirectoryEntry in myDirectoryEntry.Children) > [!NOTE] > The section of the that identifies the provider (precedes "://") is case-sensitive. For example, "LDAP://" or "WinNT://". - The syntax for the property varies according to the provider. Some common scenarios are: + The syntax for the property varies according to the provider. Some common scenarios are: WinNT @@ -1665,7 +1665,7 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); ## Remarks If the property is not initialized, calls the ADSI interface [IADs::Get](/windows/win32/api/iads/nf-iads-iads-get) method to retrieve the value from the cache. If the underling cache has not been loaded, [IADs::Get](/windows/win32/api/iads/nf-iads-iads-get) implicitly calls [IADs::GetInfo](/windows/win32/api/iads/nf-iads-iads-getinfo). This method loads the values of the supported properties that have not been set in the cache from the underlying directory store. Subsequent calls to retrieves the property values in the cache only. To control property cache loading, call . - **Note** The property is not supported for use with the Active Directory Client Extension (DSClient) for Windows NT 4.0. + **Note** The property is not supported for use with the Active Directory Client Extension (DSClient) for Windows NT 4.0. ]]> @@ -1844,7 +1844,7 @@ DirectoryEntry domain = new DirectoryEntry("LDAP://" + str); property of the property. + This is the same as the property of the property. A object's schema defines its properties and methods. @@ -2027,9 +2027,9 @@ if (string.Compare(mySchemaEntry.Name,"container") == 0) property is `true`, access to the object's properties is faster. Setting this to `false` will cause the cache to be committed after each operation. + By default, changes to properties are made locally to a cache, and property values to be read are cached after the first read. When the property is `true`, access to the object's properties is faster. Setting this to `false` will cause the cache to be committed after each operation. - If the property is `true` and you want to commit cached changes, call the method. To update values in the cache after changes to the directory are made, call the method. + If the property is `true` and you want to commit cached changes, call the method. To update values in the cache after changes to the directory are made, call the method. > [!CAUTION] > If you call before calling , any uncommitted changes to the property cache will be lost. diff --git a/xml/System.DirectoryServices/DirectorySearcher.xml b/xml/System.DirectoryServices/DirectorySearcher.xml index 3704694fdd3..35766640de7 100644 --- a/xml/System.DirectoryServices/DirectorySearcher.xml +++ b/xml/System.DirectoryServices/DirectorySearcher.xml @@ -37,17 +37,17 @@ ## Remarks Use a object to search and perform queries against an Active Directory Domain Services hierarchy using Lightweight Directory Access Protocol (LDAP). LDAP is the only system-supplied Active Directory Service Interfaces (ADSI) provider that supports directory searching. An administrator can make, alter, and delete objects that are found in the hierarchy. For more information, see [Using System.DirectoryServices](https://learn.microsoft.com/previous-versions/ms180832(v=vs.90)). - When you create an instance of , you specify the root you want to retrieve, and an optional list of properties to retrieve. The property enables you to set additional properties to do the following tasks: + When you create an instance of , you specify the root you want to retrieve, and an optional list of properties to retrieve. The property enables you to set additional properties to do the following tasks: -- Cache the search results on the local computer. Set the property to `true` to store directory information on the local computer. Updates are made to this local cache and committed to Active Directory Domain Services only when the method is called. +- Cache the search results on the local computer. Set the property to `true` to store directory information on the local computer. Updates are made to this local cache and committed to Active Directory Domain Services only when the method is called. -- Specify the length of time to search, using the property. +- Specify the length of time to search, using the property. -- Retrieve attribute names only. Set the property to `true` to retrieve only the names of attributes to which values have been assigned. +- Retrieve attribute names only. Set the property to `true` to retrieve only the names of attributes to which values have been assigned. -- Perform a paged search. Set the property to specify the maximum number of objects that are returned in a paged search. If you do not want to perform a paged search, set the property to its default of zero. +- Perform a paged search. Set the property to specify the maximum number of objects that are returned in a paged search. If you do not want to perform a paged search, set the property to its default of zero. -- Specify the maximum number of entries to return, using the property. If you set the property to its default of zero, the server-determined default is 1000 entries. +- Specify the maximum number of entries to return, using the property. If you set the property to its default of zero, the server-determined default is 1000 entries. > [!NOTE] > If the maximum number of returned entries and time limits exceed the limitations that are set on the server, the server settings override the component settings. @@ -593,14 +593,14 @@ SearchResultCollection res = src.FindAll(); The search is performed against the objects that are identified by the distinguished name that is specified in the attribute of the base object. For example, if the base object is an adschema group class and the is set to "member," then the search will be performed against all objects that are members of the group. For more information, see the [Group class](/windows/desktop/adschema/c-group) article. - When the property is used, the property must be set to . If the property is set to any other value, setting the property will throw an . + When the property is used, the property must be set to . If the property is set to any other value, setting the property will throw an . For more information, see the [Performing an Attribute Scope Query](/windows/desktop/adsi/performing-an-attribute-scoped-query). ## Examples - The following example shows how to use the property with the member attribute to get the members of a group. It then prints out the first and last names of the members and their telephone numbers. + The following example shows how to use the property with the member attribute to get the members of a group. It then prints out the first and last names of the members and their telephone numbers. ```csharp using System; @@ -762,7 +762,7 @@ public class Example property to , so that it dereferences aliases when both searching subordinates and locating base objects. + The following C# example shows how to set the property to , so that it dereferences aliases when both searching subordinates and locating base objects. ``` using System.DirectoryServices; @@ -1115,7 +1115,7 @@ SearchResultCollection res = src.FindAll(); property, it will stop searching and return the results to the client. When the client requests more data, the server will restart the search where it left off. + After the server has found the number of objects that are specified by the property, it will stop searching and return the results to the client. When the client requests more data, the server will restart the search where it left off. ]]> @@ -1527,7 +1527,7 @@ SearchResultCollection res = src.FindAll(); ## Remarks The minimum resolution of this property is one second. Fractions of seconds are ignored. - Unlike the property, the property indicates the total amount of time that the server will spend on a search. When the time limit is reached, the server stops searching and returns the results that have accumulated up to that point. + Unlike the property, the property indicates the total amount of time that the server will spend on a search. When the time limit is reached, the server stops searching and returns the results that have accumulated up to that point. Set to -1 second to use the server-determined default. @@ -1677,7 +1677,7 @@ SearchResultCollection res = src.FindAll(); property to `true`. + The following C# example shows how to set the property to `true`. ```csharp using System.DirectoryServices; diff --git a/xml/System.DirectoryServices/DirectoryVirtualListView.xml b/xml/System.DirectoryServices/DirectoryVirtualListView.xml index 9c9dc093996..638a15818fa 100644 --- a/xml/System.DirectoryServices/DirectoryVirtualListView.xml +++ b/xml/System.DirectoryServices/DirectoryVirtualListView.xml @@ -27,62 +27,62 @@ The class specifies how to conduct a virtual list view search. A virtual list view search enables users to view search results as address-book style virtual list views. It is specifically designed for very large result sets. Search data is retrieved in contiguous subsets of a sorted directory search. - @@ -445,11 +445,11 @@ foreach(SearchResult res in src.FindAll() ) Gets or sets a value to indicate the target entry's offset within the list. An integer value that represents the target entry's estimated offset within the list. - property is computed by dividing the value of the property by the value of the property, and multiplying the result by 100. - + property is computed by dividing the value of the property by the value of the property, and multiplying the result by 100. + ]]> The property is set to a value less than 0. @@ -537,11 +537,11 @@ foreach(SearchResult res in src.FindAll() ) The property gets or sets a value to indicate the estimated target entry's requested offset within the list, as a percentage of the total number of items in the list. An integer value that represents the estimated percentage offset within the list of the target entry. - property is computed by multiplying the value of the property by the value of the property, and dividing the result by 100. - + property is computed by multiplying the value of the property by the value of the property, and dividing the result by 100. + ]]> The property is set to a value greater than 100 or less than 0. diff --git a/xml/System.DirectoryServices/PropertyCollection.xml b/xml/System.DirectoryServices/PropertyCollection.xml index 92bfb766044..f7d25150664 100644 --- a/xml/System.DirectoryServices/PropertyCollection.xml +++ b/xml/System.DirectoryServices/PropertyCollection.xml @@ -244,7 +244,7 @@ property, a might be thrown due to an error while accessing the underlying interface. + When accessing members of the property, a might be thrown due to an error while accessing the underlying interface. ]]> @@ -392,7 +392,7 @@ Dim myCollection As New ICollection() ## Remarks For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's SyncRoot property. - Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a Synchronized method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. In the absence of a Synchronized method on a collection, the expected usage for looks like this: @@ -475,7 +475,7 @@ Dim myCollection As New ICollection() property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. @@ -624,7 +624,7 @@ Dim myCollection As New ICollection() ## Examples - The following example demonstrates how to implement the property. This code example is part of a larger example provided for the class. + The following example demonstrates how to implement the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet6"::: @@ -669,7 +669,7 @@ Dim myCollection As New ICollection() ## Examples - The following example shows how to implement the property. This code example is part of a larger example provided for the class. + The following example shows how to implement the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet4"::: @@ -721,12 +721,12 @@ Dim myCollection As New ICollection() ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[key]`. - You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. + You can also use the property to add new elements by setting the value of a key that does not exist in the dictionary (for example, `myCollection["myNonexistentKey"] = myValue`). However, if the specified key already exists in the dictionary, setting the property overwrites the old value. In contrast, the method does not modify existing elements. ## Examples - The following example shows how to implement the property. This code example is part of a larger example provided for the class. + The following example shows how to implement the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet13"::: @@ -773,12 +773,12 @@ Dim myCollection As New ICollection() object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. + The order of the keys in the returned object is unspecified, but is guaranteed to be the same order as the corresponding values in the returned by the property. ## Examples - The following example shows how to implement the property. This code example is part of a larger example provided for the class. + The following example shows how to implement the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Collections/DictionaryEntry/Key/Dictionary.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Collections/DictionaryEntry/Key/Dictionary.vb" id="Snippet10"::: @@ -875,7 +875,7 @@ Dim myCollection As New ICollection() Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection. - Initially, the enumerator is positioned before the first element in the collection. also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . + Initially, the enumerator is positioned before the first element in the collection. also brings the enumerator back to this position. At this position, the property is undefined. Therefore, you must call to advance the enumerator to the first element of the collection before reading the value of . returns the same object until either or is called. sets to the next element. @@ -921,7 +921,7 @@ Dim myCollection As New ICollection() property, a exception might be thrown due to an error while accessing the underlying interface. + When accessing members of the property, a exception might be thrown due to an error while accessing the underlying interface. ]]> diff --git a/xml/System.DirectoryServices/SchemaNameCollection.xml b/xml/System.DirectoryServices/SchemaNameCollection.xml index 66791979cbb..e132f25d614 100644 --- a/xml/System.DirectoryServices/SchemaNameCollection.xml +++ b/xml/System.DirectoryServices/SchemaNameCollection.xml @@ -632,7 +632,7 @@ Dim myCollection As New ICollection() ## Remarks For collections with an underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. In the absence of a `Synchronized` method on a collection, the expected usage for looks like this: diff --git a/xml/System.DirectoryServices/SearchResult.xml b/xml/System.DirectoryServices/SearchResult.xml index fa4ea583538..432de2e4c59 100644 --- a/xml/System.DirectoryServices/SearchResult.xml +++ b/xml/System.DirectoryServices/SearchResult.xml @@ -255,13 +255,13 @@ Console.WriteLine("\nThe name of the 'myDirectoryEntry' " + ## Remarks -The property uniquely identifies this entry in the Active Directory Domain Services hierarchy. The entry can always be retrieved using this path. +The property uniquely identifies this entry in the Active Directory Domain Services hierarchy. The entry can always be retrieved using this path. ## Examples The following example is an excerpt of the example in . The original example creates a new object with the desired path and uses the method to initiate the search. After performing the search, the example uses the method to retrieve the live directory entry that is identified in the search results. -This example shows how to parse the property from the search result. +This example shows how to parse the property from the search result. ```vb Dim mySearchResultPath As String = mySearchResult.Path diff --git a/xml/System.DirectoryServices/SearchResultCollection.xml b/xml/System.DirectoryServices/SearchResultCollection.xml index 49e62c02f85..e471c3d4b5d 100644 --- a/xml/System.DirectoryServices/SearchResultCollection.xml +++ b/xml/System.DirectoryServices/SearchResultCollection.xml @@ -573,7 +573,7 @@ Dim myCollection As New ICollection() ## Remarks For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection's `SyncRoot` property. - Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. + Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. In the absence of a `Synchronized` method on a collection, the expected usage for looks like this: diff --git a/xml/System.Drawing.Design/IToolboxService.xml b/xml/System.Drawing.Design/IToolboxService.xml index a8a81b03fd2..90491287cac 100644 --- a/xml/System.Drawing.Design/IToolboxService.xml +++ b/xml/System.Drawing.Design/IToolboxService.xml @@ -44,9 +44,9 @@ You can retrieve information about the contents of the toolbox with the following methods: -- The property indicates the categories currently available on the toolbox. +- The property indicates the categories currently available on the toolbox. -- The property indicates the currently selected toolbox category. +- The property indicates the currently selected toolbox category. - The method retrieves the items on the toolbox, optionally filtered by a specified toolbox category. diff --git a/xml/System.Drawing.Design/PropertyValueUIItemInvokeHandler.xml b/xml/System.Drawing.Design/PropertyValueUIItemInvokeHandler.xml index c36e1a12e33..41007bd864f 100644 --- a/xml/System.Drawing.Design/PropertyValueUIItemInvokeHandler.xml +++ b/xml/System.Drawing.Design/PropertyValueUIItemInvokeHandler.xml @@ -39,18 +39,18 @@ The associated with the icon that was double-clicked. Represents the method that will handle the event of a . - event of the that the icon is associated with. The event typically launches a user interface (UI) to edit the property's value. Add a to the property of a to assign an event handler to perform the appropriate behavior when the icon displayed next to the property name is double-clicked. - - When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - -## Examples - The following code example provides a object for any properties of the component named `HorizontalMargin` or `VerticalMargin`. The for these properties provides an image, a ToolTip, and an event handler that displays a message box when the image for the property is clicked. This code example is part of a larger example provided for the interface. - + event of the that the icon is associated with. The event typically launches a user interface (UI) to edit the property's value. Add a to the property of a to assign an event handler to perform the appropriate behavior when the icon displayed next to the property name is double-clicked. + + When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). + +## Examples + The following code example provides a object for any properties of the component named `HorizontalMargin` or `VerticalMargin`. The for these properties provides an image, a ToolTip, and an event handler that displays a message box when the image for the property is clicked. This code example is part of a larger example provided for the interface. + :::code language="csharp" source="~/snippets/csharp/System.Drawing.Design/IPropertyValueUIService/Overview/propertyuicomponent.cs" id="Snippet2"::: - + ]]> diff --git a/xml/System.Drawing.Design/ToolboxItem.xml b/xml/System.Drawing.Design/ToolboxItem.xml index 4f7c182be2e..8b3f57d3cce 100644 --- a/xml/System.Drawing.Design/ToolboxItem.xml +++ b/xml/System.Drawing.Design/ToolboxItem.xml @@ -53,15 +53,15 @@ The following properties and methods must be configured for a to function correctly: -- The property specifies the label for the toolbox item when displayed in a toolbox. +- The property specifies the label for the toolbox item when displayed in a toolbox. -- The property specifies the fully qualified name of the type of the component that the item creates. If a derived class creates multiple components, the property may or may not be used, contingent on whether a method override depends on the value of this property. +- The property specifies the fully qualified name of the type of the component that the item creates. If a derived class creates multiple components, the property may or may not be used, contingent on whether a method override depends on the value of this property. -- The property specifies the assembly that contains the type of a component that the item creates. +- The property specifies the assembly that contains the type of a component that the item creates. -- The property optionally specifies a bitmap image to display next to the display name for the toolbox item in the toolbox. +- The property optionally specifies a bitmap image to display next to the display name for the toolbox item in the toolbox. -- The property optionally contains any objects that determine whether the toolbox item can be used on a particular component. +- The property optionally contains any objects that determine whether the toolbox item can be used on a particular component. - The method returns the component instance or instances to insert where this tool is used. @@ -71,11 +71,11 @@ - The method configures the toolbox item to create the specified type of component, if the method has not been overridden to behave differently. -- The property indicates whether the properties of the toolbox item can be changed. A toolbox item is typically locked after it is added to a toolbox. +- The property indicates whether the properties of the toolbox item can be changed. A toolbox item is typically locked after it is added to a toolbox. - The method locks a toolbox item. -- The method throws an exception if the property is `true`. +- The method throws an exception if the property is `true`. @@ -249,7 +249,7 @@ property specifies the assembly that contains the types of the components to create. + The property specifies the assembly that contains the types of the components to create. ]]> @@ -330,7 +330,7 @@ method throws an if the property of the is set to `true`. + The method throws an if the property of the is set to `true`. ]]> @@ -939,9 +939,9 @@ property indicates the string that is displayed for the toolbox item in the toolbox. + This property indicates the string that is displayed for the toolbox item in the toolbox. - By default, the base class sets its property to a short form of the fully qualified type name specified by the property. + By default, the base class sets its property to a short form of the fully qualified type name specified by the property. ]]> @@ -1028,7 +1028,7 @@ property collection contains objects that specify the policy that the design-time environment uses to determine whether a toolbox item can be used on the destination component. + The property collection contains objects that specify the policy that the design-time environment uses to determine whether a toolbox item can be used on the destination component. For more information on restricting the scope in which a can be used, see the documentation for the class. @@ -1284,11 +1284,11 @@ This method performs the following operations: -- Sets the property to an indicating the assembly of the specified type. +- Sets the property to an indicating the assembly of the specified type. -- Sets the property to a short type name based on the name of the specified type. +- Sets the property to a short type name based on the name of the specified type. -- Adds any attributes found on the specified type to the property collection. +- Adds any attributes found on the specified type to the property collection. ]]> @@ -1330,7 +1330,7 @@ property defaults to `false`. + The property defaults to `false`. ]]> @@ -1620,7 +1620,7 @@ property dictionary becomes read-only after the toolbox item has been locked. + The property dictionary becomes read-only after the toolbox item has been locked. Values in the properties dictionary are validated through the method, and default values are obtained from the method. @@ -1801,7 +1801,7 @@ property specifies the fully qualified type name of the type of component to create. + The property specifies the fully qualified type name of the type of component to create. ]]> diff --git a/xml/System.Drawing.Design/ToolboxItemContainer.xml b/xml/System.Drawing.Design/ToolboxItemContainer.xml index 850fcf30573..6ecc309aaac 100644 --- a/xml/System.Drawing.Design/ToolboxItemContainer.xml +++ b/xml/System.Drawing.Design/ToolboxItemContainer.xml @@ -27,13 +27,13 @@ Encapsulates a . - is a simple class that encapsulates a for efficiency. By having a single class that is always loaded, you can defer the loading of the until it is needed. Because new classes can be derived from , you could load a that could, in turn, load an assembly that is not already in memory. For a large collection of objects, this could cause a large number of assemblies to be loaded, which decreases performance. Instead, the toolbox service deals only with objects and retrieves their contained only when necessary. - - The is designed to hold any cached data from the . The default implementation only holds the filter of the , but deriving classes may choose to cache the name, image, and other information. objects support two forms of serialization: they can be serialized through standard runtime serialization, and they can also load and save themselves from a . The former provides a very easy way to save objects to a persistent storage. The latter provides a way to integrate objects with mixed data storage formats. - + is a simple class that encapsulates a for efficiency. By having a single class that is always loaded, you can defer the loading of the until it is needed. Because new classes can be derived from , you could load a that could, in turn, load an assembly that is not already in memory. For a large collection of objects, this could cause a large number of assemblies to be loaded, which decreases performance. Instead, the toolbox service deals only with objects and retrieves their contained only when necessary. + + The is designed to hold any cached data from the . The default implementation only holds the filter of the , but deriving classes may choose to cache the name, image, and other information. objects support two forms of serialization: they can be serialized through standard runtime serialization, and they can also load and save themselves from a . The former provides a very easy way to save objects to a persistent storage. The latter provides a way to integrate objects with mixed data storage formats. + ]]> @@ -70,11 +70,11 @@ The for which to create a . Initializes a new instance of the class from a . - . - + . + ]]> @@ -100,11 +100,11 @@ A data object that represents a . Initializes a new instance of the class from a . - class. It may contain data that can be read by one of the creators that have been supplied by the user. It may also be data with a clipboard format that has a creator assigned to it. In this case, the is created on demand. - + class. It may contain data that can be read by one of the creators that have been supplied by the user. It may also be data with a clipboard format that has a creator assigned to it. In this case, the is created on demand. + ]]> @@ -197,13 +197,13 @@ Returns a collection of objects that represent the current filter for the . A collection of objects. This never returns . - objects that represent any custom creators that should be included when the filter is generated. Custom creators may contribute to the filters. This parameter can be `null` if no creators are needed. - - The types stored in a may have a filter associated with them. Filters can be used to restrict the tools that can be placed on designers. - + objects that represent any custom creators that should be included when the filter is generated. Custom creators may contribute to the filters. This parameter can be `null` if no creators are needed. + + The types stored in a may have a filter associated with them. Filters can be used to restrict the tools that can be placed on designers. + ]]> @@ -294,13 +294,13 @@ Returns the contained in the . The contained in the . - objects that represent any custom creators that should be included when the is obtained. This parameter can be `null` if no creators are needed. - - The method returns a that represents the data stored in the . never returns `null`, nor does it ever raise an exception, except in extreme cases (for example, out of memory). If a cannot be fabricated, the appropriate exception is embedded within a special . The exception is thrown when the method on this special is called. This puts the exception at the point of user action. - + objects that represent any custom creators that should be included when the is obtained. This parameter can be `null` if no creators are needed. + + The method returns a that represents the data stored in the . never returns `null`, nor does it ever raise an exception, except in extreme cases (for example, out of memory). If a cannot be fabricated, the appropriate exception is embedded within a special . The exception is thrown when the method on this special is called. This puts the exception at the point of user action. + ]]> @@ -392,11 +392,11 @@ The streaming context passed in by the serializer when serializing this object. For a description of this member, see the method. - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -421,11 +421,11 @@ Gets an that describes this . An that describes this . - property creates the serialized version of the . The data object can be used by an application to store this . This data object is fabricated from the , if necessary. - + property creates the serialized version of the . The data object can be used by an application to store this . This data object is fabricated from the , if necessary. + ]]> @@ -460,11 +460,11 @@ The source of the filter to merge with the container's filter. Merges the container's filter with the filter from the given item. - method when the toolbox item is modified or configured. You should also call it if a new , which the changes the filter, is added. - + method when the toolbox item is modified or configured. You should also call it if a new , which the changes the filter, is added. + ]]> diff --git a/xml/System.Drawing.Design/ToolboxService.xml b/xml/System.Drawing.Design/ToolboxService.xml index 56f165d6741..59c66cad315 100644 --- a/xml/System.Drawing.Design/ToolboxService.xml +++ b/xml/System.Drawing.Design/ToolboxService.xml @@ -91,7 +91,7 @@ property may return an empty collection. + The category names correspond to various toolbox categories. If a toolbox does not implement any form of categories, the property may return an empty collection. ]]> @@ -135,7 +135,7 @@ ## Remarks The method gives you the opportunity to provide a derived version of a . By default, the class does not support linked items, so it returns `null` for link parameters that are not `null`. To provide link support, you should override this method to create a derived that is capable of handling links. - The data object passed in should contain data obtained from a prior call to the property on a toolbox item container. + The data object passed in should contain data obtained from a prior call to the property on a toolbox item container. ]]>
diff --git a/xml/System.Drawing.Drawing2D/ColorBlend.xml b/xml/System.Drawing.Drawing2D/ColorBlend.xml index e20a09b289a..f708c454ef9 100644 --- a/xml/System.Drawing.Drawing2D/ColorBlend.xml +++ b/xml/System.Drawing.Drawing2D/ColorBlend.xml @@ -81,15 +81,15 @@ Initializes a new instance of the class. - class in conjunction with the class to draw an ellipse to screen that has its colors blended. The ellipse is green on the left, blends to yellow, then to blue, and finally to red on the right. This is accomplished through the settings in the `myColors` and `myPositions` arrays used in the and properties. Note that the property of the object named `lgBrush2` must be made equal to the object `myBlend`. - + class in conjunction with the class to draw an ellipse to screen that has its colors blended. The ellipse is green on the left, blends to yellow, then to blue, and finally to red on the right. This is accomplished through the settings in the `myColors` and `myPositions` arrays used in the and properties. Note that the property of the object named `lgBrush2` must be made equal to the object `myBlend`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Drawing2D.ClassicMisc/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Drawing2D/AdjustableArrowCap/.ctor/form1.vb" id="Snippet4"::: + ]]> @@ -127,11 +127,11 @@ The number of colors and positions in this . Initializes a new instance of the class with the specified number of colors and positions. - - + + ]]> @@ -179,11 +179,11 @@ Gets or sets an array of colors that represents the colors to use at corresponding positions along a gradient. An array of structures that represents the colors to use at corresponding positions along a gradient. - structures that represents the colors to use at corresponding positions along a gradient. Along with the property, this property defines a multicolor gradient. - + structures that represents the colors to use at corresponding positions along a gradient. Along with the property, this property defines a multicolor gradient. + ]]> @@ -231,13 +231,13 @@ Gets or sets the positions along a gradient line. An array of values that specify percentages of distance along the gradient line. - property, this property defines a multicolor gradient. - + property, this property defines a multicolor gradient. + ]]> diff --git a/xml/System.Drawing.Drawing2D/DashStyle.xml b/xml/System.Drawing.Drawing2D/DashStyle.xml index 0d48af81d47..914172a66b2 100644 --- a/xml/System.Drawing.Drawing2D/DashStyle.xml +++ b/xml/System.Drawing.Drawing2D/DashStyle.xml @@ -34,22 +34,22 @@ Specifies the style of dashed lines drawn with a object. - , set the property of the . - - - -## Examples - The following code example demonstrates how to create a pen and set its property using the enumeration. - - This example is designed to be used with Windows Forms. Create a form that contains a named `Button3`. Paste the code into the form and associate the `Button3_Click` method with the button's event. - + , set the property of the . + + + +## Examples + The following code example demonstrates how to create a pen and set its property using the enumeration. + + This example is designed to be used with Windows Forms. Create a form that contains a named `Button3`. Paste the code into the form and associate the `Button3_Click` method with the button's event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ImageExample/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/Overview/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/Overview/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/Overview/form1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Drawing.Drawing2D/GraphicsPath.xml b/xml/System.Drawing.Drawing2D/GraphicsPath.xml index deffae691bf..f1ca33fab03 100644 --- a/xml/System.Drawing.Drawing2D/GraphicsPath.xml +++ b/xml/System.Drawing.Drawing2D/GraphicsPath.xml @@ -5700,7 +5700,7 @@ property specifies point types and flags for the data points in a path. For each point, bits 0 through 2 indicate the type of a point, and bits 3 through 7 hold a set of flags that specify the attributes of a point. The following table shows possible values and their meanings. + The array of bytes returned by the property specifies point types and flags for the data points in a path. For each point, bits 0 through 2 indicate the type of a point, and bits 3 through 7 hold a set of flags that specify the attributes of a point. The following table shows possible values and their meanings. |Value|Meaning| |-----------|-------------| diff --git a/xml/System.Drawing.Drawing2D/HatchBrush.xml b/xml/System.Drawing.Drawing2D/HatchBrush.xml index bb03f342cac..4dc84e0c903 100644 --- a/xml/System.Drawing.Drawing2D/HatchBrush.xml +++ b/xml/System.Drawing.Drawing2D/HatchBrush.xml @@ -38,12 +38,12 @@ , which fills the background and one for the lines that form the pattern over the background defined by the property. The property defines what type of pattern the brush has and can be any value from the enumeration. There are more than fifty elements in the enumeration. + A hatch pattern is made from two colors: one defined by the , which fills the background and one for the lines that form the pattern over the background defined by the property. The property defines what type of pattern the brush has and can be any value from the enumeration. There are more than fifty elements in the enumeration. The following illustration shows an ellipse filled with a horizontal hatch pattern. ![Hatch Pattern](~/add/media/hatch1.png) - + [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples diff --git a/xml/System.Drawing.Drawing2D/LinearGradientBrush.xml b/xml/System.Drawing.Drawing2D/LinearGradientBrush.xml index ac76885e66c..06dfab8ca07 100644 --- a/xml/System.Drawing.Drawing2D/LinearGradientBrush.xml +++ b/xml/System.Drawing.Drawing2D/LinearGradientBrush.xml @@ -50,9 +50,9 @@ By default, a two-color linear gradient is an even horizontal linear blend from the starting color to the ending color along the specified line. Customize the blend pattern using the class, the methods, or the methods. Customize the direction of the gradient by specifying the enumeration or the angle in the constructor. - Use the property to create a multicolor gradient. + Use the property to create a multicolor gradient. - The property specifies a local geometric transform applied to the gradient. + The property specifies a local geometric transform applied to the gradient. [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] @@ -1489,7 +1489,7 @@ property is a copy of the brush's geometric transform, you should dispose of the matrix when you no longer need it. + A geometric transform can be used to translate, scale, rotate, or skew the gradient fill. Because the matrix returned and by the property is a copy of the brush's geometric transform, you should dispose of the matrix when you no longer need it. ]]> diff --git a/xml/System.Drawing.Drawing2D/PathGradientBrush.xml b/xml/System.Drawing.Drawing2D/PathGradientBrush.xml index 795bbf7c60a..b76c1c363eb 100644 --- a/xml/System.Drawing.Drawing2D/PathGradientBrush.xml +++ b/xml/System.Drawing.Drawing2D/PathGradientBrush.xml @@ -46,7 +46,7 @@ ## Remarks The color gradient is a smooth shading of colors from the center point of the path to the outside boundary edge of the path. Blend factors, positions, and style affect where the gradient starts and ends, and how fast it changes shade. - Path gradient brushes do not obey the property of the object used to do the drawing. Areas filled using a object are rendered the same way (aliased) regardless of the smoothing mode. + Path gradient brushes do not obey the property of the object used to do the drawing. Areas filled using a object are rendered the same way (aliased) regardless of the smoothing mode. [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] @@ -1531,7 +1531,7 @@ PathGradientBrush pgBrush = new PathGradientBrush(myPath); property is a copy of the brush's geometric transform, you should dispose of the matrix when you no longer need it. + A geometric transform can be used to translate, scale, rotate, or skew the gradient fill. Because the matrix returned and by the property is a copy of the brush's geometric transform, you should dispose of the matrix when you no longer need it. ]]> diff --git a/xml/System.Drawing.Drawing2D/SmoothingMode.xml b/xml/System.Drawing.Drawing2D/SmoothingMode.xml index 7b754e9fa5a..d47c82bba72 100644 --- a/xml/System.Drawing.Drawing2D/SmoothingMode.xml +++ b/xml/System.Drawing.Drawing2D/SmoothingMode.xml @@ -34,19 +34,19 @@ Specifies whether smoothing (antialiasing) is applied to lines and curves and the edges of filled areas. - [!NOTE] -> When the property is specified by using the `SmoothingMode` enumeration, it does not affect text. To set the text rendering quality, use the property and the enumeration. - +> When the property is specified by using the `SmoothingMode` enumeration, it does not affect text. To set the text rendering quality, use the property and the enumeration. + > [!NOTE] -> When the property is specified by using the enumeration, it does not affect areas filled by a path gradient brush. Areas filled by using a object are rendered the same way (aliased) regardless of the setting for the property. - +> When the property is specified by using the enumeration, it does not affect areas filled by a path gradient brush. Areas filled by using a object are rendered the same way (aliased) regardless of the setting for the property. + ]]> diff --git a/xml/System.Drawing.Imaging/ColorPalette.xml b/xml/System.Drawing.Imaging/ColorPalette.xml index fba2d7dd879..4baf3139ba9 100644 --- a/xml/System.Drawing.Imaging/ColorPalette.xml +++ b/xml/System.Drawing.Imaging/ColorPalette.xml @@ -41,13 +41,13 @@ Defines an array of colors that make up a color palette. The colors are 32-bit ARGB colors. Not inheritable. - object directly. If you created a object, you could then manipulate the palette size for a particular image, which is not allowed. Use the property to obtain a object. - - The colors in the palette are limited to 32-bit ARGB colors. A 32-bit ARGB color has 8 bits each for alpha, red, green, and blue values. The lowest 8 bits make up the blue bit, the next 8 bits are green, the next 8 bits are red, and the most significant 8 bits are alpha. This means each component can vary from 0 to 255. Fully on is 255 and fully off is 0. Alpha is used to make the color value transparent (alpha = 0) or opaque (alpha = 255). The number of intensity levels in the image can be increased without increasing the number of colors used. This process creates what is called a halftone, and it offers increased contrast at a cost of decreased resolution. - + object directly. If you created a object, you could then manipulate the palette size for a particular image, which is not allowed. Use the property to obtain a object. + + The colors in the palette are limited to 32-bit ARGB colors. A 32-bit ARGB color has 8 bits each for alpha, red, green, and blue values. The lowest 8 bits make up the blue bit, the next 8 bits are green, the next 8 bits are red, and the most significant 8 bits are alpha. This means each component can vary from 0 to 255. Fully on is 255 and fully off is 0. Alpha is used to make the color value transparent (alpha = 0) or opaque (alpha = 255). The number of intensity levels in the image can be increased without increasing the number of colors used. This process creates what is called a halftone, and it offers increased contrast at a cost of decreased resolution. + ]]> @@ -224,15 +224,15 @@ Gets a value that specifies how to interpret the color information in the array of colors. - The following flag values are valid: - - 0x00000001 - The color values in the array contain alpha information. - - 0x00000002 - The colors in the array are grayscale values. - - 0x00000004 + The following flag values are valid: + + 0x00000001 + The color values in the array contain alpha information. + + 0x00000002 + The colors in the array are grayscale values. + + 0x00000004 The colors in the array are halftone values. To be added. diff --git a/xml/System.Drawing.Imaging/ImageCodecFlags.xml b/xml/System.Drawing.Imaging/ImageCodecFlags.xml index 7bdac21ccae..f7846815d5e 100644 --- a/xml/System.Drawing.Imaging/ImageCodecFlags.xml +++ b/xml/System.Drawing.Imaging/ImageCodecFlags.xml @@ -40,11 +40,11 @@ Provides attributes of an image encoder/decoder (codec). - class is used by the property of the class. - + class is used by the property of the class. + ]]> diff --git a/xml/System.Drawing.Imaging/PropertyItem.xml b/xml/System.Drawing.Imaging/PropertyItem.xml index c0acfc6bb13..3e761244c43 100644 --- a/xml/System.Drawing.Imaging/PropertyItem.xml +++ b/xml/System.Drawing.Imaging/PropertyItem.xml @@ -41,26 +41,26 @@ Encapsulates a metadata property to be included in an image file. Not inheritable. - is not intended to be used as a stand-alone object. A object is intended to be used by classes that are derived from . A object is used to retrieve and to change the metadata of existing image files, not to create the metadata. Therefore, the class does not have a defined `Public` constructor, and you cannot create an instance of a object. - - To work around the absence of a `Public` constructor, use an existing object instead of creating a new instance of the class. For more information, see . - - - -## Examples - The following code example demonstrates how to read and display the metadata in an image file using the class and the property. - - This example is designed to be used in a Windows Form that imports the namespace. Paste the code into the form and change the path to `fakePhoto.jpg` to point to an image file on your system. Call the `ExtractMetaData` method when handling the form's event, passing `e` as . - + is not intended to be used as a stand-alone object. A object is intended to be used by classes that are derived from . A object is used to retrieve and to change the metadata of existing image files, not to create the metadata. Therefore, the class does not have a defined `Public` constructor, and you cannot create an instance of a object. + + To work around the absence of a `Public` constructor, use an existing object instead of creating a new instance of the class. For more information, see . + + + +## Examples + The following code example demonstrates how to read and display the metadata in an image file using the class and the property. + + This example is designed to be used in a Windows Form that imports the namespace. Paste the code into the form and change the path to `fakePhoto.jpg` to point to an image file on your system. Call the `ExtractMetaData` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ImageExample/CPP/form1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/Overview/form1.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/Overview/form1.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/Overview/form1.vb" id="Snippet6"::: + ]]> How To: Read Image Metadata @@ -109,231 +109,231 @@ Gets or sets the ID of the property. The integer that represents the ID of the property. - @@ -426,24 +426,24 @@ Gets or sets an integer that defines the type of data contained in the property. An integer that defines the type of data contained in . - is an array of bytes.| -|2|Specifies that is a null-terminated ASCII string. If you set the type data member to ASCII type, you should set the property to the length of the string including the null terminator. For example, the string "Hello" would have a length of 6.| -|3|Specifies that is an array of unsigned short (16-bit) integers.| -|4|Specifies that is an array of unsigned long (32-bit) integers.| -|5|Specifies that data member is an array of pairs of unsigned long integers. Each pair represents a fraction; the first integer is the numerator and the second integer is the denominator.| -|6|Specifies that is an array of bytes that can hold values of any data type.| -|7|Specifies that is an array of signed long (32-bit) integers.| -|10|Specifies that is an array of pairs of signed long integers. Each pair represents a fraction; the first integer is the numerator and the second integer is the denominator.| - - For more information about property tags, see [Image Property Tag Constants](/windows/desktop/gdiplus/-gdiplus-constant-image-property-tag-constants). - + is an array of bytes.| +|2|Specifies that is a null-terminated ASCII string. If you set the type data member to ASCII type, you should set the property to the length of the string including the null terminator. For example, the string "Hello" would have a length of 6.| +|3|Specifies that is an array of unsigned short (16-bit) integers.| +|4|Specifies that is an array of unsigned long (32-bit) integers.| +|5|Specifies that data member is an array of pairs of unsigned long integers. Each pair represents a fraction; the first integer is the numerator and the second integer is the denominator.| +|6|Specifies that is an array of bytes that can hold values of any data type.| +|7|Specifies that is an array of signed long (32-bit) integers.| +|10|Specifies that is an array of pairs of signed long integers. Each pair represents a fraction; the first integer is the numerator and the second integer is the denominator.| + + For more information about property tags, see [Image Property Tag Constants](/windows/desktop/gdiplus/-gdiplus-constant-image-property-tag-constants). + ]]> @@ -492,11 +492,11 @@ Gets or sets the value of the property item. A byte array that represents the value of the property item. - property contains data in one of several different primitive types. To use the data, determine the data type using the property and convert the byte array accordingly. - + property contains data in one of several different primitive types. To use the data, determine the data type using the property and convert the byte array accordingly. + ]]> diff --git a/xml/System.Drawing.Printing/PageSettings.xml b/xml/System.Drawing.Printing/PageSettings.xml index ef3a4f33ed5..3e219c874a3 100644 --- a/xml/System.Drawing.Printing/PageSettings.xml +++ b/xml/System.Drawing.Printing/PageSettings.xml @@ -57,7 +57,7 @@ class is used to specify settings that modify the way a page will be printed. Typically, you set default settings for all pages to be printed through the property. To specify settings on a page-by-page basis, handle the or event and modify the argument included in the or , respectively. + The class is used to specify settings that modify the way a page will be printed. Typically, you set default settings for all pages to be printed through the property. To specify settings on a page-by-page basis, handle the or event and modify the argument included in the or , respectively. For more information about handling events, see the class overview. For more information about printing, see the namespace overview. @@ -160,7 +160,7 @@ constructor is similar to initializing a new instance of and setting the property. + The constructor is similar to initializing a new instance of and setting the property. ]]> @@ -202,7 +202,7 @@ property along with the property to calculate the printing area for the page. + Use the property along with the property to calculate the printing area for the page. ]]> @@ -287,7 +287,7 @@ property to determine if the printer supports color printing. If the printer supports color, but you do not want to print in color, set the property to `false`. The default will be `true`. + You can use the property to determine if the printer supports color printing. If the printer supports color, but you do not want to print in color, set the property to `false`. The default will be `true`. @@ -474,12 +474,12 @@ property to determine the angle, in degrees, that the portrait orientation is rotated to produce the landscape orientation. + You can use the property to determine the angle, in degrees, that the portrait orientation is rotated to produce the landscape orientation. ## Examples - The following code example sets a document's default page orientation to landscape through the property, and prints the document. The example has three prerequisites: + The following code example sets a document's default page orientation to landscape through the property, and prints the document. The example has three prerequisites: - A variable named `filePath` has been set to the path of the file to print. @@ -547,7 +547,7 @@ event, you can use this property along with the property to calculate the printing area for the page. + When handling the event, you can use this property along with the property to calculate the printing area for the page. @@ -614,9 +614,9 @@ represents the size of the paper through the property, which contains one of the values. + A represents the size of the paper through the property, which contains one of the values. - Set the property for the page to a valid , available through the collection. + Set the property for the page to a valid , available through the collection. For information about how you can specify a custom paper size, see the constructor. @@ -689,9 +689,9 @@ represents the source of the paper through the property, which contains one of the values. + A represents the source of the paper through the property, which contains one of the values. - Set the property for the page to a valid , available through the collection. + Set the property for the page to a valid , available through the collection. @@ -755,7 +755,7 @@ property returns the correct value, whether the page orientation is landscape or portrait. + The property returns the correct value, whether the page orientation is landscape or portrait. You can use this property to print outside the margins of the page, but within the printable area. @@ -805,9 +805,9 @@ represents the printer resolution of through the property, which contains one of the values. + A represents the printer resolution of through the property, which contains one of the values. - Set the property for the page to a valid , available through the collection. + Set the property for the page to a valid , available through the collection. diff --git a/xml/System.Drawing.Printing/PaperSize.xml b/xml/System.Drawing.Printing/PaperSize.xml index f317fce6150..d5f6528ca63 100644 --- a/xml/System.Drawing.Printing/PaperSize.xml +++ b/xml/System.Drawing.Printing/PaperSize.xml @@ -46,24 +46,24 @@ Specifies the size of a piece of paper. - and properties to get the paper sizes that are available on the printer and to set the paper size for a page, respectively. - - You can use the constructor to specify a custom paper size. The and property values can be set only for custom objects. - - For more information about printing, see the namespace overview. - - - -## Examples - The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. - + and properties to get the paper sizes that are available on the printer and to set the paper size for a page, respectively. + + You can use the constructor to specify a custom paper size. The and property values can be set only for custom objects. + + For more information about printing, see the namespace overview. + + + +## Examples + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: + ]]> @@ -81,16 +81,16 @@ Initializes a new instance of the class. - class. - -|Property|Initial value| -|--------------|-------------------| -||| -||| - + class. + +|Property|Initial value| +|--------------|-------------------| +||| +||| + ]]> @@ -162,20 +162,20 @@ The height of the paper, in hundredths of an inch. Initializes a new instance of the class. - created with this constructor always has its property set to . The and property values can be set only for custom objects. - - - -## Examples - The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. - + created with this constructor always has its property set to . The and property values can be set only for custom objects. + + + +## Examples + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: + ]]> @@ -219,11 +219,11 @@ Gets or sets the height of the paper, in hundredths of an inch. The height of the paper, in hundredths of an inch. - and property values can be set only for custom objects. - + and property values can be set only for custom objects. + ]]> The property is not set to . @@ -263,11 +263,11 @@ Gets the type of paper. One of the values. - constructor to specify a custom paper size. - + constructor to specify a custom paper size. + ]]> The property is not set to . @@ -313,20 +313,20 @@ Gets or sets the name of the type of paper. The name of the type of paper. - property is set to . - - - -## Examples - The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. - + property is set to . + + + +## Examples + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. The is identified as the property that will provide the display string for the item being added through the property of the combo box. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: + ]]> The property is not set to . @@ -375,131 +375,131 @@ Gets or sets an integer representing one of the values or a custom value. An integer representing one of the values, or a custom value. - enumeration members. A value equal to 48 or 49 or larger than 118 indicates a custom paper size; however, the property will return the actual integer value for the size. - -|Integer|PaperSize member| -|-------------|----------------------| -|1|| -|2|| -|3|| -|4|| -|5|| -|6|| -|7|| -|8|| -|9|| -|10|| -|11|| -|12|| -|13|| -|14|| -|15|| -|16|| -|17|| -|18|| -|19|| -|20|| -|21|| -|22|| -|23|| -|24|| -|25|| -|26|| -|27|| -|28|| -|29|| -|30|| -|31|| -|32|| -|33|| -|34|| -|35|| -|36|| -|37|| -|38|| -|39|| -|40|| -|41|| -|42|| -|43|| -|44|| -|45|| -|46|| -|47|| -|50|| -|51|| -|52|| -|53|| -|54|| -|55|| -|56|| -|57|| -|58|| -|59|| -|60|| -|61|| -|62|| -|63|| -|64|| -|65|| -|66|| -|67|| -|68|| -|69|| -|70|| -|71|| -|72|| -|73|| -|74|| -|75|| -|76|| -|77|| -|78|| -|79|| -|80|| -|81|| -|82|| -|83|| -|84|| -|85|| -|86|| -|87|| -|88|| -|89|| -|90|| -|91|| -|92|| -|93|| -|94|| -|95|| -|96|| -|97|| -|98|| -|99|| -|100|| -|101|| -|102|| -|103|| -|104|| -|105|| -|106|| -|107|| -|108|| -|109|| -|110|| -|111|| -|112|| -|113|| -|114|| -|115|| -|116|| -|117|| -|118|| -|Greater than 118|A custom paper size| - + enumeration members. A value equal to 48 or 49 or larger than 118 indicates a custom paper size; however, the property will return the actual integer value for the size. + +|Integer|PaperSize member| +|-------------|----------------------| +|1|| +|2|| +|3|| +|4|| +|5|| +|6|| +|7|| +|8|| +|9|| +|10|| +|11|| +|12|| +|13|| +|14|| +|15|| +|16|| +|17|| +|18|| +|19|| +|20|| +|21|| +|22|| +|23|| +|24|| +|25|| +|26|| +|27|| +|28|| +|29|| +|30|| +|31|| +|32|| +|33|| +|34|| +|35|| +|36|| +|37|| +|38|| +|39|| +|40|| +|41|| +|42|| +|43|| +|44|| +|45|| +|46|| +|47|| +|50|| +|51|| +|52|| +|53|| +|54|| +|55|| +|56|| +|57|| +|58|| +|59|| +|60|| +|61|| +|62|| +|63|| +|64|| +|65|| +|66|| +|67|| +|68|| +|69|| +|70|| +|71|| +|72|| +|73|| +|74|| +|75|| +|76|| +|77|| +|78|| +|79|| +|80|| +|81|| +|82|| +|83|| +|84|| +|85|| +|86|| +|87|| +|88|| +|89|| +|90|| +|91|| +|92|| +|93|| +|94|| +|95|| +|96|| +|97|| +|98|| +|99|| +|100|| +|101|| +|102|| +|103|| +|104|| +|105|| +|106|| +|107|| +|108|| +|109|| +|110|| +|111|| +|112|| +|113|| +|114|| +|115|| +|116|| +|117|| +|118|| +|Greater than 118|A custom paper size| + ]]> @@ -579,11 +579,11 @@ Gets or sets the width of the paper, in hundredths of an inch. The width of the paper, in hundredths of an inch. - and property values can be set only for custom objects. - + and property values can be set only for custom objects. + ]]> The property is not set to . diff --git a/xml/System.Drawing.Printing/PaperSource.xml b/xml/System.Drawing.Printing/PaperSource.xml index f0b466cb412..3b735e2a000 100644 --- a/xml/System.Drawing.Printing/PaperSource.xml +++ b/xml/System.Drawing.Printing/PaperSource.xml @@ -46,22 +46,22 @@ Specifies the paper tray from which the printer gets paper. - and properties to get the paper source trays that are available on the printer and to set the paper source for a page, respectively. - - For more information about printing, see the namespace overview. - - - -## Examples - The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. - + and properties to get the paper source trays that are available on the printer and to set the paper source for a page, respectively. + + For more information about printing, see the namespace overview. + + + +## Examples + The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet2"::: + ]]> @@ -99,16 +99,16 @@ Initializes a new instance of the class. - class. - -|Property|Initial value| -|--------------|-------------------| -||| -||| - + class. + +|Property|Initial value| +|--------------|-------------------| +||| +||| + ]]> @@ -191,28 +191,28 @@ Gets or sets the integer representing one of the values or a custom value. The integer value representing one of the values or a custom value. - member. Anything larger than 256 maps to in the enumeration, but the property returns the actual integer value. - -|Integer value|PaperSourceKind member| -|-------------------|----------------------------| -|1|| -|2|| -|3|| -|4|| -|5|| -|6|| -|7|| -|8|| -|9|| -|10|| -|11|| -|14|| -|15|| -|256 or larger|| - + member. Anything larger than 256 maps to in the enumeration, but the property returns the actual integer value. + +|Integer value|PaperSourceKind member| +|-------------------|----------------------------| +|1|| +|2|| +|3|| +|4|| +|5|| +|6|| +|7|| +|8|| +|9|| +|10|| +|11|| +|14|| +|15|| +|256 or larger|| + ]]> @@ -264,20 +264,20 @@ Gets or sets the name of the paper source. The name of the paper source. - property. - - - -## Examples - The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. - + property. + + + +## Examples + The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.Drawing.Printing/PaperSourceKind.xml b/xml/System.Drawing.Printing/PaperSourceKind.xml index d0d00ce8d7d..2a7dd87845e 100644 --- a/xml/System.Drawing.Printing/PaperSourceKind.xml +++ b/xml/System.Drawing.Printing/PaperSourceKind.xml @@ -41,13 +41,13 @@ Standard paper sources. - property. - - For more information on printing, see the namespace overview. - + property. + + For more information on printing, see the namespace overview. + ]]> diff --git a/xml/System.Drawing.Printing/PreviewPrintController.xml b/xml/System.Drawing.Printing/PreviewPrintController.xml index 1652524208e..5d53588f7b7 100644 --- a/xml/System.Drawing.Printing/PreviewPrintController.xml +++ b/xml/System.Drawing.Printing/PreviewPrintController.xml @@ -41,17 +41,17 @@ Specifies a print controller that displays a document on a screen as a series of images. - or class and set its property. The is used by the and classes, though you can use the when managing the display of your own print preview window. - - When used with a or , sets the of the associated to a , performs the print preview, and sets the back to the original value. - - creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. - - For more information about printing, see the namespace overview. - + or class and set its property. The is used by the and classes, though you can use the when managing the display of your own print preview window. + + When used with a or , sets the of the associated to a , performs the print preview, and sets the back to the original value. + + creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + + For more information about printing, see the namespace overview. + ]]> @@ -122,11 +122,11 @@ Captures the pages of a document as a series of images. An array of type that contains the pages of a as a series of images. - image representation contained in a to implement your own print preview form. - + image representation contained in a to implement your own print preview form. + ]]> @@ -206,13 +206,13 @@ A that contains data about how to preview a page in the print document. Completes the control sequence that determines when and how to preview a page in a print document. - is called immediately after the raises the event. If an exception is thrown inside a event of a , this method is not called. - - creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. - + is called immediately after the raises the event. If an exception is thrown inside a event of a , this method is not called. + + creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + ]]> @@ -261,13 +261,13 @@ A that contains data about how to preview the print document. Completes the control sequence that determines when and how to preview a print document. - raises the event. Even if an uncaught exception was thrown during the print preview process, is called. - - creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. - + raises the event. Even if an uncaught exception was thrown during the print preview process, is called. + + creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + ]]> @@ -316,16 +316,16 @@ Begins the control sequence that determines when and how to preview a page in a print document. A that represents a page from a . - is called immediately before raises the event. - - creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. - + is called immediately before raises the event. + + creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + > [!NOTE] -> Anti-aliasing, also known as gray scaling, makes the print preview look better. However, the use of anti-aliasing can slow down the rendering speed. For more information about anti-aliasing, see the property. - +> Anti-aliasing, also known as gray scaling, makes the print preview look better. However, the use of anti-aliasing can slow down the rendering speed. For more information about anti-aliasing, see the property. + ]]> @@ -372,15 +372,15 @@ A that contains data about how to print the document. Begins the control sequence that determines when and how to preview a print document. - is called immediately after raises the event. - - creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. - - verifies that the printer settings are valid. - + is called immediately after raises the event. + + creates the that is displayed during the print preview. After is called, the method sets the to a graphic of a single page. The method clears the , while the method deallocates the object. + + verifies that the printer settings are valid. + ]]> The printer named in the property does not exist. @@ -435,14 +435,14 @@ if the print preview uses anti-aliasing; otherwise, . The default is . - [!NOTE] -> While using anti-aliasing makes the print preview look better, it can slow down the rendering speed. - +> While using anti-aliasing makes the print preview look better, it can slow down the rendering speed. + ]]> diff --git a/xml/System.Drawing.Printing/PrintDocument.xml b/xml/System.Drawing.Printing/PrintDocument.xml index 8fa3b5e556c..2faa25e9be2 100644 --- a/xml/System.Drawing.Printing/PrintDocument.xml +++ b/xml/System.Drawing.Printing/PrintDocument.xml @@ -226,12 +226,12 @@ property. For example, the property specifies whether the page prints in color, the property specifies landscape or portrait orientation, and the property specifies the margins of the page. + You can specify several default page settings through the property. For example, the property specifies whether the page prints in color, the property specifies landscape or portrait orientation, and the property specifies the margins of the page. To specify settings on a page-by-page basis, handle the or event and modify the argument included in the or , respectively. > [!NOTE] -> After printing has started, changes to page settings through the property will not affect pages being printed. +> After printing has started, changes to page settings through the property will not affect pages being printed. @@ -297,7 +297,7 @@ property does not specify the file to print. Rather, you specify the output to print by handling the event. For an example, see the class overview. + The property does not specify the file to print. Rather, you specify the output to print by handling the event. For an example, see the class overview. @@ -353,7 +353,7 @@ ## Remarks Typically, you handle the event to release fonts, file streams, and other resources used during the printing process, like fonts. - You indicate that there are no more pages to print by setting the property to `false` in the event. The event also occurs if the printing process is canceled or an exception occurs during the printing process. + You indicate that there are no more pages to print by setting the property to `false` in the event. The event also occurs if the printing process is canceled or an exception occurs during the printing process. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs. For more information about handling events with delegates, see [Handling and Raising Events](/dotnet/standard/events/). @@ -641,7 +641,7 @@ object origin. When is `true`, the object location takes into account the property value and the printable area of the page. When is `false`, only the printable area of the page is used to determine the location of the object origin, the value is ignored. + Calculating the area available to print requires knowing the physical size of the paper, the margins for the page, and the location of the object origin. When is `true`, the object location takes into account the property value and the printable area of the page. When is `false`, only the printable area of the page is used to determine the location of the object origin, the value is ignored. For example, if is `true`, and is set for 1 inch on each side, the object included in the is located 1 inch from the left and top of the page. If the printable area of the page is .25 of an inch on each side and is `false`, the object is located .25 of an inch from the left and top of the page. @@ -690,7 +690,7 @@ ## Remarks Specify the output to print by handling the event and by using the included in the . - Use the property to specify which printer should print the document. + Use the property to specify which printer should print the document. The method prints the document without using a print dialog. Use a when you want to offer the user the ability to choose print settings. @@ -767,7 +767,7 @@ ## Examples - The following code example requires that you have created an instance of the class that is named `myPrintDocument`. The example creates a new instance of the class, assigns it to the property of `myPrintDocument`, and prints the document. + The following code example requires that you have created an instance of the class that is named `myPrintDocument`. The example creates a new instance of the class, assigns it to the property of `myPrintDocument`, and prints the document. Use the and namespaces for this example. @@ -836,7 +836,7 @@ property. For example, use the property to specify the number of copies you want to print, the property to specify the printer to use, and the property to specify the range of pages you want to print. + You can specify several printer settings through the property. For example, use the property to specify the number of copies you want to print, the property to specify the printer to use, and the property to specify the range of pages you want to print. @@ -892,9 +892,9 @@ property of the . For example, to specify a line of text that should be printed, draw the text using the method. + To specify the output to print, use the property of the . For example, to specify a line of text that should be printed, draw the text using the method. - In addition to specifying the output, you can indicate if there are additional pages to print by setting the property to `true`. The default is `false`, which indicates that there are no more pages to print. Individual page settings can also be modified through the and the print job can be canceled by setting the property to `true`. To print each page of a document using different page settings, handle the event. + In addition to specifying the output, you can indicate if there are additional pages to print by setting the property to `true`. The default is `false`, which indicates that there are no more pages to print. Individual page settings can also be modified through the and the print job can be canceled by setting the property to `true`. To print each page of a document using different page settings, handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs. For more information about handling events with delegates, see [Handling and Raising Events](/dotnet/standard/events/). @@ -956,7 +956,7 @@ property or by setting the property to a . Changes made to the affect only the current page, not the document's default page settings. The print job can also be canceled by setting the property to `true` for the . + It is possible to print each page of a document using different page settings. You set page settings by modifying individual properties of the property or by setting the property to a . Changes made to the affect only the current page, not the document's default page settings. The print job can also be canceled by setting the property to `true` for the . To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs. For more information about handling events with delegates, see [Handling and Raising Events](/dotnet/standard/events/). diff --git a/xml/System.Drawing.Printing/PrintPageEventArgs.xml b/xml/System.Drawing.Printing/PrintPageEventArgs.xml index cdf0ae881d6..715eaa21a5b 100644 --- a/xml/System.Drawing.Printing/PrintPageEventArgs.xml +++ b/xml/System.Drawing.Printing/PrintPageEventArgs.xml @@ -47,7 +47,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] - The property retrieves the rectangular area that represents the portion of the page between the margins. The property retrieves the rectangular area that represents the total area of the page. The property defines the graphics object with which to do the painting. The property retrieves the printer settings for the current page. The remaining properties indicate whether a print job should be canceled or whether a print job has more pages. + The property retrieves the rectangular area that represents the portion of the page between the margins. The property retrieves the rectangular area that represents the total area of the page. The property defines the graphics object with which to do the painting. The property retrieves the printer settings for the current page. The remaining properties indicate whether a print job should be canceled or whether a print job has more pages. For more information about printing with Windows Forms, see the namespace overview. If you wish to print from a Windows Presentation Foundation application, see the namespace. diff --git a/xml/System.Drawing.Printing/PrinterResolution.xml b/xml/System.Drawing.Printing/PrinterResolution.xml index 0e2082746c4..43cc236a9db 100644 --- a/xml/System.Drawing.Printing/PrinterResolution.xml +++ b/xml/System.Drawing.Printing/PrinterResolution.xml @@ -42,24 +42,24 @@ Represents the resolution supported by a printer. - and properties to get the printer resolutions that are available on the printer and to set the printing resolution for a page, respectively. - - Use the property to determine whether the printer resolution type is the value . If so, use the and properties to determine the printer resolution in the horizontal and vertical directions, respectively. - - For more information on printing, see the namespace overview. - - - -## Examples - The following code example populates the `comboPrintResolution` combo box with the supported resolutions. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. - + and properties to get the printer resolutions that are available on the printer and to set the printing resolution for a page, respectively. + + Use the property to determine whether the printer resolution type is the value . If so, use the and properties to determine the printer resolution in the horizontal and vertical directions, respectively. + + For more information on printing, see the namespace overview. + + + +## Examples + The following code example populates the `comboPrintResolution` combo box with the supported resolutions. The example assumes that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet3"::: + ]]> @@ -96,15 +96,15 @@ Initializes a new instance of the class. - class. - -|Property|Initial Value| -|--------------|-------------------| -||| - + class. + +|Property|Initial Value| +|--------------|-------------------| +||| + ]]> @@ -239,13 +239,13 @@ Gets the horizontal printer resolution, in dots per inch. The horizontal printer resolution, in dots per inch, if is set to ; otherwise, a value. - property contains the value `DMRES_HIGH` if is set to , `DMRES_MEDIUM` if is set to , `DMRES_LOW` if is set to , and `DMRES_DRAFT` if is set to . - - For more information, see [DEVMODE structure](/windows/win32/api/wingdi/ns-wingdi-devmodea). - + property contains the value `DMRES_HIGH` if is set to , `DMRES_MEDIUM` if is set to , `DMRES_LOW` if is set to , and `DMRES_DRAFT` if is set to . + + For more information, see [DEVMODE structure](/windows/win32/api/wingdi/ns-wingdi-devmodea). + ]]> @@ -298,11 +298,11 @@ Gets the vertical printer resolution, in dots per inch. The vertical printer resolution, in dots per inch. - property is not set to , the default value of the property is -1. - + property is not set to , the default value of the property is -1. + ]]> diff --git a/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml index 19a7913832b..851ca63e0f8 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+PaperSizeCollection.xml @@ -48,24 +48,24 @@ Contains a collection of objects. - contains instances that represents the paper sizes through the property, which contains one of the values. - - Typically, you set a page's paper size through the property to a valid instance available through the collection. - - See the constructor to find out how you can specify a custom paper size. - - - -## Examples - The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. - + contains instances that represents the paper sizes through the property, which contains one of the values. + + Typically, you set a page's paper size through the property to a valid instance available through the collection. + + See the constructor to find out how you can specify a custom paper size. + + + +## Examples + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: + ]]> @@ -237,15 +237,15 @@ Gets the number of different paper sizes in the collection. The number of different paper sizes in the collection. - is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. - + is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: + ]]> @@ -284,15 +284,15 @@ Returns an enumerator that can iterate through the collection. An for the . - or to throw an exception. - - Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. - - Removing objects from the enumerator also removes them from the collection. - + or to throw an exception. + + Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. + + Removing objects from the enumerator also removes them from the collection. + ]]> @@ -335,15 +335,15 @@ Gets the at a specified index. The at the specified index. - is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. - + is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet1"::: + ]]> @@ -390,11 +390,11 @@ The index at which to start copying items. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -440,11 +440,11 @@ For a description of this member, see . The number of elements contained in the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -485,11 +485,11 @@ if access to the is synchronized (thread safe); otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -529,11 +529,11 @@ For a description of this member, see . An object that can be used to synchronize access to the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -581,11 +581,11 @@ For a description of this member, see . An enumerator associated with the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml index 72682eb423f..555ff14c386 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+PaperSourceCollection.xml @@ -48,22 +48,22 @@ Contains a collection of objects. - contains instances that represents the paper source trays through the property, which contains one of the values. - - Typically, you set a page's paper source through the property to a valid instance available through the collection. - - - -## Examples - The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. - + contains instances that represents the paper source trays through the property, which contains one of the values. + + Typically, you set a page's paper source through the property to a valid instance available through the collection. + + + +## Examples + The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet2"::: + ]]> @@ -235,15 +235,15 @@ Gets the number of different paper sources in the collection. The number of different paper sources in the collection. - is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. - + is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet2"::: + ]]> @@ -282,15 +282,15 @@ Returns an enumerator that can iterate through the collection. An for the . - or to throw an exception. - - Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. - - Removing objects from the enumerator also removes them from the collection. - + or to throw an exception. + + Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. + + Removing objects from the enumerator also removes them from the collection. + ]]> @@ -333,15 +333,15 @@ Gets the at a specified index. The at the specified index. - is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. - + is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet2"::: + ]]> @@ -388,11 +388,11 @@ The index at which to start the copy operation. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -438,11 +438,11 @@ For a description of this member, see . The number of elements contained in the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -483,11 +483,11 @@ if access to the is synchronized (thread safe); otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -527,11 +527,11 @@ For a description of this member, see . An object that can be used to synchronize access to the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -579,11 +579,11 @@ For a description of this member, see . An object that can be used to iterate through the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml index 39686860bf5..32fff7f3897 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+PrinterResolutionCollection.xml @@ -48,24 +48,24 @@ Contains a collection of objects. - contains instances that represents the printer resolutions supported through the property, which contains one of the values. - - Typically, you set the printer's resolution through the property to a valid instance available through the collection. - - If is `Custom`, then use the and properties to determine the custom printer resolution in the horizontal and vertical directions, respectively. - - - -## Examples - The following code example populates the `comboPrintResolution` combo box with the supported resolutions. The example requires that a variable named `printDoc` exists and that the specific combo box exists. - + contains instances that represents the printer resolutions supported through the property, which contains one of the values. + + Typically, you set the printer's resolution through the property to a valid instance available through the collection. + + If is `Custom`, then use the and properties to determine the custom printer resolution in the horizontal and vertical directions, respectively. + + + +## Examples + The following code example populates the `comboPrintResolution` combo box with the supported resolutions. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet3"::: + ]]> @@ -236,15 +236,15 @@ Gets the number of available printer resolutions in the collection. The number of available printer resolutions in the collection. - variable named `printDoc` exists and that the specific combo box exists. - + variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet3"::: + ]]> @@ -283,15 +283,15 @@ Returns an enumerator that can iterate through the collection. An for the . - or to throw an exception. - - Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. - - Removing objects from the enumerator also removes them from the collection. - + or to throw an exception. + + Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. + + Removing objects from the enumerator also removes them from the collection. + ]]> @@ -334,15 +334,15 @@ Gets the at a specified index. The at the specified index. - variable named `printDoc` exists and that the specific combo box exists. - + variable named `printDoc` exists and that the specific combo box exists. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet3"::: + ]]> @@ -389,11 +389,11 @@ The index at which to start the copy operation. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -439,11 +439,11 @@ For a description of this member, see . The number of elements contained in the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -484,11 +484,11 @@ if access to the is synchronized (thread safe); otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -528,11 +528,11 @@ For a description of this member, see . An object that can be used to synchronize access to the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -580,11 +580,11 @@ For a description of this member, see . An object that can be used to iterate through the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml b/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml index 3998eed5755..a6f187362d1 100644 --- a/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml +++ b/xml/System.Drawing.Printing/PrinterSettings+StringCollection.xml @@ -56,11 +56,11 @@ Contains a collection of objects. - property, which indicates the names of printers installed on a computer, is a . - + property, which indicates the names of printers installed on a computer, is a . + ]]> @@ -268,15 +268,15 @@ Returns an enumerator that can iterate through the collection. An for the . - or to throw an exception. - - Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. - - Removing objects from the enumerator also removes them from the collection. - + or to throw an exception. + + Two enumerators instantiated from the same collection at the same time can contain different snapshots of the collection. + + Removing objects from the enumerator also removes them from the collection. + ]]> @@ -392,11 +392,11 @@ The starting index. For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -443,11 +443,11 @@ For a description of this member, see . The number of elements contained in the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -488,11 +488,11 @@ if access to the is synchronized (thread safe); otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -532,11 +532,11 @@ For a description of this member, see . An object that can be used to synchronize access to the . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -584,11 +584,11 @@ For a description of this member, see . An enumerator that can be used to iterate through the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Drawing.Printing/PrinterSettings.xml b/xml/System.Drawing.Printing/PrinterSettings.xml index ec53bb6a1cc..f1bf954e12f 100644 --- a/xml/System.Drawing.Printing/PrinterSettings.xml +++ b/xml/System.Drawing.Printing/PrinterSettings.xml @@ -249,7 +249,7 @@ property to specify the number of copies to print. + Collating is performed only when the number of copies is greater than 1. Set the property to specify the number of copies to print. Setting to `true` will print a complete copy of the document before the first page of the next copy is printed. `false` will print each page by the number of copies specified before printing the next page. @@ -297,7 +297,7 @@ property to determine the maximum number of copies the printer supports. If the number of copies is set higher than the maximum copies supported by the printer, only the maximum number of copies will be printed, and no exception will occur. + Not all printers support printing multiple copes. You can use the property to determine the maximum number of copies the printer supports. If the number of copies is set higher than the maximum copies supported by the printer, only the maximum number of copies will be printed, and no exception will occur. > [!NOTE] > Some printers might not support printing more than one copy at a time. @@ -597,7 +597,7 @@ property to check to see if the printer supports duplex printing. + You can use the property to check to see if the printer supports duplex printing. ]]> @@ -655,7 +655,7 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the requires the and to be specified and the value to be within that range. + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the requires the and to be specified and the value to be within that range. During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. @@ -858,7 +858,7 @@ ## Examples - The following code example populates the `comboInstalledPrinters` combo box with the installed printers and also sets the printer to print, using the property, when the selection changes. The `PopulateInstalledPrintersCombo` routine is called when the form is being initialized. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboInstalledPrinters` combo box with the installed printers and also sets the printer to print, using the property, when the selection changes. The `PopulateInstalledPrintersCombo` routine is called when the form is being initialized. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet5"::: @@ -907,12 +907,12 @@ always returns `false` when you explicitly set the property to a string value other than `null`. + always returns `false` when you explicitly set the property to a string value other than `null`. ## Examples - The following example demonstrates how to use the property. To run this example, paste the following code into a form and call `PopulateInstalledPrintersCombo` from the form's constructor or event-handling method. + The following example demonstrates how to use the property. To run this example, paste the following code into a form and call `PopulateInstalledPrintersCombo` from the form's constructor or event-handling method. :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PrinterSettings/IsDefaultPrinter/Form1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PrinterSettings/IsDefaultPrinter/Form1.vb" id="Snippet1"::: @@ -1090,12 +1090,12 @@ property after setting the to safely determine if the printer is valid. + When you get or set some properties, a valid printer is required or else an exception is raised. To avoid exceptions, use the property after setting the to safely determine if the printer is valid. ## Examples - The following code example specifies the target printer by setting the property, and if the is `true`, prints the document on the specified printer. The example has three prerequisites: + The following code example specifies the target printer by setting the property, and if the is `true`, prints the document on the specified printer. The example has three prerequisites: - A variable named `filePath` has been set to the path of the file to print. @@ -1150,7 +1150,7 @@ property to `true` to print a page in landscape format. + Valid rotation values are 90 and 270 degrees. If landscape is not supported, the only valid rotation value is 0 degrees. You set the property to `true` to print a page in landscape format. ]]> @@ -1194,7 +1194,7 @@ property to the number of copies to print. Use the property to determine if your printer supports printing multiple copies at a time, because some printers do not. + Set the property to the number of copies to print. Use the property to determine if your printer supports printing multiple copies at a time, because some printers do not. ]]> @@ -1243,7 +1243,7 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . ]]> @@ -1296,7 +1296,7 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. When setting the or values programmatically, ensure that they are within the range defined by the and properties, or an exception is thrown when displaying the . ]]> @@ -1343,16 +1343,16 @@ contains instances that represent the paper sizes through the property, which contains one of the values. + The contains instances that represent the paper sizes through the property, which contains one of the values. - Typically, you set a page's paper size through the property to a valid available through the collection. + Typically, you set a page's paper size through the property to a valid available through the collection. To specify a custom paper size, see the constructor. ## Examples - The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSize` combo box with the printer's supported paper sizes. In addition, a custom paper size is created and added to the combo box. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet1"::: @@ -1404,14 +1404,14 @@ contains instances that represent the paper source trays through the property, which contains one of the values. + The contains instances that represent the paper source trays through the property, which contains one of the values. - Typically, you set a page's paper source through the property to a valid available through the collection. + Typically, you set a page's paper source through the property to a valid available through the collection. ## Examples - The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. + The following code example populates the `comboPaperSource` combo box with the printer's supported paper sources. The is identified as the property that provides the display string for the item being added through the property of the combo box. The example requires that a variable named `printDoc` exists and that the specific combo box exists. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet2"::: @@ -1465,12 +1465,12 @@ ## Remarks After setting the printer name, call to determine if the printer name is recognized as a valid printer on the system. - You can also use the property to get a list of printers installed on the system. + You can also use the property to get a list of printers installed on the system. ## Examples - The following code example specifies the target printer by setting the property, and if the is `true`, prints the document on the specified printer. The example has three prerequisites: + The following code example specifies the target printer by setting the property, and if the is `true`, prints the document on the specified printer. The example has three prerequisites: - A variable named `filePath` has been set to the path of the file to print. @@ -1528,9 +1528,9 @@ contains instances that represent the printer resolutions supported through the property, which contains one of the values. + The contains instances that represent the printer resolutions supported through the property, which contains one of the values. - Typically, you set a page's paper source through the property to a valid available through the collection. + Typically, you set a page's paper source through the property to a valid available through the collection. If is `Custom`, then use the and properties to determine the custom printer resolution in the horizontal and vertical directions, respectively. @@ -1628,7 +1628,7 @@ property is used by the .when the user selects a print range. The default is `AllPages`. To enable the user to specify a range of pages to print, the property must be set to `true`. To enable the user to specify the selected pages to print, the property must be set to `true`. + The property is used by the .when the user selects a print range. The default is `AllPages`. To enable the user to specify a range of pages to print, the property must be set to `true`. To enable the user to specify the selected pages to print, the property must be set to `true`. During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. @@ -1691,10 +1691,10 @@ property is used by the when the user selects the **Print to file** option. In such a case, the output port is set to "FILE," causing the Windows printing subsystem to prompt the user for a file name when the method is called. + The property is used by the when the user selects the **Print to file** option. In such a case, the output port is set to "FILE," causing the Windows printing subsystem to prompt the user for a file name when the method is called. > [!NOTE] -> The property is only used by the and cannot be set programmatically. The `Print to file` option only appears on the when the property is set to `true`. +> The property is only used by the and cannot be set programmatically. The `Print to file` option only appears on the when the property is set to `true`. ]]> @@ -1883,7 +1883,7 @@ and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the also requires the and to be specified and the value to be within that range. + The and properties are used by the when the user selects a print range. The property must be set to `true` to enable the user to specify a print range. In addition, the also requires the and to be specified and the value to be within that range. During the printing process, in the event, view the to determine what should be printed. If is , use the and properties to determine what pages should be printed. If is , then specify output only for the selected pages. diff --git a/xml/System.Drawing.Printing/QueryPageSettingsEventArgs.xml b/xml/System.Drawing.Printing/QueryPageSettingsEventArgs.xml index 5c59479e23e..68a6ec5c291 100644 --- a/xml/System.Drawing.Printing/QueryPageSettingsEventArgs.xml +++ b/xml/System.Drawing.Printing/QueryPageSettingsEventArgs.xml @@ -41,22 +41,22 @@ Provides data for the event. - property or by setting the property to a . The print job can also be canceled by setting the property to `true`. - - - -## Examples - The following code example prints a document with the first page in color, if the printer supports it. The example assumes that a variable named `printDoc` has been created, and the and events are handled. - - Use the and namespaces for this example. - + property or by setting the property to a . The print job can also be canceled by setting the property to `true`. + + + +## Examples + The following code example prints a document with the first page in color, if the printer supports it. The example assumes that a variable named `printDoc` has been created, and the and events are handled. + + Use the and namespaces for this example. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet6"::: + ]]> @@ -145,22 +145,22 @@ Gets or sets the page settings for the page to be printed. The page settings for the page to be printed. - property or by setting the property to a . The print job can also be canceled by setting the property to `true`. - - - -## Examples - The following code example prints a document with the first page in color, if the printer supports it. The example assumes that a variable named `printDoc` has been created, and the and events are handled. - - Use the and namespaces for this example. - + property or by setting the property to a . The print job can also be canceled by setting the property to `true`. + + + +## Examples + The following code example prints a document with the first page in color, if the printer supports it. The example assumes that a variable named `printDoc` has been created, and the and events are handled. + + Use the and namespaces for this example. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/PaperSource and PaperSize Example with Resolution/CPP/source.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing.Printing/PageSettings/Color/source.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing.Printing/PageSettings/Color/source.vb" id="Snippet6"::: + ]]> diff --git a/xml/System.Drawing.Text/FontCollection.xml b/xml/System.Drawing.Text/FontCollection.xml index 3fd60a7f408..1398f8314fc 100644 --- a/xml/System.Drawing.Text/FontCollection.xml +++ b/xml/System.Drawing.Text/FontCollection.xml @@ -42,7 +42,7 @@ allows you to get a list of the font families contained in the collection with its property. For additional information on fonts and text, including example code, see [Using Fonts and Text](/dotnet/framework/winforms/advanced/using-fonts-and-text). + The allows you to get a list of the font families contained in the collection with its property. For additional information on fonts and text, including example code, see [Using Fonts and Text](/dotnet/framework/winforms/advanced/using-fonts-and-text). [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] diff --git a/xml/System.Drawing.Text/InstalledFontCollection.xml b/xml/System.Drawing.Text/InstalledFontCollection.xml index 80308fd88a2..885a0eb4733 100644 --- a/xml/System.Drawing.Text/InstalledFontCollection.xml +++ b/xml/System.Drawing.Text/InstalledFontCollection.xml @@ -44,7 +44,7 @@ allows you to get a list of fonts families that are installed on the computer running the application with its property. For additional information on fonts and text, including example code, see [Using Fonts and Text](/dotnet/framework/winforms/advanced/using-fonts-and-text). + The allows you to get a list of fonts families that are installed on the computer running the application with its property. For additional information on fonts and text, including example code, see [Using Fonts and Text](/dotnet/framework/winforms/advanced/using-fonts-and-text). Do not use the class to install a font to Windows. Instead use the GDI `AddFontResource` function. An object sees only fonts that are installed in Windows before the object is created. diff --git a/xml/System.Drawing.Text/PrivateFontCollection.xml b/xml/System.Drawing.Text/PrivateFontCollection.xml index 7f6744e4149..bea130d57cf 100644 --- a/xml/System.Drawing.Text/PrivateFontCollection.xml +++ b/xml/System.Drawing.Text/PrivateFontCollection.xml @@ -176,7 +176,7 @@ method, passing `true`, to set GDI+ rendering on the application, or on individual controls by setting the control's property to `true`. Some controls cannot be rendered with GDI+. + To use the memory font, text on a control must be rendered with GDI+. Use the method, passing `true`, to set GDI+ rendering on the application, or on individual controls by setting the control's property to `true`. Some controls cannot be rendered with GDI+. ]]> diff --git a/xml/System.Drawing/Bitmap.xml b/xml/System.Drawing/Bitmap.xml index a26ae79af0e..5227e9d89c0 100644 --- a/xml/System.Drawing/Bitmap.xml +++ b/xml/System.Drawing/Bitmap.xml @@ -437,7 +437,7 @@ ## Examples - The following code example demonstrates how to construct a new bitmap from a file. The example uses the and methods to recolor the image. It also uses the property. + The following code example demonstrates how to construct a new bitmap from a file. The example uses the and methods to recolor the image. It also uses the property. This example is designed to be used with a Windows Form that contains a , and named `Label1`, `PictureBox1` and `Button1`, respectively. Paste the code into the form and associate the `Button1_Click` method with the button's event. diff --git a/xml/System.Drawing/BufferedGraphics.xml b/xml/System.Drawing/BufferedGraphics.xml index a381f927751..6d75a7c05c3 100644 --- a/xml/System.Drawing/BufferedGraphics.xml +++ b/xml/System.Drawing/BufferedGraphics.xml @@ -56,9 +56,9 @@ > [!NOTE] > The simplest way to use double buffering is to set the control style flag on a control using the method. Setting the flag for a control redirects all painting for the control through a default graphics buffer, without requiring any additional code. This flag is set to `true` by default. - The class has no public constructor and must be created by the for an application domain using its method. You can retrieve the for the current application domain from the static property. + The class has no public constructor and must be created by the for an application domain using its method. You can retrieve the for the current application domain from the static property. - The property can be used for drawing to the graphics buffer. This property provides access to the object that draws to the graphics buffer allocated for this object. + The property can be used for drawing to the graphics buffer. This property provides access to the object that draws to the graphics buffer allocated for this object. The method with no arguments draws the contents of the graphics buffer to the surface specified when the buffer was allocated. Other overloads of the method allow you to specify a object or an object that points to a device context to which to draw the contents of the graphics buffer. diff --git a/xml/System.Drawing/BufferedGraphicsContext.xml b/xml/System.Drawing/BufferedGraphicsContext.xml index 1b69bb18e9e..ec1d0c17be2 100644 --- a/xml/System.Drawing/BufferedGraphicsContext.xml +++ b/xml/System.Drawing/BufferedGraphicsContext.xml @@ -56,7 +56,7 @@ The class provides methods for creating and configuring a graphics buffer. The method creates a , which is a wrapper for a graphics buffer that also provides methods you can use to write to the buffer and render its contents to an output device. - You can retrieve the for the current application domain from the static property. For graphically intensive applications such as animation, you can create a dedicated using the constructor, but for most applications the property will be sufficient. + You can retrieve the for the current application domain from the static property. For graphically intensive applications such as animation, you can create a dedicated using the constructor, but for most applications the property will be sufficient. For more information on drawing buffered graphics and custom buffering implementations, see [Double Buffered Graphics](/dotnet/framework/winforms/advanced/double-buffered-graphics) and [How to: Manually Manage Buffered Graphics](/dotnet/framework/winforms/advanced/how-to-manually-manage-buffered-graphics). @@ -169,7 +169,7 @@ method with a rectangle whose size exceeds the value of the property, a temporary is created to allocate the buffer and provide a temporary context for the buffer. The new is distinct from the for the application domain and it is disposed automatically when the returned by the method is disposed. + When you call the method with a rectangle whose size exceeds the value of the property, a temporary is created to allocate the buffer and provide a temporary context for the buffer. The new is distinct from the for the application domain and it is disposed automatically when the returned by the method is disposed. @@ -229,7 +229,7 @@ method with a rectangle whose size exceeds the value of the property, a temporary is created to allocate the buffer and provide a temporary context for the buffer. The new is distinct from the for the application domain and it is disposed automatically when the returned by the method is disposed. + When you call the method with a rectangle whose size exceeds the value of the property, a temporary is created to allocate the buffer and provide a temporary context for the buffer. The new is distinct from the for the application domain and it is disposed automatically when the returned by the method is disposed. diff --git a/xml/System.Drawing/BufferedGraphicsManager.xml b/xml/System.Drawing/BufferedGraphicsManager.xml index e7a51f52b73..ea3a768ae7c 100644 --- a/xml/System.Drawing/BufferedGraphicsManager.xml +++ b/xml/System.Drawing/BufferedGraphicsManager.xml @@ -45,26 +45,26 @@ Provides access to the main buffered graphics context object for the application domain. - class allows you to implement custom double buffering for your graphics. Graphics that use double buffering can reduce or eliminate flicker that is caused by redrawing a display surface. - - This class has one static property, , which returns the main for the current application domain. The class creates instances that can be used to draw buffered graphics. - - The class has no public constructor and must be created by the object for an application domain using its method. You can retrieve the object for the current application domain from the static property. - - For more information on double buffering, see [Double Buffered Graphics](/dotnet/framework/winforms/advanced/double-buffered-graphics), , and . - - - -## Examples - The following code example demonstrates acquiring the for the current application domain. - + class allows you to implement custom double buffering for your graphics. Graphics that use double buffering can reduce or eliminate flicker that is caused by redrawing a display surface. + + This class has one static property, , which returns the main for the current application domain. The class creates instances that can be used to draw buffered graphics. + + The class has no public constructor and must be created by the object for an application domain using its method. You can retrieve the object for the current application domain from the static property. + + For more information on double buffering, see [Double Buffered Graphics](/dotnet/framework/winforms/advanced/double-buffered-graphics), , and . + + + +## Examples + The following code example demonstrates acquiring the for the current application domain. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/BufferingExamples/CPP/bufferingexamples.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/BufferedGraphics/Render/bufferingexamples.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/BufferedGraphics/Render/bufferingexamples.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/BufferedGraphics/Render/bufferingexamples.vb" id="Snippet1"::: + ]]> @@ -110,20 +110,20 @@ Gets the for the current application domain. The for the current application domain. - property always returns the same object. - - - -## Examples - The following code example demonstrates acquiring the for the current application domain. - + property always returns the same object. + + + +## Examples + The following code example demonstrates acquiring the for the current application domain. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/BufferingExamples/CPP/bufferingexamples.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/BufferedGraphics/Render/bufferingexamples.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/BufferedGraphics/Render/bufferingexamples.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/BufferedGraphics/Render/bufferingexamples.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Drawing/Color.xml b/xml/System.Drawing/Color.xml index 6e56862bb49..bd98dffd191 100644 --- a/xml/System.Drawing/Color.xml +++ b/xml/System.Drawing/Color.xml @@ -116,7 +116,7 @@ Named colors are represented by using the properties of the structure. -The color of each pixel is represented as a 32-bit number: 8 bits each for alpha, red, green, and blue (ARGB). Each of the four components is a number from 0 through 255, with 0 representing no intensity and 255 representing full intensity. The alpha component specifies the transparency of the color: 0 is fully transparent, and 255 is fully opaque. To determine the alpha, red, green, or blue component of a color, use the , , , or property, respectively. You can create a custom color by using one of the methods. +The color of each pixel is represented as a 32-bit number: 8 bits each for alpha, red, green, and blue (ARGB). Each of the four components is a number from 0 through 255, with 0 representing no intensity and 255 representing full intensity. The alpha component specifies the transparency of the color: 0 is fully transparent, and 255 is fully opaque. To determine the alpha, red, green, or blue component of a color, use the , , , or property, respectively. You can create a custom color by using one of the methods. For more information about these colors, see [List of colors by name](/uwp/api/windows.ui.colors#remarks). @@ -3798,7 +3798,7 @@ This example is designed to be used with a Windows Form. Paste the code into the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a predefined color. + This property does not do a comparison of the ARGB values. Therefore, when the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a predefined color. ]]> @@ -3850,7 +3850,7 @@ This example is designed to be used with a Windows Form. Paste the code into the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a predefined color. + This property does not do a comparison of the ARGB values. Therefore, when the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a predefined color. ]]> @@ -3901,7 +3901,7 @@ This example is designed to be used with a Windows Form. Paste the code into the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a system color. + This property does not do a comparison of the ARGB values. Therefore, when the property is applied to a structure that is created by using the method, returns `false`, even if the ARGB value matches the ARGB value of a system color. ]]> @@ -5585,7 +5585,7 @@ This example is designed to be used with a Windows Form. Paste the code into the ## Examples - The following code example demonstrates how to use the property. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button2` and associate the `Button2_Click` method with the button's event. + The following code example demonstrates how to use the property. This example is designed to be used with Windows Forms. Paste the code into a form that contains a button named `Button2` and associate the `Button2_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet4"::: @@ -7795,7 +7795,7 @@ This example is designed to be used with a Windows Form. Paste the code into the property. This example is designed to be used with Windows Forms. Paste the code into a form that contains two buttons named `Button1` and `Button2`. Call the `UseTransparentProperty` method in the form's constructor. + The following code example demonstrates how to use the property. This example is designed to be used with Windows Forms. Paste the code into a form that contains two buttons named `Button1` and `Button2`. Call the `UseTransparentProperty` method in the form's constructor. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet2"::: diff --git a/xml/System.Drawing/Font.xml b/xml/System.Drawing/Font.xml index 50165151177..42e874b92e2 100644 --- a/xml/System.Drawing/Font.xml +++ b/xml/System.Drawing/Font.xml @@ -155,7 +155,7 @@ operator, the constructor, and the property. This example is designed to be used with a Windows Form that contains a button named `Button2`. Paste the following code into your form and associate the `Button2_Click` method with the button's event. + The following code example demonstrates the operator, the constructor, and the property. This example is designed to be used with a Windows Form that contains a button named `Button2`. Paste the following code into your form and associate the `Button2_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.CharacterRangeExample/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Overview/form1.cs" id="Snippet3"::: @@ -203,7 +203,7 @@ property set to and its property set to . + The resulting font has its property set to and its property set to . ]]> @@ -249,7 +249,7 @@ property set to and its property set to . Windows Forms applications support TrueType fonts and have limited support for OpenType fonts. If the `familyName` parameter specifies a font that is not installed on the machine running the application or is not supported, Microsoft Sans Serif will be substituted. + The resulting font has its property set to and its property set to . Windows Forms applications support TrueType fonts and have limited support for OpenType fonts. If the `familyName` parameter specifies a font that is not installed on the machine running the application or is not supported, Microsoft Sans Serif will be substituted. @@ -305,7 +305,7 @@ property set to . + The resulting font has its property set to . @@ -364,7 +364,7 @@ property set to . + The resulting font has its property set to . ]]> @@ -414,7 +414,7 @@ property set to . Windows Forms applications support TrueType fonts and have limited support for OpenType fonts. If the `familyName` parameter specifies a font that is not installed on the machine running the application or is not supported, Microsoft Sans Serif will be substituted. + The resulting font has its property set to . Windows Forms applications support TrueType fonts and have limited support for OpenType fonts. If the `familyName` parameter specifies a font that is not installed on the machine running the application or is not supported, Microsoft Sans Serif will be substituted. ]]> @@ -462,7 +462,7 @@ property set to . + The resulting font has its property set to . ]]> @@ -839,7 +839,7 @@ operator, the constructor, and the property. This example is designed to be used with a Windows Form that contains a button named `Button2`. Paste the following code into your form and associate the `Button2_Click` method with the button's event. + The following code example demonstrates the operator, the constructor, and the property. This example is designed to be used with a Windows Form that contains a button named `Button2`. Paste the following code into your form and associate the `Button2_Click` method with the button's event. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.CharacterRangeExample/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Overview/form1.cs" id="Snippet3"::: @@ -1621,7 +1621,7 @@ ## Remarks The line spacing of a is the vertical distance between the base lines of two consecutive lines of text. Thus, the line spacing includes the blank space between lines along with the height of the character itself. - If the property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. For a screen display that has a vertical resolution of 96 dots per inch, you can calculate the height as follows: + If the property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. For a screen display that has a vertical resolution of 96 dots per inch, you can calculate the height as follows: 2355*(0.3/2048)\*96 = 33.11719 @@ -1671,11 +1671,11 @@ ## Remarks The line spacing of a is the vertical distance between the base lines of two consecutive lines of text. Thus, the line spacing includes the blank space between lines along with the height of the character itself. - If the property of the font is set to anything other than , the height, in pixels, is calculated using the vertical resolution of the specified object. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. If the object has a property value of and a property value of 96 dots per inch, the height is calculated as follows: + If the property of the font is set to anything other than , the height, in pixels, is calculated using the vertical resolution of the specified object. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. If the object has a property value of and a property value of 96 dots per inch, the height is calculated as follows: 2355*(0.3/2048)\*96 = 33.1171875 - Continuing with the same example, suppose the property of the object is set to rather than . Then (using 1 inch = 25.4 millimeters) the height, in millimeters, is calculated as follows: + Continuing with the same example, suppose the property of the object is set to rather than . Then (using 1 inch = 25.4 millimeters) the height, in millimeters, is calculated as follows: 2355*(0.3/2048)25.4 = 8.762256 @@ -1743,7 +1743,7 @@ property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. If the specified vertical resolution is 96 dots per inch, the height is calculated as follows: + If the property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. If the specified vertical resolution is 96 dots per inch, the height is calculated as follows: 2355*(0.3/2048)\*96 = 33.1171875 @@ -1800,11 +1800,11 @@ ## Remarks The line spacing is the vertical distance between the base lines of two consecutive lines of text. Thus, the line spacing includes the blank space between lines along with the height of the character itself. - If the property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. For a screen display that has a vertical resolution of 96 dots per inch, you can calculate the height as follows: + If the property of the font is set to anything other than , the height (in pixels) is calculated using the vertical resolution of the screen display. For example, suppose the font unit is inches and the font size is 0.3. Also suppose that for the corresponding font family, the em-height is 2048 and the line spacing is 2355. For a screen display that has a vertical resolution of 96 dots per inch, you can calculate the height as follows: 2355*(0.3/2048)\*96 = 33.11719 - The value returned by the method would be 33.11719, and the value returned by the property would be 34. The property is the value returned by , rounded up to the nearest integer. + The value returned by the method would be 33.11719, and the value returned by the property would be 34. The property is the value returned by , rounded up to the nearest integer. ]]> @@ -1853,7 +1853,7 @@ property could return `true`, even if the font is not actually a system font. To avoid this situation, if you are using system fonts in your application, you should track user preference changes by handling the or event. + When the user changes the system font, the property could return `true`, even if the font is not actually a system font. To avoid this situation, if you are using system fonts in your application, you should track user preference changes by handling the or event. ]]> @@ -2320,7 +2320,7 @@ property will be one of the members of the , converted to a string. + The name returned by the property will be one of the members of the , converted to a string. ]]> diff --git a/xml/System.Drawing/FontFamily.xml b/xml/System.Drawing/FontFamily.xml index d91b18bb98f..9d914632513 100644 --- a/xml/System.Drawing/FontFamily.xml +++ b/xml/System.Drawing/FontFamily.xml @@ -52,7 +52,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example shows all the font families in the property of the class. This example is designed to be used with a Windows Form. To run this example, add a named `listBox1` to a form and call the `PopulateListBoxWithFonts` method from the form's constructor. + The following code example shows all the font families in the property of the class. This example is designed to be used with a Windows Form. To run this example, add a named `listBox1` to a form and call the `PopulateListBoxWithFonts` method from the form's constructor. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet1"::: @@ -365,7 +365,7 @@ property of the class. This example is designed to be used with a Windows Form. To run this example, add a named `listBox1` to a form and call the `PopulateListBoxWithFonts` method from the form's constructor. + The following code example shows all the font families in the property of the class. This example is designed to be used with a Windows Form. To run this example, add a named `listBox1` to a form and call the `PopulateListBoxWithFonts` method from the form's constructor. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet1"::: @@ -1006,7 +1006,7 @@ property of the class. This example is designed to be used with a Windows Form. To run this example, add a named `listBox1` to a form, and call the `PopulateListBoxWithFonts` method from the form's constructor. + The following code example shows all the font families in the property of the class. This example is designed to be used with a Windows Form. To run this example, add a named `listBox1` to a form, and call the `PopulateListBoxWithFonts` method from the form's constructor. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet1"::: diff --git a/xml/System.Drawing/Graphics.xml b/xml/System.Drawing/Graphics.xml index a83ebfc002f..b35f04d9a64 100644 --- a/xml/System.Drawing/Graphics.xml +++ b/xml/System.Drawing/Graphics.xml @@ -65,7 +65,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] - You can obtain a object by calling the method on an object that inherits from , or by handling a control's event and accessing the property of the class. You can also create a object from an image by using the method. For more information about creating a object, see [How to: Create Graphics Objects for Drawing](https://learn.microsoft.com/dotnet/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing). + You can obtain a object by calling the method on an object that inherits from , or by handling a control's event and accessing the property of the class. You can also create a object from an image by using the method. For more information about creating a object, see [How to: Create Graphics Objects for Drawing](https://learn.microsoft.com/dotnet/framework/winforms/advanced/how-to-create-graphics-objects-for-drawing). You can draw many different shapes and lines by using a object. For more information about how to draw lines and shapes, see the specific `Draw`*GraphicalElement* method for the line or shape you want to draw. These methods include , , , , and . For more information about how to draw lines and shapes, see [Using a Pen to Draw Lines and Shapes](https://learn.microsoft.com/dotnet/desktop/winforms/advanced/using-a-pen-to-draw-lines-and-shapes) and [Using a Brush to Fill Shapes](https://learn.microsoft.com/dotnet/framework/winforms/advanced/using-a-brush-to-fill-shapes). @@ -522,12 +522,12 @@ The following code example is designed for use with Windows Forms, and it requir object returned by the property does not affect subsequent drawing with the object. To change the clip region, replace the property value with a new object. To determine whether the clipping region is infinite, retrieve the property and call its method. + Modifying the object returned by the property does not affect subsequent drawing with the object. To change the clip region, replace the property value with a new object. To determine whether the clipping region is infinite, retrieve the property and call its method. ## Examples - The following code example demonstrates the use of the property. This example is designed to be used with Windows Forms. Paste the code into a form and call the `SetAndFillClip` method when handling the form's event, passing `e` as . + The following code example demonstrates the use of the property. This example is designed to be used with Windows Forms. Paste the code into a form and call the `SetAndFillClip` method when handling the form's event, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.GraphicsProperties/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Graphics/Clip/form1.cs" id="Snippet4"::: @@ -573,9 +573,9 @@ The following code example is designed for use with Windows Forms, and it requir property. The default unit is pixels. A is typically associated with a control and the origin of the rectangle will be relative to the client area of that control. + The unit for resulting rectangle is designated by the property. The default unit is pixels. A is typically associated with a control and the origin of the rectangle will be relative to the client area of that control. - If the clipping region is infinite, the property returns a meaningless large rectangle. To determine whether the clipping region is infinite, retrieve the property and call its method. + If the clipping region is infinite, the property returns a meaningless large rectangle. To determine whether the clipping region is infinite, retrieve the property and call its method. ]]> @@ -620,7 +620,7 @@ The following code example is designed for use with Windows Forms, and it requir The compositing mode determines whether pixels from a source image overwrite or are combined with background pixels. > [!NOTE] -> You should not use a property value of when the property is set to . An exception could occur or the image may not render correctly. +> You should not use a property value of when the property is set to . An exception could occur or the image may not render correctly. ]]> @@ -12359,7 +12359,7 @@ The object has a transform applied othe property of this . + This method excludes the area specified by the `rect` parameter from the current clip region and assigns the resulting area to the property of this . @@ -12424,7 +12424,7 @@ The object has a transform applied othe property of this . + This method excludes the area specified by the `region` parameter from the current clip region and assigns the resulting area to the property of this . @@ -16036,7 +16036,7 @@ The object has a transform applied othe property of this the area represented by the intersection of the current clip region and the rectangle specified by the `rect` parameter. + This method assigns to the property of this the area represented by the intersection of the current clip region and the rectangle specified by the `rect` parameter. @@ -16103,7 +16103,7 @@ The object has a transform applied othe property of this the area represented by the intersection of the current clip region and the rectangle specified by the `rect` parameter. + This method assigns to the property of this the area represented by the intersection of the current clip region and the rectangle specified by the `rect` parameter. @@ -16170,7 +16170,7 @@ The object has a transform applied othe property of this the area represented by the intersection of the current clip region and the region specified by the `region` parameter. + This method assigns to the property of this the area represented by the intersection of the current clip region and the region specified by the `region` parameter. @@ -18210,7 +18210,7 @@ The object has a transform applied othe ## Examples - The following code example demonstrates the effect of changing the property. + The following code example demonstrates the effect of changing the property. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ChangePageUnit` method when handling the form's event, passing `e` as . @@ -19638,7 +19638,7 @@ The object has a transform applied othe are rendered the same way (aliased) regardless of the property. + The smoothing mode specifies whether lines, curves, and the edges of filled areas use smoothing (also called antialiasing). One exception is that path gradient brushes do not obey the smoothing mode. Areas filled using a are rendered the same way (aliased) regardless of the property. @@ -19749,7 +19749,7 @@ The object has a transform applied othe The text rendering hint specifies whether text renders with antialiasing. > [!NOTE] -> You should not use a property value of when the property is set to . An exception could occur or the image may not render correctly. +> You should not use a property value of when the property is set to . An exception could occur or the image may not render correctly. @@ -19802,9 +19802,9 @@ The object has a transform applied othe property represents the world transformation, which maps world coordinates to page coordinates. + GDI+ uses three coordinate spaces: world, page, and device. World coordinates are the coordinates used to model a particular graphic world and are the coordinates you pass to methods in the .NET Framework. Page coordinates refer to the coordinate system used by a drawing surface, such as a form or a control. Device coordinates are the coordinates used by the physical device being drawn on, such as a screen or a printer. The property represents the world transformation, which maps world coordinates to page coordinates. - Because the matrix returned and by the property is a copy of the geometric transform, you should dispose of the matrix when you no longer need it. + Because the matrix returned and by the property is a copy of the geometric transform, you should dispose of the matrix when you no longer need it. ]]> @@ -20412,7 +20412,7 @@ This is a more performant alternative to property. The default unit is pixels. A is typically associated with a control and the origin of the rectangle will be relative to the client area of that control. + The unit for resulting rectangle is designated by the property. The default unit is pixels. A is typically associated with a control and the origin of the rectangle will be relative to the client area of that control. The visible clipping region is the intersection of the clipping region of this and the clipping region of the window. diff --git a/xml/System.Drawing/Image.xml b/xml/System.Drawing/Image.xml index 3e5e5c28f04..46c84e5faaf 100644 --- a/xml/System.Drawing/Image.xml +++ b/xml/System.Drawing/Image.xml @@ -372,7 +372,7 @@ |`ImageFlagsReadOnly`|65536| |`ImageFlagsCaching`|131072| - For example, if the property for an image returned 77960, the for the image would be , , , , and . + For example, if the property for an image returned 77960, the for the image would be , , , , and . ]]> @@ -1137,7 +1137,7 @@ ## Remarks For a list of property item IDs and links to more information, see . - It is difficult to set property items, because the class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . + It is difficult to set property items, because the class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . @@ -1599,7 +1599,7 @@ and methods to recolor the image. It also uses the property. + The following code example demonstrates how to construct a new bitmap from a file, using the and methods to recolor the image. It also uses the property. This example is designed to be used with a Windows Form that contains a , and named `Label1`, `PictureBox1`, and `Button1`, respectively. Paste the code into the form and associate the `Button1_Click` method with the button's event. @@ -1653,7 +1653,7 @@ property returns an empty array (that is, an array of length zero). + If the image has no property items or if the image format does not support property items, the property returns an empty array (that is, an array of length zero). ]]> @@ -1707,7 +1707,7 @@ ## Examples - The following code example demonstrates how to read and display the metadata in an image file using the class and the property. + The following code example demonstrates how to read and display the metadata in an image file using the class and the property. This example is designed to be used a Windows Form that imports the namespace. Paste the code into the form and change the path to `fakePhoto.jpg` to point to an image file on your system. Call the `ExtractMetaData` method when handling the form's event, passing `e` as . @@ -1794,7 +1794,7 @@ class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . + It is difficult to set property items, because the class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . ]]> @@ -2370,7 +2370,7 @@ ## Remarks If the image format does not support property items, this method throws with the message "Property not supported." If the image format supports property items but does not support the particular property you are attempting to set, this method ignores the attempt but does not throw an exception. - It is difficult to set property items, because the class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . + It is difficult to set property items, because the class has no public constructors. One way to work around this restriction is to obtain a by retrieving the property value or calling the method of an that already has property items. Then you can set the fields of the and pass it to . diff --git a/xml/System.Drawing/Pen.xml b/xml/System.Drawing/Pen.xml index ec80b0e1f27..5278174d0f0 100644 --- a/xml/System.Drawing/Pen.xml +++ b/xml/System.Drawing/Pen.xml @@ -56,7 +56,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example demonstrates constructing a with a and the effects of setting the property on a . + The following code example demonstrates constructing a with a and the effects of setting the property on a . This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineJoin` method when handling the form's event, passing `e` as . @@ -119,14 +119,14 @@ property determines how the draws lines. Lines are drawn as if they are filled rectangles, with the characteristics of the specified . + The property determines how the draws lines. Lines are drawn as if they are filled rectangles, with the characteristics of the specified . - The property of the new is set to 1 (the default). + The property of the new is set to 1 (the default). ## Examples - The following code example demonstrates constructing a with a and the effects of setting the property on a . + The following code example demonstrates constructing a with a and the effects of setting the property on a . This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineJoin` method when handling the form's event, passing `e` as . @@ -182,7 +182,7 @@ property is set to the color specified by the `color` parameter. The property is set to 1 (the default). + The property is set to the color specified by the `color` parameter. The property is set to 1 (the default). ]]> @@ -226,7 +226,7 @@ is set to the color specified in the `brush` parameter, the property is set to the value specified in the `width` parameter, and the units are set to . + The is set to the color specified in the `brush` parameter, the property is set to the value specified in the `width` parameter, and the units are set to . Note that the `brush` parameter also specifies the property of this . @@ -287,7 +287,7 @@ property is set to the color specified by the `color` parameter. The property is set to the value specified in the `width` parameter. If this value is 0, the width in device units is always 1 pixel— it is not affected by scale-transform operations that are in effect for the Graphics object that the is used for. + The property is set to the color specified by the `color` parameter. The property is set to the value specified in the `width` parameter. If this value is 0, the width in device units is always 1 pixel— it is not affected by scale-transform operations that are in effect for the Graphics object that the is used for. @@ -525,7 +525,7 @@ Suppose you want a pen to draw two parallel lines where the width of the first line is 20 percent of the pen's width, the width of the space that separates the two lines is 50 percent of the pen' s width, and the width of the second line is 30 percent of the pen's width. Start by creating a and an array of real numbers. Set the compound array by passing the array with the values 0.0, 0.2, 0.7, and 1.0 to this property. - Do not set this property if the has its property set to . + Do not set this property if the has its property set to . ]]> @@ -640,7 +640,7 @@ if the has its property set to . + Do not set this property to if the has its property set to . @@ -789,7 +789,7 @@ for this property specifies that a custom pattern of dashes and spaces, defined by the property, makes up lines drawn with this . If the value of this property is and the value of the property is `null`, the pen draws solid lines. + A value of for this property specifies that a custom pattern of dashes and spaces, defined by the property, makes up lines drawn with this . If the value of this property is and the value of the property is `null`, the pen draws solid lines. ]]> @@ -1701,7 +1701,7 @@ property is a copy of the pen's geometric transform, you should dispose of the matrix when you no longer need it. + This property defines an elliptical shape for the pen tip. This ellipse is obtained from the default circular shape by applying the transformation matrix. Note that the translation portion of the matrix is ignored. Because the matrix returned and by the property is a copy of the pen's geometric transform, you should dispose of the matrix when you no longer need it. ]]> @@ -1841,7 +1841,7 @@ object using its property. The unit of measure is typically pixels. A of 0 will result in the drawing as if the were 1. + You can access the unit of measure of the object using its property. The unit of measure is typically pixels. A of 0 will result in the drawing as if the were 1. diff --git a/xml/System.Drawing/Rectangle.xml b/xml/System.Drawing/Rectangle.xml index eebcb4cba1c..8ba802922dd 100644 --- a/xml/System.Drawing/Rectangle.xml +++ b/xml/System.Drawing/Rectangle.xml @@ -81,33 +81,33 @@ Stores a set of four integers that represent the location and size of a rectangle. - , , and upper-left corner represented by the property. - - To draw rectangles, you need a object and a object. The object provides the method, and the object stores features of the line, such as color and width. The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. - - To draw a filled with color, you need a object and an object derived from such as or . The object provides the method and the object provides the color and fill information. - - For more advanced shapes, use a object. - - - -## Examples - The following example draws a rectangle with its upper-left corner at (10, 10). The rectangle has a width of 100 and a height of 50. The second argument passed to the constructor indicates that the pen width is 5 pixels. - - When the rectangle is drawn, the pen is centered on the rectangle's boundary. Because the pen width is 5, the sides of the rectangle are drawn 5 pixels wide, such that 1 pixel is drawn on the boundary itself, 2 pixels are drawn on the inside, and 2 pixels are drawn on the outside. For more details on pen alignment, see [How to: Set Pen Width and Alignment](/dotnet/framework/winforms/advanced/how-to-set-pen-width-and-alignment). - - The following illustration shows the resulting rectangle. The dotted lines show where the rectangle would have been drawn if the pen width had been one pixel. The enlarged view of the upper-left corner of the rectangle shows that the thick black lines are centered on those dotted lines. - - ![Pens](~/add/media/pens1.gif "Pens") - - The example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. - + , , and upper-left corner represented by the property. + + To draw rectangles, you need a object and a object. The object provides the method, and the object stores features of the line, such as color and width. The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. + + To draw a filled with color, you need a object and an object derived from such as or . The object provides the method and the object provides the color and fill information. + + For more advanced shapes, use a object. + + + +## Examples + The following example draws a rectangle with its upper-left corner at (10, 10). The rectangle has a width of 100 and a height of 50. The second argument passed to the constructor indicates that the pen width is 5 pixels. + + When the rectangle is drawn, the pen is centered on the rectangle's boundary. Because the pen width is 5, the sides of the rectangle are drawn 5 pixels wide, such that 1 pixel is drawn on the boundary itself, 2 pixels are drawn on the inside, and 2 pixels are drawn on the outside. For more details on pen alignment, see [How to: Set Pen Width and Alignment](/dotnet/framework/winforms/advanced/how-to-set-pen-width-and-alignment). + + The following illustration shows the resulting rectangle. The dotted lines show where the rectangle would have been drawn if the pen width had been one pixel. The enlarged view of the upper-left corner of the rectangle shows that the thick black lines are centered on those dotted lines. + + ![Pens](~/add/media/pens1.gif "Pens") + + The example is designed for use with Windows Forms, and it requires `e`, which is a parameter of the event handler. + :::code language="csharp" source="~/snippets/csharp/System.Drawing/Rectangle/Overview/Class1.cs" id="Snippet21"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Rectangle/Overview/Class1.vb" id="Snippet21"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Rectangle/Overview/Class1.vb" id="Snippet21"::: + ]]> @@ -224,15 +224,15 @@ The height of the rectangle. Initializes a new instance of the class with the specified location and size. - , , , and members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . - + , , , and members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet2"::: + ]]> @@ -294,11 +294,11 @@ Gets the y-coordinate that is the sum of the and property values of this structure. The y-coordinate that is the sum of and of this . - property represents the y-coordinate of the first point at the bottom edge of the that is not contained in the . - + property represents the y-coordinate of the first point at the bottom edge of the that is not contained in the . + ]]> @@ -416,11 +416,11 @@ Determines if the specified point is contained within this structure. This method returns if the point represented by is contained within this structure; otherwise . - @@ -479,20 +479,20 @@ Determines if the rectangular region represented by is entirely contained within this structure. This method returns if the rectangular region represented by is entirely contained within this structure; otherwise . - method and the class. This example is designed for use with a Windows Form. Paste this code into a form that contains a button named `Button1`, call `DrawFirstRectangle` from the form's constructor or method, and associate the `Button1_Click` method with the button's event. - + method and the class. This example is designed for use with a Windows Form. Paste this code into a form that contains a button named `Button1`, call `DrawFirstRectangle` from the form's constructor or method, and associate the `Button1_Click` method with the button's event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet3"::: + ]]> @@ -553,11 +553,11 @@ Determines if the specified point is contained within this structure. This method returns if the point defined by and is contained within this structure; otherwise . - @@ -604,11 +604,11 @@ Represents a structure with its properties left uninitialized. - @@ -787,20 +787,20 @@ Creates a structure with the specified edge locations. The new that this method creates. - with the specified upper-left and lower-right corners. - - - -## Examples - The following code example demonstrates how to create a rectangle using the method. This example is designed to be used with a Windows Form. Paste this code into a form and call the `CreateARectangleFromLTRB` method when handling the form's event, passing `e` as . - + with the specified upper-left and lower-right corners. + + + +## Examples + The following code example demonstrates how to create a rectangle using the method. This example is designed to be used with a Windows Form. Paste this code into a form and call the `CreateARectangleFromLTRB` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet7"::: + ]]> @@ -915,11 +915,11 @@ Gets or sets the height of this structure. The height of this structure. The default is 0. - property will also cause a change in the property of the . The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. - + property will also cause a change in the property of the . The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. + ]]> @@ -980,20 +980,20 @@ The amount to inflate this rectangle. Enlarges this by the specified amount. - `e`, which is a parameter of the event handler. The code creates a and enlarges it by 50 units in both axes. The rectangle is drawn to screen before inflation (black) and after inflation (red). - + `e`, which is a parameter of the event handler. The code creates a and enlarges it by 50 units in both axes. The rectangle is drawn to screen before inflation (black) and after inflation (red). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicRectangleExamples/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Rectangle/Inflate/form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Rectangle/Inflate/form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Rectangle/Inflate/form1.vb" id="Snippet2"::: + ]]> @@ -1052,22 +1052,22 @@ The amount to inflate this vertically. Enlarges this by the specified amount. - structure is deflated in the corresponding direction. - - - -## Examples - The following example creates a structure and enlarges it by 100 units in the x-axis direction: - + structure is deflated in the corresponding direction. + + + +## Examples + The following example creates a structure and enlarges it by 100 units in the x-axis direction: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicRectangleExamples/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Rectangle/Inflate/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Rectangle/Inflate/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Rectangle/Inflate/form1.vb" id="Snippet3"::: + ]]> @@ -1123,20 +1123,20 @@ Creates and returns an enlarged copy of the specified structure. The copy is enlarged by the specified amount. The original structure remains unmodified. The enlarged . - `e`, which is a parameter of the event handler. The code creates a and enlarges it by 50 units in both axes. Notice that the resulting rectangle (red) is 150 units in both axes. - + `e`, which is a parameter of the event handler. The code creates a and enlarges it by 50 units in both axes. Notice that the resulting rectangle (red) is 150 units in both axes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.ClassicRectangleExamples/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Rectangle/Inflate/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Rectangle/Inflate/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Rectangle/Inflate/form1.vb" id="Snippet1"::: + ]]> @@ -1197,15 +1197,15 @@ The with which to intersect. Replaces this with the intersection of itself and the specified . - , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . - + , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet2"::: + ]]> @@ -1259,15 +1259,15 @@ Returns a third structure that represents the intersection of two other structures. If there is no intersection, an empty is returned. A that represents the intersection of and . - , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . - + , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet1"::: + ]]> @@ -1326,15 +1326,15 @@ Determines if this rectangle intersects with . This method returns if there is any intersection, otherwise . - , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . - + , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet2"::: + ]]> @@ -1392,15 +1392,15 @@ Tests whether all numeric properties of this have values of zero. This property returns if the , , , and properties of this all have values of zero; otherwise, . - , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . - + , and the members. This example should be used with a Windows Form. Paste this code into a form and call this method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet2"::: + ]]> @@ -1583,20 +1583,20 @@ Amount to offset the location. Adjusts the location of this rectangle by the specified amount. - , and methods and the class. This example is designed for use with a Windows Form. Paste this code into a form that contains a button named `Button1`, call `DrawFirstRectangle` from the form's constructor or method, and associate the `Button1_Click` method with the button's event. - + , and methods and the class. This example is designed for use with a Windows Form. Paste this code into a form that contains a button named `Button1`, call `DrawFirstRectangle` from the form's constructor or method, and associate the `Button1_Click` method with the button's event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet3"::: + ]]> @@ -1822,11 +1822,11 @@ Gets the x-coordinate that is the sum of and property values of this structure. The x-coordinate that is the sum of and of this . - property represents the x-coordinate of the first point at the right edge of the rectangle that is not contained in the rectangle. - + property represents the x-coordinate of the first point at the right edge of the rectangle that is not contained in the rectangle. + ]]> @@ -1878,15 +1878,15 @@ Converts the specified to a by rounding the values to the nearest integer values. The rounded integer value of the . - and methods. This example is designed for use with a Windows Form. Paste this code into a form and call the `RoundingAndTruncatingRectangles` method when handling the form's event, passing `e` as . - + and methods. This example is designed for use with a Windows Form. Paste this code into a form and call the `RoundingAndTruncatingRectangles` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet5"::: + ]]> @@ -2113,15 +2113,15 @@ Converts the specified to a by truncating the values. The truncated value of the . - and methods. This example is designed for use with a Windows Form. Paste this code into a form and call the `RoundingAndTruncatingRectangles` method when handling the form's event, passing `e` as . - + and methods. This example is designed for use with a Windows Form. Paste this code into a form and call the `RoundingAndTruncatingRectangles` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet5"::: + ]]> @@ -2175,20 +2175,20 @@ Gets a structure that contains the union of two structures. A structure that bounds the union of the two structures. - method returns a rectangle with a starting point of (0, 0), and the height and width of the non-empty rectangle. For example, if you have two rectangles: A = (0, 0; 0, 0) and B = (1, 1; 2, 2), then the union of A and B is (0, 0; 2, 2). - - - -## Examples - The following code example demonstrates how to use the method. This example is designed for use with a Windows Form. Paste this code into a form and call the `ShowRectangleUnion` method when handling the form's event, passing `e` as . - + method returns a rectangle with a starting point of (0, 0), and the height and width of the non-empty rectangle. For example, if you have two rectangles: A = (0, 0; 0, 0) and B = (1, 1; 2, 2), then the union of A and B is (0, 0; 2, 2). + + + +## Examples + The following code example demonstrates how to use the method. This example is designed for use with a Windows Form. Paste this code into a form and call the `ShowRectangleUnion` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.RectanglesAndPoints/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Brushes/Overview/form1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Brushes/Overview/form1.vb" id="Snippet4"::: + ]]> @@ -2250,11 +2250,11 @@ Gets or sets the width of this structure. The width of this structure. The default is 0. - property will also cause a change in the property of the . The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. - + property will also cause a change in the property of the . The units the rectangle is drawn in is determined by the and properties of the graphics object used for drawing. The default unit is pixels. + ]]> @@ -2316,11 +2316,11 @@ Gets or sets the x-coordinate of the upper-left corner of this structure. The x-coordinate of the upper-left corner of this structure. The default is 0. - property will also cause a change in the property of the . - + property will also cause a change in the property of the . + ]]> @@ -2382,11 +2382,11 @@ Gets or sets the y-coordinate of the upper-left corner of this structure. The y-coordinate of the upper-left corner of this structure. The default is 0. - property will also cause a change in the property of the . - + property will also cause a change in the property of the . + ]]> diff --git a/xml/System.Drawing/RotateFlipType.xml b/xml/System.Drawing/RotateFlipType.xml index 4d24f44c35e..bfdeffddfdc 100644 --- a/xml/System.Drawing/RotateFlipType.xml +++ b/xml/System.Drawing/RotateFlipType.xml @@ -34,22 +34,22 @@ Specifies how much an image is rotated and the axis used to flip the image. - property of an and the enumeration. - - This example is designed to be used with a Windows Form that contains a named `PictureBox1` and a button named `Button1`. Paste the code into a form, call `InitializeBitmap` from the form's constructor or event-handling method and associate `Button1_Click` with the button's event. Ensure the file path to the bitmap is valid on your system. - + property of an and the enumeration. + + This example is designed to be used with a Windows Form that contains a named `PictureBox1` and a button named `Button1`. Paste the code into a form, call `InitializeBitmap` from the form's constructor or event-handling method and associate `Button1_Click` with the button's event. Ensure the file path to the bitmap is valid on your system. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.BitmapMembers/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Bitmap/.ctor/form1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Drawing/Size.xml b/xml/System.Drawing/Size.xml index 144dba7519a..618847c9c8f 100644 --- a/xml/System.Drawing/Size.xml +++ b/xml/System.Drawing/Size.xml @@ -85,7 +85,7 @@ ## Remarks -The structure is used to specify a height and width through the property for , , , and other graphics classes. You can perform operations on a by using the overloaded operators such as , , and . The unit for the and of the structure depend on the and settings for the object that is used to draw. +The structure is used to specify a height and width through the property for , , , and other graphics classes. You can perform operations on a by using the overloaded operators such as , , and . The unit for the and of the structure depend on the and settings for the object that is used to draw. ]]> diff --git a/xml/System.Drawing/StringAlignment.xml b/xml/System.Drawing/StringAlignment.xml index 5ad56f3eb10..40e37fd28a4 100644 --- a/xml/System.Drawing/StringAlignment.xml +++ b/xml/System.Drawing/StringAlignment.xml @@ -34,20 +34,20 @@ Specifies the alignment of a text string relative to its layout rectangle. - property, this enumeration sets the vertical alignment for a drawn string. When used with the property, this enumeration sets the horizontal alignment. - - - -## Examples - The following code example demonstrates how to use the and properties and the enumeration to align strings. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineAndAlignment` method when handling the form's event, passing `e` as . - + property, this enumeration sets the vertical alignment for a drawn string. When used with the property, this enumeration sets the horizontal alignment. + + + +## Examples + The following code example demonstrates how to use the and properties and the enumeration to align strings. This example is designed to be used with Windows Forms. Paste the code into a form and call the `ShowLineAndAlignment` method when handling the form's event, passing `e` as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Drawing/StringFormat.xml b/xml/System.Drawing/StringFormat.xml index 04ab8baf6b6..271e38ba399 100644 --- a/xml/System.Drawing/StringFormat.xml +++ b/xml/System.Drawing/StringFormat.xml @@ -610,7 +610,7 @@ ||| ||0| - If you make changes to the object returned from the property, these changes persist, and future calls to the property reflects these changes. + If you make changes to the object returned from the property, these changes persist, and future calls to the property reflects these changes. ]]> @@ -765,7 +765,7 @@ ## Examples - The following code example shows how to set a keyboard shortcut using the property. It also demonstrates how to use the method. To run this example, paste the code into a form, handle the form's event and call the following method, passing e as . + The following code example shows how to set a keyboard shortcut using the property. It also demonstrates how to use the method. To run this example, paste the code into a form, handle the form's event and call the following method, passing e as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet2"::: @@ -1053,7 +1053,7 @@ property is converted. + Only the value of the property is converted. @@ -1112,7 +1112,7 @@ property and how to use the enumeration. This example is designed to be used with a Windows Form. Paste this code into a form and call the `ShowStringTrimming` method when handling the form's event, passing e as . + The following example shows how to set the property and how to use the enumeration. This example is designed to be used with a Windows Form. Paste this code into a form and call the `ShowStringTrimming` method when handling the form's event, passing e as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet6"::: diff --git a/xml/System.Drawing/StringTrimming.xml b/xml/System.Drawing/StringTrimming.xml index 9cbd4ea2908..c5b5a726311 100644 --- a/xml/System.Drawing/StringTrimming.xml +++ b/xml/System.Drawing/StringTrimming.xml @@ -34,15 +34,15 @@ Specifies how to trim characters from a string that does not completely fit into a layout shape. - property and how to use the enumeration. This example is designed to be used with a Windows Form. Paste this code into a form and call the ShowStringTrimming method when handling the form's `Paint` event, passing e as . - + property and how to use the enumeration. This example is designed to be used with a Windows Form. Paste this code into a form and call the ShowStringTrimming method when handling the form's `Paint` event, passing e as . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.Misc2/CPP/form1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Color/Name/form1.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/Color/Name/form1.vb" id="Snippet6"::: + ]]> diff --git a/xml/System.Drawing/SystemBrushes.xml b/xml/System.Drawing/SystemBrushes.xml index db3dfdbed8d..6b297bb17af 100644 --- a/xml/System.Drawing/SystemBrushes.xml +++ b/xml/System.Drawing/SystemBrushes.xml @@ -52,7 +52,7 @@ [!INCLUDE[System.Drawing.Common note](~/includes/system-drawing-common.md)] ## Examples - The following code example shows how to set a keyboard shortcut using the property. It also demonstrates how to use the method. To run this example, paste the code into a form, handle the form's event and call the following method, passing `e` as . + The following code example shows how to set a keyboard shortcut using the property. It also demonstrates how to use the method. To run this example, paste the code into a form, handle the form's event and call the following method, passing `e` as . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.MiscExamples/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/Bitmap/.ctor/form12.cs" id="Snippet2"::: diff --git a/xml/System.Drawing/SystemColors.xml b/xml/System.Drawing/SystemColors.xml index 3ed02574d0a..b5ba922aa22 100644 --- a/xml/System.Drawing/SystemColors.xml +++ b/xml/System.Drawing/SystemColors.xml @@ -56,20 +56,20 @@ Each property of the class is a structure that is the color of a Windows display element. - or classes rather than creating a new pen or brush based on a value from . For example, if you wanted to get a brush for the face color of a 3-D element, use the property because it gets a brush that already exists, whereas calling the constructor with a parameter value of will create a new brush. - - - -## Examples - The following code example demonstrates the operator and the class. This example is designed to be used with a Windows Form that contains a button named `Button1`. Paste the following code into your form and associate the `Button1_Click` method with the button's `Click` event. - + or classes rather than creating a new pen or brush based on a value from . For example, if you wanted to get a brush for the face color of a 3-D element, use the property because it gets a brush that already exists, whereas calling the constructor with a parameter value of will create a new brush. + + + +## Examples + The following code example demonstrates the operator and the class. This example is designed to be used with a Windows Form that contains a button named `Button1`. Paste the following code into your form and associate the `Button1_Click` method with the button's `Click` event. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Drawing.CharacterRangeExample/CPP/form1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Overview/form1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Overview/form1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Overview/form1.vb" id="Snippet2"::: + ]]> @@ -244,11 +244,11 @@ Gets a structure that is the color of the application workspace. A that is the color of the application workspace. - @@ -335,11 +335,11 @@ Gets a structure that is the highlight color of a 3-D element. A that is the highlight color of a 3-D element. - @@ -384,11 +384,11 @@ Gets a structure that is the shadow color of a 3-D element. A that is the shadow color of a 3-D element. - @@ -483,11 +483,11 @@ Gets a structure that is the shadow color of a 3-D element. A that is the shadow color of a 3-D element. - @@ -533,11 +533,11 @@ Gets a structure that is the dark shadow color of a 3-D element. A that is the dark shadow color of a 3-D element. - @@ -583,11 +583,11 @@ Gets a structure that is the light color of a 3-D element. A that is the light color of a 3-D element. - @@ -633,11 +633,11 @@ Gets a structure that is the highlight color of a 3-D element. A that is the highlight color of a 3-D element. - @@ -853,11 +853,11 @@ Gets a structure that is the color of dimmed text. A that is the color of dimmed text. - @@ -903,11 +903,11 @@ Gets a structure that is the color of the background of selected items. A that is the color of the background of selected items. - structure may be the color used for the background of selected items in a list box. - + structure may be the color used for the background of selected items in a list box. + ]]> @@ -953,11 +953,11 @@ Gets a structure that is the color of the text of selected items. A that is the color of the text of selected items. - @@ -1003,11 +1003,11 @@ Gets a structure that is the color used to designate a hot-tracked item. A that is the color used to designate a hot-tracked item. - diff --git a/xml/System.Drawing/SystemFonts.xml b/xml/System.Drawing/SystemFonts.xml index 1e6eedc0706..89c75a30497 100644 --- a/xml/System.Drawing/SystemFonts.xml +++ b/xml/System.Drawing/SystemFonts.xml @@ -131,7 +131,7 @@ property depending on the operating system and local culture. + The following table describes the value returned by the property depending on the operating system and local culture. |System and/or culture|Font| |----------------------------|----------| @@ -141,7 +141,7 @@ MS Shell Dlg maps to a font set in the system registry. - If the above fonts are not installed, the default font is Tahoma, 8 point. If Tahoma, 8 point, is not installed, returns the value of the property. + If the above fonts are not installed, the default font is Tahoma, 8 point. If Tahoma, 8 point, is not installed, returns the value of the property. The returned by does not change when the user is in High Contrast mode. For a font that changes when the user is in High Contrast mode use another system font such as . @@ -190,7 +190,7 @@ property returns Tahoma, 8 point. Otherwise, returns the value of the property. The returned by does not change when the user is in High Contrast mode. For a font that changes when the user is in High Contrast mode use another system font such as . + If the operating system is Windows 2000 or Windows XP, the property returns Tahoma, 8 point. Otherwise, returns the value of the property. The returned by does not change when the user is in High Contrast mode. For a font that changes when the user is in High Contrast mode use another system font such as . ]]> diff --git a/xml/System.Drawing/SystemPens.xml b/xml/System.Drawing/SystemPens.xml index be237c40808..9b9e0e4d92b 100644 --- a/xml/System.Drawing/SystemPens.xml +++ b/xml/System.Drawing/SystemPens.xml @@ -99,7 +99,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithActiveBorderPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithActiveBorderPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet13"::: @@ -143,7 +143,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithActiveCaptionPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithActiveCaptionPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet14"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet14"::: @@ -227,7 +227,7 @@ ## Examples - The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithActiveAppWorkspacePen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithActiveAppWorkspacePen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet14"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet14"::: @@ -271,7 +271,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithButtonSpacePen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithButtonSpacePen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet16"::: @@ -320,7 +320,7 @@ ## Examples - The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithButtonHighlightPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithButtonHighlightPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet17"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet17"::: @@ -369,7 +369,7 @@ ## Examples - The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithButtonShadowPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithButtonShadowPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet18"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet18"::: @@ -414,7 +414,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet19"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet19"::: @@ -464,7 +464,7 @@ ## Examples - The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlDarkPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlDarkPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet20"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet20"::: @@ -514,7 +514,7 @@ ## Examples - The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlDarkDarkPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlDarkDarkPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet21"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet21"::: @@ -564,7 +564,7 @@ ## Examples - The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlLightPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlLightPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet22"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet22"::: @@ -614,7 +614,7 @@ ## Examples - The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlLightLightPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlLightLightPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet23"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet23"::: @@ -659,7 +659,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlTextPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlTextPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet24"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet24"::: @@ -703,7 +703,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlDesktopPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithControlDesktopPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet25"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet25"::: @@ -786,7 +786,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithGradientActiveCaptionPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithGradientActiveCaptionPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet26"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet26"::: @@ -830,7 +830,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithGradientInactiveCaptionPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithGradientInactiveCaptionPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet27"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet27"::: @@ -880,7 +880,7 @@ ## Examples - The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithGrayTextPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithGrayTextPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet28"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet28"::: @@ -930,7 +930,7 @@ ## Examples - The following code example creates points and sizes using several of the overloaded operators defined for these types. It also demonstrates how to use the property. + The following code example creates points and sizes using several of the overloaded operators defined for these types. It also demonstrates how to use the property. This example is designed to be used with Windows Forms. Create a form that contains a named `subtractButton`. Paste the code into the form and call the `CreatePointsAndSizes` method from the form's event-handling method, passing `e` as . @@ -983,7 +983,7 @@ ## Examples - The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithHighlightTextPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithHighlightTextPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet30"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet30"::: @@ -1027,7 +1027,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithHotTrackPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithHotTrackPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet31"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet31"::: @@ -1071,7 +1071,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithInactiveBorderPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithInactiveBorderPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet32"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet32"::: @@ -1115,7 +1115,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithInactiveCaptionPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithInactiveCaptionPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet33"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet33"::: @@ -1160,7 +1160,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithInactiveCaptionTextPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithInactiveCaptionTextPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet34"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet34"::: @@ -1204,7 +1204,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithInfoPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithInfoPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet35"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet35"::: @@ -1249,7 +1249,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithInfoTextPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithInfoTextPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet36"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet36"::: @@ -1293,7 +1293,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithMenuPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithMenuPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet37"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet37"::: @@ -1337,7 +1337,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithMenuBarPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithMenuBarPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet38"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet38"::: @@ -1381,7 +1381,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithMenuHighlightPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithMenuHighlightPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet39"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet39"::: @@ -1426,7 +1426,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithMenuTextPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithMenuTextPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet40"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet40"::: @@ -1470,7 +1470,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithScrollBarPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithScrollBarPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet41"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet41"::: @@ -1514,7 +1514,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithWindowPen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithWindowPen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet42"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet42"::: @@ -1559,7 +1559,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithWindowFramePen` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithWindowFramePen` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet44"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet44"::: @@ -1604,7 +1604,7 @@ property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithWindowText` method from the event-handling method, passing `e` as . + The following code example demonstrates how to use the property. To run this example, paste it into a Windows Form. Handle the form's event and call the `DrawWithWindowText` method from the event-handling method, passing `e` as . :::code language="csharp" source="~/snippets/csharp/System.Drawing/CharacterRange/Equals/Form1.cs" id="Snippet45"::: :::code language="vb" source="~/snippets/visualbasic/System.Drawing/CharacterRange/Equals/Form1.vb" id="Snippet45"::: diff --git a/xml/System.Drawing/TextureBrush.xml b/xml/System.Drawing/TextureBrush.xml index e66f4497686..1458df9ad42 100644 --- a/xml/System.Drawing/TextureBrush.xml +++ b/xml/System.Drawing/TextureBrush.xml @@ -997,7 +997,7 @@ property is a copy of the brush's geometric transform, you should dispose of the matrix when you no longer need it. + A geometric transformation can be used to translate, scale, rotate, or skew the image that defines the texture of this brush. Because the matrix returned and by the property is a copy of the brush's geometric transform, you should dispose of the matrix when you no longer need it. ]]> @@ -1176,7 +1176,7 @@ method. It also demonstrates the property and the enumeration. + The following code example demonstrates how to obtain a new bitmap using the method. It also demonstrates the property and the enumeration. This example is designed to be used with Windows Forms. Create a form containing a button named Button2. Paste the code into the form and associate the Button2_Click method with the button's `Click` event. diff --git a/xml/System.EnterpriseServices/Activity.xml b/xml/System.EnterpriseServices/Activity.xml index d847e2e2b15..58fd8925c59 100644 --- a/xml/System.EnterpriseServices/Activity.xml +++ b/xml/System.EnterpriseServices/Activity.xml @@ -24,18 +24,18 @@ Creates an activity to do synchronous or asynchronous batch work that can use COM+ services without needing to create a COM+ component. This class cannot be inherited. - object. - - - -## Examples - The following code example demonstrates how to use the class and use the synchronization service. - - :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/Activity/Overview/EnterpriseServices_Activity.cs" id="Snippet0"::: - + object. + + + +## Examples + The following code example demonstrates how to use the class and use the synchronization service. + + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/Activity/Overview/EnterpriseServices_Activity.cs" id="Snippet0"::: + ]]> @@ -61,18 +61,18 @@ A that contains the configuration information for the services to be used. Initializes a new instance of the class. - that is used to submit batch work to COM+ services. The context associated with the activity is completely determined by the object that is passed through the `cfg` parameter. - - - -## Examples - The following code example demonstrates how to initialize a new instance of the class. - - :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/Activity/Overview/EnterpriseServices_Activity.cs" id="Snippet1"::: - + that is used to submit batch work to COM+ services. The context associated with the activity is completely determined by the object that is passed through the `cfg` parameter. + + + +## Examples + The following code example demonstrates how to initialize a new instance of the class. + + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/Activity/Overview/EnterpriseServices_Activity.cs" id="Snippet1"::: + ]]> @@ -103,13 +103,13 @@ A object that is used to implement the batch work. Runs the specified user-defined batch work asynchronously. - @@ -135,11 +135,11 @@ Binds the user-defined work to the current thread. - binds the batch work that is submitted by the or methods to the current single-threaded apartment (STA). has no effect if the current thread is being run in the multithreaded apartment (MTA). The current thread model is determined by the configuration of the property of the object. - + binds the batch work that is submitted by the or methods to the current single-threaded apartment (STA). has no effect if the current thread is being run in the multithreaded apartment (MTA). The current thread model is determined by the configuration of the property of the object. + ]]> @@ -191,11 +191,11 @@ Unbinds the batch work that is submitted by the or methods from the thread on which the batch work is running. - has no effect if the batch work was not previously bound to a thread. - + has no effect if the batch work was not previously bound to a thread. + ]]> diff --git a/xml/System.EnterpriseServices/ApplicationIDAttribute.xml b/xml/System.EnterpriseServices/ApplicationIDAttribute.xml index 8b27f577687..e89425854bf 100644 --- a/xml/System.EnterpriseServices/ApplicationIDAttribute.xml +++ b/xml/System.EnterpriseServices/ApplicationIDAttribute.xml @@ -28,19 +28,19 @@ Specifies the application ID (as a GUID) for this assembly. This class cannot be inherited. - takes a GUID in its constructor. When registration occurs, the components in the assembly are installed in an application with the given ID. - - - -## Examples - The following code example demonstrates the use of the type. - + takes a GUID in its constructor. When registration occurs, the components in the assembly are installed in an application with the given ID. + + + +## Examples + The following code example demonstrates the use of the type. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ApplicationIDAttribute/Overview/class1.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationIDAttribute/Overview/class1.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationIDAttribute/Overview/class1.vb" id="Snippet0"::: + ]]> @@ -66,14 +66,14 @@ The GUID associated with the COM+ application. Initializes a new instance of the class specifying the GUID representing the application ID for the COM+ application. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ApplicationIDAttribute/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationIDAttribute/Overview/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationIDAttribute/Overview/class1.vb" id="Snippet1"::: + ]]> @@ -99,19 +99,19 @@ Gets the GUID of the COM+ application. The GUID representing the COM+ application. - is set by the constructor using the GUID passed in as a parameter. - - - -## Examples - The following code example demonstrates how to get the value of an `ApplicationID` attribute's property. - + is set by the constructor using the GUID passed in as a parameter. + + + +## Examples + The following code example demonstrates how to get the value of an `ApplicationID` attribute's property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ApplicationIDAttribute/Overview/class1.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationIDAttribute/Overview/class1.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationIDAttribute/Overview/class1.vb" id="Snippet0"::: + ]]> diff --git a/xml/System.EnterpriseServices/ApplicationQueuingAttribute.xml b/xml/System.EnterpriseServices/ApplicationQueuingAttribute.xml index 3d131f66ae6..c3a73644ba8 100644 --- a/xml/System.EnterpriseServices/ApplicationQueuingAttribute.xml +++ b/xml/System.EnterpriseServices/ApplicationQueuingAttribute.xml @@ -28,21 +28,21 @@ Enables queuing support for the marked assembly and enables the application to read method calls from Message Queuing queues. This class cannot be inherited. - , see the constructor. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following code example demonstrates the use of the type. - + , see the constructor. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following code example demonstrates the use of the type. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.vb" id="Snippet0"::: + ]]> @@ -64,25 +64,25 @@ Initializes a new instance of the class, enabling queuing support for the assembly and initializing , , and . - . - -|Property|Value| -|--------------|-----------| -|`Enabled`|`true`| -|`QueueListenerEnabled`|`false`| -|`MaxListenerThreads`|zero (0)| - - - -## Examples - The following code example creates a new . - + . + +|Property|Value| +|--------------|-----------| +|`Enabled`|`true`| +|`QueueListenerEnabled`|`false`| +|`MaxListenerThreads`|zero (0)| + + + +## Examples + The following code example creates a new . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.vb" id="Snippet1"::: + ]]> @@ -109,19 +109,19 @@ if queuing support is enabled; otherwise, . The default value set by the constructor is . - enables an application to use queued components; however, it does not enable the application to listen for queued messages from clients. - - - -## Examples - The following code example gets and sets the value of an `ApplicationQueuing` attribute's property. - + enables an application to use queued components; however, it does not enable the application to listen for queued messages from clients. + + + +## Examples + The following code example gets and sets the value of an `ApplicationQueuing` attribute's property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.vb" id="Snippet2"::: + ]]> @@ -147,21 +147,21 @@ Gets or sets the number of threads used to extract messages from the queue and activate the corresponding component. The maximum number of threads to use for processing messages arriving in the queue. The default is zero. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.vb" id="Snippet4"::: + ]]> @@ -188,14 +188,14 @@ if the application accepts queued component calls; otherwise, . The default is . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ApplicationQueuingAttribute/Overview/class1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.EnterpriseServices/AutoCompleteAttribute.xml b/xml/System.EnterpriseServices/AutoCompleteAttribute.xml index f9b2a6efcc6..a8cd5618c94 100644 --- a/xml/System.EnterpriseServices/AutoCompleteAttribute.xml +++ b/xml/System.EnterpriseServices/AutoCompleteAttribute.xml @@ -28,21 +28,21 @@ Marks the attributed method as an object. This class cannot be inherited. - if the method call returns normally. If the method call throws an exception, the transaction is aborted. - - - -## Examples - The following code example demonstrates the use of the type. - + if the method call returns normally. If the method call throws an exception, the transaction is aborted. + + + +## Examples + The following code example demonstrates the use of the type. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.vb" id="Snippet0"::: + ]]> @@ -73,14 +73,14 @@ Initializes a new instance of the class, specifying that the application should automatically call if the transaction completes successfully. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.vb" id="Snippet1"::: + ]]> @@ -107,19 +107,19 @@ to enable in the COM+ object; otherwise, . Initializes a new instance of the class, specifying whether COM+ is enabled. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.vb" id="Snippet2"::: + ]]> @@ -146,14 +146,14 @@ if is enabled in COM+; otherwise, . The default is . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AutoCompleteAttribute/Overview/class1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.EnterpriseServices/ContextUtil.xml b/xml/System.EnterpriseServices/ContextUtil.xml index 33babdf4c90..91ac726b67d 100644 --- a/xml/System.EnterpriseServices/ContextUtil.xml +++ b/xml/System.EnterpriseServices/ContextUtil.xml @@ -18,20 +18,20 @@ Obtains information about the COM+ object context. This class cannot be inherited. - is the preferred class to use for obtaining COM+ context information. Because the members of this class are all `static` (`shared` in Visual Basic), it is not necessary to instantiate it before using them. - - - -## Examples - The following code example demonstrates how to use to create a transactional . - + is the preferred class to use for obtaining COM+ context information. Because the members of this class are all `static` (`shared` in Visual Basic), it is not necessary to instantiate it before using them. + + + +## Examples + The following code example demonstrates how to use to create a transactional . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Transaction/CPP/transaction.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/Overview/transaction.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/Overview/transaction.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/Overview/transaction.vb" id="Snippet1"::: + ]]> @@ -57,15 +57,15 @@ Gets a GUID representing the activity containing the component. The GUID for an activity if the current context is part of an activity; otherwise, . - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesContextUtil/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ActivityId/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet1"::: + ]]> There is no COM+ context available. @@ -92,15 +92,15 @@ Gets a GUID for the current application. The GUID for the current application. - There is no COM+ context available. @@ -128,15 +128,15 @@ Gets a GUID for the current application instance. The GUID for the current application instance. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesContextUtil/CPP/class1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ActivityId/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet2"::: + ]]> There is no COM+ context available. @@ -164,15 +164,15 @@ Gets a GUID for the current context. The GUID for the current context. - There is no COM+ context available. @@ -200,20 +200,20 @@ if the object is to be deactivated when the method returns; otherwise, . The default is . - property to ensure that a is deactivated after a method call. - + property to ensure that a is deactivated after a method call. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Transaction/CPP/transaction.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/Overview/transaction.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/Overview/transaction.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/Overview/transaction.vb" id="Snippet1"::: + ]]> There is no COM+ context available. @@ -240,20 +240,20 @@ Sets both the bit and the bit to in the COM+ context. - method. - + method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesContextUtil/CPP/class1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ActivityId/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet3"::: + ]]> No COM+ context is available. @@ -280,20 +280,20 @@ Sets the bit to and the bit to in the COM+ context. - method. - + method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesContextUtil/CPP/class1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ActivityId/class1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet4"::: + ]]> No COM+ context is available. @@ -324,11 +324,11 @@ Returns a named property from the COM+ context. The named property for the context. - There is no COM+ context available. @@ -410,15 +410,15 @@ if the current context is transactional; otherwise, . - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesContextUtil/CPP/class1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ActivityId/class1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet5"::: + ]]> There is no COM+ context available. @@ -446,15 +446,15 @@ if the current context has security enabled; otherwise, . - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesContextUtil/CPP/class1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ActivityId/class1.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet6"::: + ]]> There is no COM+ context available. @@ -481,22 +481,22 @@ Gets or sets the bit in the COM+ context. One of the values, either or . - is set to `Commit`, the COM+ `consistent` bit is set to `true` and the COM+ context votes to commit the transaction. If is set to `Abort`, the `consistent` bit is set to `false` and the COM+ context votes to abort the transaction. The default value of the `consistent` bit is `true`. - - The `consistent` bit casts a vote to commit or abort the transaction in which it executes, and the `done` bit finalizes the vote. COM+ inspects the `consistent` bit when the `done` bit is set to `true` on a method call return or when the object deactivates. Although an object's `consistent` bit can change repeatedly within each method call, only the last change counts. - - - -## Examples - The following code example demonstrates how to use property to create a transactional . - + is set to `Commit`, the COM+ `consistent` bit is set to `true` and the COM+ context votes to commit the transaction. If is set to `Abort`, the `consistent` bit is set to `false` and the COM+ context votes to abort the transaction. The default value of the `consistent` bit is `true`. + + The `consistent` bit casts a vote to commit or abort the transaction in which it executes, and the `done` bit finalizes the vote. COM+ inspects the `consistent` bit when the `done` bit is set to `true` on a method call return or when the object deactivates. Although an object's `consistent` bit can change repeatedly within each method call, only the last change counts. + + + +## Examples + The following code example demonstrates how to use property to create a transactional . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Transaction/CPP/transaction.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/Overview/transaction.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/Overview/transaction.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/Overview/transaction.vb" id="Snippet1"::: + ]]> There is no COM+ context available. @@ -548,20 +548,20 @@ Sets the bit to and the bit to in the COM+ context. - There is no COM+ context available. @@ -588,20 +588,20 @@ Sets the bit and the bit to in the COM+ context. - There is no COM+ context available. @@ -632,11 +632,11 @@ Object that represents the property value to set. Sets the named property for the COM+ context. - There is no COM+ context available. @@ -663,11 +663,11 @@ Gets the current transaction context. A that represents the current transaction context. - There is no COM+ context available. @@ -694,11 +694,11 @@ Gets an object describing the current COM+ DTC transaction. An object that represents the current transaction. - interface if the transaction is a COM+ DTC transaction. - + interface if the transaction is a COM+ DTC transaction. + ]]> There is no COM+ context available. @@ -725,15 +725,15 @@ Gets the GUID of the current COM+ DTC transaction. A GUID representing the current COM+ DTC transaction, if one exists. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesContextUtil/CPP/class1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ActivityId/class1.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ActivityId/class1.vb" id="Snippet7"::: + ]]> There is no COM+ context available. diff --git a/xml/System.EnterpriseServices/EventTrackingEnabledAttribute.xml b/xml/System.EnterpriseServices/EventTrackingEnabledAttribute.xml index 175a1409aa6..9fc65430cba 100644 --- a/xml/System.EnterpriseServices/EventTrackingEnabledAttribute.xml +++ b/xml/System.EnterpriseServices/EventTrackingEnabledAttribute.xml @@ -28,19 +28,19 @@ Enables event tracking for a component. This class cannot be inherited. - type. - + type. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.vb" id="Snippet0"::: + ]]> @@ -71,19 +71,19 @@ Initializes a new instance of the class, enabling event tracking. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.vb" id="Snippet1"::: + ]]> @@ -110,14 +110,14 @@ to enable event tracking; otherwise, . Initializes a new instance of the class, optionally disabling event tracking. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.vb" id="Snippet2"::: + ]]> @@ -144,14 +144,14 @@ if tracking is enabled; otherwise, . The default is . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/EventTrackingEnabledAttribute/Overview/class1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.EnterpriseServices/ExceptionClassAttribute.xml b/xml/System.EnterpriseServices/ExceptionClassAttribute.xml index 8f7581f335d..15d143bd1e9 100644 --- a/xml/System.EnterpriseServices/ExceptionClassAttribute.xml +++ b/xml/System.EnterpriseServices/ExceptionClassAttribute.xml @@ -28,18 +28,18 @@ Sets the queuing exception class for the queued class. This class cannot be inherited. - type. - - :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ExceptionClassAttribute/Overview/class1.cs" id="Snippet0"::: - + type. + + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ExceptionClassAttribute/Overview/class1.cs" id="Snippet0"::: + ]]> @@ -65,13 +65,13 @@ The name of the exception class for the player to activate and play back before the message is routed to the dead letter queue. Initializes a new instance of the class. - . - - :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ExceptionClassAttribute/Overview/class1.cs" id="Snippet1"::: - + . + + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ExceptionClassAttribute/Overview/class1.cs" id="Snippet1"::: + ]]> @@ -97,13 +97,13 @@ Gets the name of the exception class for the player to activate and play back before the message is routed to the dead letter queue. The name of the exception class for the player to activate and play back before the message is routed to the dead letter queue. - property. - - :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ExceptionClassAttribute/Overview/class1.cs" id="Snippet2"::: - + property. + + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ExceptionClassAttribute/Overview/class1.cs" id="Snippet2"::: + ]]> diff --git a/xml/System.EnterpriseServices/JustInTimeActivationAttribute.xml b/xml/System.EnterpriseServices/JustInTimeActivationAttribute.xml index 651a8f73834..9a2d16048ae 100644 --- a/xml/System.EnterpriseServices/JustInTimeActivationAttribute.xml +++ b/xml/System.EnterpriseServices/JustInTimeActivationAttribute.xml @@ -28,24 +28,24 @@ Turns just-in-time (JIT) activation on or off. This class cannot be inherited. - @@ -76,14 +76,14 @@ Initializes a new instance of the class. The parameterless constructor enables just-in-time (JIT) activation. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/JustInTimeActivationAttribute/.ctor/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/JustInTimeActivationAttribute/.ctor/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/JustInTimeActivationAttribute/.ctor/class1.vb" id="Snippet1"::: + ]]> @@ -110,19 +110,19 @@ to enable JIT activation; otherwise, . Initializes a new instance of the class, optionally allowing the disabling of just-in-time (JIT) activation by passing as the parameter. - value for the transaction is `Supported`, `Required`, or `RequiresNew`. - - - -## Examples - The following code example creates a new . - + value for the transaction is `Supported`, `Required`, or `RequiresNew`. + + + +## Examples + The following code example creates a new . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/JustInTimeActivationAttribute/.ctor/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/JustInTimeActivationAttribute/.ctor/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/JustInTimeActivationAttribute/.ctor/class1.vb" id="Snippet2"::: + ]]> @@ -149,14 +149,14 @@ if JIT activation is enabled; otherwise, . The default is . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/JustInTimeActivationAttribute/.ctor/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/JustInTimeActivationAttribute/.ctor/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/JustInTimeActivationAttribute/.ctor/class1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.EnterpriseServices/LoadBalancingSupportedAttribute.xml b/xml/System.EnterpriseServices/LoadBalancingSupportedAttribute.xml index 8b0e3664595..61570b0e038 100644 --- a/xml/System.EnterpriseServices/LoadBalancingSupportedAttribute.xml +++ b/xml/System.EnterpriseServices/LoadBalancingSupportedAttribute.xml @@ -28,14 +28,14 @@ Determines whether the component participates in load balancing, if the component load balancing service is installed and enabled on the server. - type. - + type. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.vb" id="Snippet0"::: + ]]> @@ -66,14 +66,14 @@ Initializes a new instance of the class, specifying load balancing support. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.vb" id="Snippet1"::: + ]]> @@ -100,14 +100,14 @@ to enable load balancing support; otherwise, . Initializes a new instance of the class, optionally disabling load balancing support. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.vb" id="Snippet2"::: + ]]> @@ -134,14 +134,14 @@ if load balancing support is enabled; otherwise, . The default is . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/LoadBalancingSupportedAttribute/Overview/class1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.EnterpriseServices/MustRunInClientContextAttribute.xml b/xml/System.EnterpriseServices/MustRunInClientContextAttribute.xml index bf7876cecaa..dbb3b796857 100644 --- a/xml/System.EnterpriseServices/MustRunInClientContextAttribute.xml +++ b/xml/System.EnterpriseServices/MustRunInClientContextAttribute.xml @@ -28,21 +28,21 @@ Forces the attributed object to be created in the context of the creator, if possible. This class cannot be inherited. - is thrown when an attempt is made to create the object. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following code example demonstrates the use of the type. - + is thrown when an attempt is made to create the object. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following code example demonstrates the use of the type. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.vb" id="Snippet0"::: + ]]> @@ -73,14 +73,14 @@ Initializes a new instance of the class, requiring creation of the object in the context of the creator. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.vb" id="Snippet1"::: + ]]> @@ -107,14 +107,14 @@ to create the object in the context of the creator; otherwise, . Initializes a new instance of the class, optionally not creating the object in the context of the creator. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.vb" id="Snippet2"::: + ]]> @@ -141,14 +141,14 @@ if the object is to be created in the context of the creator; otherwise, . The default is . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/MustRunInClientContextAttribute/Overview/class1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.EnterpriseServices/ObjectPoolingAttribute.xml b/xml/System.EnterpriseServices/ObjectPoolingAttribute.xml index d29b1d5cd13..95a2763377f 100644 --- a/xml/System.EnterpriseServices/ObjectPoolingAttribute.xml +++ b/xml/System.EnterpriseServices/ObjectPoolingAttribute.xml @@ -28,24 +28,24 @@ Enables and configures object pooling for a component. This class cannot be inherited. - , see the constructor. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following code example demonstrates the use of this attribute. - + , see the constructor. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following code example demonstrates the use of this attribute. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Pooling/CPP/inspector.cpp" id="Snippet0"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.vb" id="Snippet0"::: + ]]> @@ -76,27 +76,27 @@ Initializes a new instance of the class and sets the , , , and properties to their default values. - . - -|Property|Value| -|--------------|-----------| -|Enabled|`true`| -|MaxPoolSize|-1| -|MinPoolSize|-1| -|CreationTimeout|-1| - - - -## Examples - The following code example demonstrates the use of this attribute. - + . + +|Property|Value| +|--------------|-----------| +|Enabled|`true`| +|MaxPoolSize|-1| +|MinPoolSize|-1| +|CreationTimeout|-1| + + + +## Examples + The following code example demonstrates the use of this attribute. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Pooling/CPP/inspector.cpp" id="Snippet0"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.vb" id="Snippet0"::: + ]]> @@ -123,15 +123,15 @@ to enable object pooling; otherwise, . Initializes a new instance of the class and sets the property. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesObjectPoolingAttribute/cpp/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.vb" id="Snippet1"::: + ]]> @@ -159,15 +159,15 @@ The maximum pool size. Initializes a new instance of the class and sets the and properties. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesObjectPoolingAttribute/cpp/class1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.vb" id="Snippet3"::: + ]]> @@ -198,15 +198,15 @@ The maximum pool size. Initializes a new instance of the class and sets the , , and properties. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesObjectPoolingAttribute/cpp/class1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.vb" id="Snippet2"::: + ]]> @@ -237,11 +237,11 @@ if the method has made changes. - method is intended only to be used from within the .NET Framework infrastructure. It is sufficient for a developer to apply the class attribute and set other members in its interface. - + method is intended only to be used from within the .NET Framework infrastructure. It is sufficient for a developer to apply the class attribute and set other members in its interface. + ]]> @@ -272,11 +272,11 @@ if the method has made changes; otherwise, . - method is intended only to be used from within the .NET Framework infrastructure. It is sufficient for a developer to apply the class attribute and set other members in its interface. - + method is intended only to be used from within the .NET Framework infrastructure. It is sufficient for a developer to apply the class attribute and set other members in its interface. + ]]> @@ -302,20 +302,20 @@ Gets or sets the length of time to wait for an object to become available in the pool before throwing an exception. This value is in milliseconds. The time-out value in milliseconds. - @@ -342,15 +342,15 @@ if object pooling is enabled; otherwise, . The default is . - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServicesObjectPoolingAttribute/cpp/class1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ObjectPoolingAttribute/.ctor/class1.vb" id="Snippet4"::: + ]]> @@ -381,11 +381,11 @@ if the attribute is applied to a serviced component class. - method is intended only to be used from within the .NET Framework infrastructure. It is sufficient for a developer to apply the class attribute and set other members in its interface. - + method is intended only to be used from within the .NET Framework infrastructure. It is sufficient for a developer to apply the class attribute and set other members in its interface. + ]]> @@ -411,20 +411,20 @@ Gets or sets the value for the maximum size of the pool. The maximum number of objects in the pool. - represents the maximum number of pooled objects that the pooling manager will create, both actively used by clients and inactive in the pool. When creating objects, the pooling manager checks to verify that the maximum pool size has not been reached and, if it has not, the pooling manager creates a new object to dispense to the client. If the maximum pool size has been reached, client requests are queued and receive the first available object from the pool in the order in which they arrived. Object creation requests time-out after a specified period. - - - -## Examples - The following code example demonstrates the use of this property. - + represents the maximum number of pooled objects that the pooling manager will create, both actively used by clients and inactive in the pool. When creating objects, the pooling manager checks to verify that the maximum pool size has not been reached and, if it has not, the pooling manager creates a new object to dispense to the client. If the maximum pool size has been reached, client requests are queued and receive the first available object from the pool in the order in which they arrived. Object creation requests time-out after a specified period. + + + +## Examples + The following code example demonstrates the use of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Pooling/CPP/inspector.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.vb" id="Snippet1"::: + ]]> @@ -450,20 +450,20 @@ Gets or sets the value for the minimum size of the pool. The minimum number of objects in the pool. - represents the number of objects that are created when the application starts and the minimum number of objects that are maintained in the pool while the application is running. If the number of available objects in the pool drops below the specified minimum, new objects are created to meet any outstanding object requests and refill the pool. If the number of available objects in the pool is greater than the minimum number, those surplus objects are destroyed during a clean-up cycle. - - - -## Examples - The following code example demonstrates the use of this property. - + represents the number of objects that are created when the application starts and the minimum number of objects that are maintained in the pool while the application is running. If the number of available objects in the pool drops below the specified minimum, new objects are created to meet any outstanding object requests and refill the pool. If the number of available objects in the pool is greater than the minimum number, those surplus objects are destroyed during a clean-up cycle. + + + +## Examples + The following code example demonstrates the use of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Pooling/CPP/inspector.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/ApplicationId/inspector.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.EnterpriseServices/RegistrationException.xml b/xml/System.EnterpriseServices/RegistrationException.xml index 2b3ef53d1ef..cbeda8caa40 100644 --- a/xml/System.EnterpriseServices/RegistrationException.xml +++ b/xml/System.EnterpriseServices/RegistrationException.xml @@ -24,15 +24,15 @@ The exception that is thrown when a registration error is detected. - @@ -132,11 +132,11 @@ Gets an array of objects that describe registration errors. The array of objects. - property. - + property. + ]]> diff --git a/xml/System.EnterpriseServices/SecurityCallContext.xml b/xml/System.EnterpriseServices/SecurityCallContext.xml index 9714178bce2..9f84d4a5e8d 100644 --- a/xml/System.EnterpriseServices/SecurityCallContext.xml +++ b/xml/System.EnterpriseServices/SecurityCallContext.xml @@ -18,15 +18,15 @@ Describes the chain of callers leading up to the current method call. - class to interrogate the security context of calls to the methods of a class. - + class to interrogate the security context of calls to the methods of a class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Security/CPP/employeeinformation.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet4"::: + ]]> @@ -52,11 +52,11 @@ Gets a object that describes the caller. The object that describes the caller. - accesses the `Callers` item in the `ISecurityCallContext` collection in COM+. - + accesses the `Callers` item in the `ISecurityCallContext` collection in COM+. + ]]> There is no security context. @@ -83,20 +83,20 @@ Gets a object that describes the security call context. The object that describes the security call context. - property is the recommended way to access the security call context. - - - -## Examples - The following code example demonstrates the use of this method to obtain a object describing the security context of a method call. - + property is the recommended way to access the security call context. + + + +## Examples + The following code example demonstrates the use of this method to obtain a object describing the security context of a method call. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Security/CPP/employeeinformation.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet6"::: + ]]> @@ -122,15 +122,15 @@ Gets a object that describes the direct caller of this method. A value. - method. - + method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Security/CPP/employeeinformation.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet7"::: + ]]> @@ -161,15 +161,15 @@ if the direct caller is a member of the specified role; otherwise, . - method is in a specified role. - + method is in a specified role. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Security/CPP/employeeinformation.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet6"::: + ]]> @@ -249,11 +249,11 @@ Gets the value from the collection in COM+. The value from the collection in COM+. - is the least secure authentication level of all callers in the chain. - + is the least secure authentication level of all callers in the chain. + ]]> @@ -279,11 +279,11 @@ Gets the value from the collection in COM+. The value from the collection in COM+. - is the number of callers in the chain of calls. - + is the number of callers in the chain of calls. + ]]> diff --git a/xml/System.EnterpriseServices/SecurityRoleAttribute.xml b/xml/System.EnterpriseServices/SecurityRoleAttribute.xml index b3cf6f6d16b..e8763cc74b8 100644 --- a/xml/System.EnterpriseServices/SecurityRoleAttribute.xml +++ b/xml/System.EnterpriseServices/SecurityRoleAttribute.xml @@ -28,26 +28,26 @@ Configures a role for an application or component. This class cannot be inherited. - to add roles to an application, and to associate them with components. When is applied to an assembly as a whole, it ensures that the role exists in the application configuration (COM+ catalog). You can add members of the role using the COM+ Explorer. - - When applied to a component, the ensures that the role exists in the application configuration, and associates the target component with the role. - - By default, created roles have no members. If the property is set to `true`, the Everyone user group is automatically added to the role. This is best for all-access type roles that are given minimal control over the system. - - Security roles can be specified at the component level, per interface and per method. As with other method attributes, security configuration is not currently shared between interface definition and method implementation. - - - -## Examples - The following code example demonstrates the use of this attribute to associate a role with an assembly that contains classes. - + to add roles to an application, and to associate them with components. When is applied to an assembly as a whole, it ensures that the role exists in the application configuration (COM+ catalog). You can add members of the role using the COM+ Explorer. + + When applied to a component, the ensures that the role exists in the application configuration, and associates the target component with the role. + + By default, created roles have no members. If the property is set to `true`, the Everyone user group is automatically added to the role. This is best for all-access type roles that are given minimal control over the system. + + Security roles can be specified at the component level, per interface and per method. As with other method attributes, security configuration is not currently shared between interface definition and method implementation. + + + +## Examples + The following code example demonstrates the use of this attribute to associate a role with an assembly that contains classes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Security/CPP/employeeinformation.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet3"::: + ]]> @@ -82,15 +82,15 @@ A security role for the application, component, interface, or method. Initializes a new instance of the class and sets the property. - classes. - + classes. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Security/CPP/employeeinformation.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/AccessChecksLevelOption/Overview/employeeinformation.vb" id="Snippet3"::: + ]]> @@ -189,11 +189,11 @@ to require that a newly created role have the Everyone user group added as a user (roles that already exist on the application are not modified); otherwise, to suppress adding the Everyone user group as a user. - diff --git a/xml/System.EnterpriseServices/ServiceConfig.xml b/xml/System.EnterpriseServices/ServiceConfig.xml index 00bd98f0a4b..0dcc3093d07 100644 --- a/xml/System.EnterpriseServices/ServiceConfig.xml +++ b/xml/System.EnterpriseServices/ServiceConfig.xml @@ -368,7 +368,7 @@ ## Remarks Configures side-by-side assemblies for this . - You must set the property, if you create a new side-by-side assembly by setting the property to . + You must set the property, if you create a new side-by-side assembly by setting the property to . ]]> @@ -490,7 +490,7 @@ is similar to the property but allows the enclosed code to run as an existing transaction that is specified by a TIP URL. + is similar to the property but allows the enclosed code to run as an existing transaction that is specified by a TIP URL. ]]> diff --git a/xml/System.EnterpriseServices/SynchronizationAttribute.xml b/xml/System.EnterpriseServices/SynchronizationAttribute.xml index 85586808b03..711cd3b7093 100644 --- a/xml/System.EnterpriseServices/SynchronizationAttribute.xml +++ b/xml/System.EnterpriseServices/SynchronizationAttribute.xml @@ -28,23 +28,23 @@ Sets the synchronization value of the component. This class cannot be inherited. - to a context-bound object results in the creation of a wait handle and auto reset event, which are not deterministically garbage collected. Therefore, you should not create a large number of context-bound objects marked with the `SynchronizationAttribute` within a short time period. - - - -## Examples - The following code example demonstrates the use of the type. - + to a context-bound object results in the creation of a wait handle and auto reset event, which are not deterministically garbage collected. Therefore, you should not create a large number of context-bound objects marked with the `SynchronizationAttribute` within a short time period. + + + +## Examples + The following code example demonstrates the use of the type. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.vb" id="Snippet0"::: + ]]> @@ -75,19 +75,19 @@ Initializes a new instance of the class with the default . - property is set to the default value . - - - -## Examples - The following code example creates a new . - + property is set to the default value . + + + +## Examples + The following code example creates a new . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.vb" id="Snippet1"::: + ]]> @@ -113,14 +113,14 @@ One of the values. Initializes a new instance of the class with the specified . - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.vb" id="Snippet2"::: + ]]> @@ -146,14 +146,14 @@ Gets the current setting of the property. One of the values. The default is . - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/SynchronizationAttribute/Overview/class1.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.EnterpriseServices/TransactionAttribute.xml b/xml/System.EnterpriseServices/TransactionAttribute.xml index 700b75cf754..8c550c0c0cc 100644 --- a/xml/System.EnterpriseServices/TransactionAttribute.xml +++ b/xml/System.EnterpriseServices/TransactionAttribute.xml @@ -28,22 +28,22 @@ Specifies the type of transaction that is available to the attributed object. Permissible values are members of the enumeration. - as transactional. - + as transactional. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/EnterpriseServices_Transaction/CPP/transaction.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/ContextUtil/Overview/transaction.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/Overview/transaction.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/ContextUtil/Overview/transaction.vb" id="Snippet1"::: + ]]> @@ -74,14 +74,14 @@ Initializes a new instance of the class, setting the component's requested transaction type to . - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/TransactionAttribute/.ctor/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/TransactionAttribute/.ctor/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/TransactionAttribute/.ctor/class1.vb" id="Snippet1"::: + ]]> @@ -107,14 +107,14 @@ The specified transaction type, a value. Initializes a new instance of the class, specifying the transaction type. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/TransactionAttribute/.ctor/class1.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/TransactionAttribute/.ctor/class1.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/TransactionAttribute/.ctor/class1.vb" id="Snippet2"::: + ]]> @@ -140,14 +140,14 @@ Gets or sets the transaction isolation level. One of the values. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/TransactionAttribute/.ctor/class1.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/TransactionAttribute/.ctor/class1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/TransactionAttribute/.ctor/class1.vb" id="Snippet3"::: + ]]> @@ -173,14 +173,14 @@ Gets or sets the time-out for this transaction. The transaction time-out in seconds. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/TransactionAttribute/.ctor/class1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/TransactionAttribute/.ctor/class1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/TransactionAttribute/.ctor/class1.vb" id="Snippet4"::: + ]]> @@ -206,14 +206,14 @@ Gets the value for the transaction, optionally disabling the transaction service. The specified transaction type, a value. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.EnterpriseServices/TransactionAttribute/.ctor/class1.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/TransactionAttribute/.ctor/class1.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.EnterpriseServices/TransactionAttribute/.ctor/class1.vb" id="Snippet5"::: + ]]> diff --git a/xml/System.Globalization/Calendar.xml b/xml/System.Globalization/Calendar.xml index e0501693d5c..41cafffad42 100644 --- a/xml/System.Globalization/Calendar.xml +++ b/xml/System.Globalization/Calendar.xml @@ -281,7 +281,7 @@ The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . The time-of-day part of the resulting remains the same as the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet1"::: @@ -367,7 +367,7 @@ The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet2"::: @@ -453,7 +453,7 @@ The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet3"::: @@ -539,7 +539,7 @@ The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet4"::: @@ -629,7 +629,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -715,7 +715,7 @@ The day part of the resulting is affected if the resulting time is outside the day of the specified . The month part of the resulting is affected if the resulting day is outside the month of the specified . The year part of the resulting is affected if the resulting month is outside the year of the specified . The era part of the resulting is affected if the resulting year is outside the era of the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet6"::: @@ -803,7 +803,7 @@ In all .NET classes derived from the class, a week is defined as seven days. - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet7"::: @@ -893,7 +893,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -972,7 +972,7 @@ type found in .NET and displays the value of its property. + The following example uses reflection to instantiate each type found in .NET and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -2563,11 +2563,11 @@ Only the and the object for a particular culture that uses the calendar indicated by the property includes the following culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters: + The object for a particular culture that uses the calendar indicated by the property includes the following culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters: -- The property contains the default first day of the week that can be used for the `firstDayOfWeek` parameter. +- The property contains the default first day of the week that can be used for the `firstDayOfWeek` parameter. -- The property contains the default calendar week rule that can be used for the `rule` parameter. +- The property contains the default calendar week rule that can be used for the `rule` parameter. > [!NOTE] > This does not map exactly to ISO 8601. The differences are discussed in the blog entry [ISO 8601 Week of Year format in Microsoft .NET](https://go.microsoft.com/fwlink/?LinkId=160851). Starting with .NET Core 3.0, and solve this problem. @@ -2577,7 +2577,7 @@ Only the and the method throws an for particular combinations of `rule` and `firstDayOfWeek` values even if `time` is greater than the date returned by that calendar's property. The following table lists the affected calendars, the specific `rule` values, and the range of the earliest supported `time` values. The specific minimum value depends on the value of the `firstDayOfWeek` parameter. + For some calendars, a call to the method throws an for particular combinations of `rule` and `firstDayOfWeek` values even if `time` is greater than the date returned by that calendar's property. The following table lists the affected calendars, the specific `rule` values, and the range of the earliest supported `time` values. The specific minimum value depends on the value of the `firstDayOfWeek` parameter. |Calendar|CalendarWeekRule value|Gregorian date (M/dd/yyyy)|Date in calendar (M/dd/yyyy)| |--------------|----------------------------|------------------------------------|--------------------------------------| diff --git a/xml/System.Globalization/CalendarAlgorithmType.xml b/xml/System.Globalization/CalendarAlgorithmType.xml index dbbcb0bfde5..b9fbbf91dcf 100644 --- a/xml/System.Globalization/CalendarAlgorithmType.xml +++ b/xml/System.Globalization/CalendarAlgorithmType.xml @@ -55,13 +55,13 @@ ## Remarks A date calculation for a particular calendar depends on whether the calendar is solar-based, lunar-based, or lunisolar-based. For example, the , , and classes are solar-based, the and classes are lunar-based,.and the and classes are lunisolar-based, thus using solar calculations for the year and lunar calculations for the month and day. - A value, which is returned by a calendar member such as the property, specifies the foundation for a particular calendar. + A value, which is returned by a calendar member such as the property, specifies the foundation for a particular calendar. ## Examples - The following code example demonstrates the property and the enumeration. - + The following code example demonstrates the property and the enumeration. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/CalendarAlgorithmType/Overview/caltype.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CalendarAlgorithmType/Overview/caltype.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/CalendarWeekRule.xml b/xml/System.Globalization/CalendarWeekRule.xml index 784600c879b..83de13a34a2 100644 --- a/xml/System.Globalization/CalendarWeekRule.xml +++ b/xml/System.Globalization/CalendarWeekRule.xml @@ -72,58 +72,58 @@ Defines different rules for determining the first week of the year. - enumeration is returned by the property and is used by the culture's current calendar to determine the calendar week rule. The enumeration value is also used as a parameter to the method. - - Calendar week rules depend on the value that indicates the first day of the week in addition to depending on a value. The property provides the default value for a culture, but any value can be specified as the first day of the week in the method. - - The first week based on the `FirstDay` value can have one to seven days. The first week based on the `FirstFullWeek` value always has seven days. The first week based on the `FirstFourDayWeek` value can have four to seven days. - - For example, in the Gregorian calendar, suppose that the first day of the year (January 1) falls on a Tuesday and the designated first day of the week is Sunday. Selecting `FirstFullWeek` defines the first Sunday (January 6) as the beginning of the first week of the year. The first five days of the year are considered part of the last week of the previous year. In contrast, selecting `FirstFourDayWeek` defines the first day of the year (January 1) as the beginning of the first week of the year because there are more than four days from January 1 to the day before the following Sunday. - -|Date|FirstDay|FirstFullWeek|FirstFourDayWeek| -|----------|--------------|-------------------|----------------------| -|Dec 31 Mon|Last week of the previous year|Last week of the previous year|Last week of the previous year| -|Jan 1 Tue|Week 1|Last week of the previous year|Week 1| -|Jan 2 Wed|Week 1|Last week of the previous year|Week 1| -|Jan 3 Thu|Week 1|Last week of the previous year|Week 1| -|Jan 4 Fri|Week 1|Last week of the previous year|Week 1| -|Jan 5 Sat|Week 1|Last week of the previous year|Week 1| -|Jan 6 Sun|Week 2|Week 1|Week 2| -|Jan 7 Mon|Week 2|Week 1|Week 2| -|Jan 8 Tue|Week 2|Week 1|Week 2| -|Jan 9 Wed|Week 2|Week 1|Week 2| -|Jan 10 Thu|Week 2|Week 1|Week 2| -|Jan 11 Fri|Week 2|Week 1|Week 2| -|Jan 12 Sat|Week 2|Week 1|Week 2| - - Suppose the first day of the year (January 1) falls on a Friday and the designated first day of the week is Sunday. Selecting `FirstFourDayWeek` defines the first Sunday (January 3) as the beginning of the first week of the year because there are fewer than four days from January 1 to the day before the following Sunday. - -|Date|FirstDay|FirstFullWeek|FirstFourDayWeek| -|----------|--------------|-------------------|----------------------| -|Dec 31 Thu|Last week of the previous year|Last week of the previous year|Last week of the previous year| -|Jan 1 Fri|Week 1|Last week of the previous year|Last week of the previous year| -|Jan 2 Sat|Week 1|Last week of the previous year|Last week of the previous year| -|Jan 3 Sun|Week 2|Week 1|Week 1| -|Jan 4 Mon|Week 2|Week 1|Week 1| -|Jan 5 Tue|Week 2|Week 1|Week 1| -|Jan 6 Wed|Week 2|Week 1|Week 1| -|Jan 7 Thu|Week 2|Week 1|Week 1| -|Jan 8 Fri|Week 2|Week 1|Week 1| -|Jan 9 Sat|Week 2|Week 1|Week 1| - - The following example illustrates how the and values are used together to determine how weeks are assigned. In the Gregorian calendar, the first day of the year (January 1) in 2013 falls on a Tuesday. If the designated first day of the week is Sunday, the first Sunday (January 6) is the first day of the first week of the year, and Saturday (January 5) belongs to the fifty-third week of the previous year. Changing the calendar week rule to `FirstFourDayWeek` defines Tuesday (January 1) as the beginning of the first week of the year, because there are more than four days between Tuesday, January 1, and Sunday, January 6. Using this rule, January 5 belongs to the first week of the year. For 2010, a year in which January 1 falls on a Friday, applying the `FirstFourDayWeek` rule with as the first day of the week makes Sunday, January 3 the beginning of the first week of the year, because the first week in 2010 that has more than four days is January 3 through 9. - + enumeration is returned by the property and is used by the culture's current calendar to determine the calendar week rule. The enumeration value is also used as a parameter to the method. + + Calendar week rules depend on the value that indicates the first day of the week in addition to depending on a value. The property provides the default value for a culture, but any value can be specified as the first day of the week in the method. + + The first week based on the `FirstDay` value can have one to seven days. The first week based on the `FirstFullWeek` value always has seven days. The first week based on the `FirstFourDayWeek` value can have four to seven days. + + For example, in the Gregorian calendar, suppose that the first day of the year (January 1) falls on a Tuesday and the designated first day of the week is Sunday. Selecting `FirstFullWeek` defines the first Sunday (January 6) as the beginning of the first week of the year. The first five days of the year are considered part of the last week of the previous year. In contrast, selecting `FirstFourDayWeek` defines the first day of the year (January 1) as the beginning of the first week of the year because there are more than four days from January 1 to the day before the following Sunday. + +|Date|FirstDay|FirstFullWeek|FirstFourDayWeek| +|----------|--------------|-------------------|----------------------| +|Dec 31 Mon|Last week of the previous year|Last week of the previous year|Last week of the previous year| +|Jan 1 Tue|Week 1|Last week of the previous year|Week 1| +|Jan 2 Wed|Week 1|Last week of the previous year|Week 1| +|Jan 3 Thu|Week 1|Last week of the previous year|Week 1| +|Jan 4 Fri|Week 1|Last week of the previous year|Week 1| +|Jan 5 Sat|Week 1|Last week of the previous year|Week 1| +|Jan 6 Sun|Week 2|Week 1|Week 2| +|Jan 7 Mon|Week 2|Week 1|Week 2| +|Jan 8 Tue|Week 2|Week 1|Week 2| +|Jan 9 Wed|Week 2|Week 1|Week 2| +|Jan 10 Thu|Week 2|Week 1|Week 2| +|Jan 11 Fri|Week 2|Week 1|Week 2| +|Jan 12 Sat|Week 2|Week 1|Week 2| + + Suppose the first day of the year (January 1) falls on a Friday and the designated first day of the week is Sunday. Selecting `FirstFourDayWeek` defines the first Sunday (January 3) as the beginning of the first week of the year because there are fewer than four days from January 1 to the day before the following Sunday. + +|Date|FirstDay|FirstFullWeek|FirstFourDayWeek| +|----------|--------------|-------------------|----------------------| +|Dec 31 Thu|Last week of the previous year|Last week of the previous year|Last week of the previous year| +|Jan 1 Fri|Week 1|Last week of the previous year|Last week of the previous year| +|Jan 2 Sat|Week 1|Last week of the previous year|Last week of the previous year| +|Jan 3 Sun|Week 2|Week 1|Week 1| +|Jan 4 Mon|Week 2|Week 1|Week 1| +|Jan 5 Tue|Week 2|Week 1|Week 1| +|Jan 6 Wed|Week 2|Week 1|Week 1| +|Jan 7 Thu|Week 2|Week 1|Week 1| +|Jan 8 Fri|Week 2|Week 1|Week 1| +|Jan 9 Sat|Week 2|Week 1|Week 1| + + The following example illustrates how the and values are used together to determine how weeks are assigned. In the Gregorian calendar, the first day of the year (January 1) in 2013 falls on a Tuesday. If the designated first day of the week is Sunday, the first Sunday (January 6) is the first day of the first week of the year, and Saturday (January 5) belongs to the fifty-third week of the previous year. Changing the calendar week rule to `FirstFourDayWeek` defines Tuesday (January 1) as the beginning of the first week of the year, because there are more than four days between Tuesday, January 1, and Sunday, January 6. Using this rule, January 5 belongs to the first week of the year. For 2010, a year in which January 1 falls on a Friday, applying the `FirstFourDayWeek` rule with as the first day of the week makes Sunday, January 3 the beginning of the first week of the year, because the first week in 2010 that has more than four days is January 3 through 9. + :::code language="csharp" source="~/snippets/csharp/System.Globalization/CalendarWeekRule/Overview/calendarweekruleex.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CalendarWeekRule/Overview/calendarweekruleex.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CalendarWeekRule/Overview/calendarweekruleex.vb" id="Snippet1"::: + > [!NOTE] > This does not map exactly to ISO 8601. The differences are discussed in the blog entry [ISO 8601 Week of Year format in Microsoft .NET](https://go.microsoft.com/fwlink/?LinkId=160851). Starting with .NET Core 3.0, and solve this problem. - - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , set the property of to a new . - + + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , set the property of to a new . + ]]> diff --git a/xml/System.Globalization/ChineseLunisolarCalendar.xml b/xml/System.Globalization/ChineseLunisolarCalendar.xml index 920a9f6ac71..0f037ffaf77 100644 --- a/xml/System.Globalization/ChineseLunisolarCalendar.xml +++ b/xml/System.Globalization/ChineseLunisolarCalendar.xml @@ -71,20 +71,20 @@ Represents time in divisions, such as months, days, and years. Years are calculated using the Chinese calendar, while days and months are calculated using the lunisolar calendar. - class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. The class calculates years based on solar calculations, and months and days based on lunar calculations. - + class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. The class calculates years based on solar calculations, and months and days based on lunar calculations. + > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). - - A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. - - Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Chinese lunisolar calendar. - - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . - +> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). + + A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + + Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Chinese lunisolar calendar. + + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + ]]> Working with Calendars @@ -174,13 +174,13 @@ Specifies the era that corresponds to the current object. - class recognizes only the current era. - + class recognizes only the current era. + ]]> @@ -226,11 +226,11 @@ Gets the number of days in the year that precedes the year that is specified by the property. The number of days in the year that precedes the year specified by . - diff --git a/xml/System.Globalization/CompareInfo.xml b/xml/System.Globalization/CompareInfo.xml index 70d2711c8bc..f87a5f94181 100644 --- a/xml/System.Globalization/CompareInfo.xml +++ b/xml/System.Globalization/CompareInfo.xml @@ -197,7 +197,7 @@ . If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. + By default, the comparison is performed by using . If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. > [!NOTE] > When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -359,7 +359,7 @@ property to ensure that the behavior is consistent regardless of the culture settings of the operating system. + If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. > [!NOTE] > When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -469,7 +469,7 @@ property to ensure that the behavior is consistent regardless of the culture settings of the operating system. + If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. > [!NOTE] > When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -589,7 +589,7 @@ property to ensure that the behavior is consistent regardless of the culture settings of the operating system. + If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. > [!NOTE] > When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -708,7 +708,7 @@ property to ensure that the behavior is consistent regardless of the culture settings of the operating system. + If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. > [!NOTE] > When possible, you should use string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -846,7 +846,7 @@ property to ensure that the behavior is consistent regardless of the culture settings of the operating system. + If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. > [!NOTE] > When possible, you should call string comparison methods that have a parameter of type to specify the kind of comparison expected. As a general rule, use linguistic options (using the current culture) for comparing strings displayed in the user interface and specify or for security comparisons. @@ -952,7 +952,7 @@ This method overrides . - If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. + If a security decision depends on a string comparison or a case change, you should use the property to ensure that the behavior is consistent regardless of the culture settings of the operating system. ]]> @@ -5266,7 +5266,7 @@ This method has greater overhead than other property. + The following example demonstrates the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/CompareInfo/Overview/CompareInfo.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CompareInfo/Overview/CompareInfo.vb" id="Snippet1"::: @@ -5331,12 +5331,12 @@ This method has greater overhead than other and properties can have different values. For example, an property value of hexadecimal 0x10407 identifies an alternate sort culture that sorts names as they might appear in a German telephone book. The property has a value of "de-de_phoneb", whereas the property of the associated German (Germany) culture has a value of "de-DE". + The and properties can have different values. For example, an property value of hexadecimal 0x10407 identifies an alternate sort culture that sorts names as they might appear in a German telephone book. The property has a value of "de-de_phoneb", whereas the property of the associated German (Germany) culture has a value of "de-DE". ## Examples - The following example compares three strings using the fr-FR and ja-JP cultures. The property is used to display the name of each culture. + The following example compares three strings using the fr-FR and ja-JP cultures. The property is used to display the name of each culture. :::code language="csharp" source="~/snippets/csharp/System.Globalization/CompareInfo/Overview/CompareInfo.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CompareInfo/Overview/CompareInfo.vb" id="Snippet1"::: @@ -5453,7 +5453,7 @@ This method has greater overhead than other method. It returns a string that consists of the class name and the value of the instance property, separated by a hyphen. + This method overrides the method. It returns a string that consists of the class name and the value of the instance property, separated by a hyphen. ]]> @@ -5521,7 +5521,7 @@ This method has greater overhead than other object returned by the property doesn't identify the precise Unicode version used to compare strings. It is useful only when comparing two objects to determine whether they use the same Unicode version and culture to compare strings. For more information and an example, see the reference page. + The object returned by the property doesn't identify the precise Unicode version used to compare strings. It is useful only when comparing two objects to determine whether they use the same Unicode version and culture to compare strings. For more information and an example, see the reference page. ]]> diff --git a/xml/System.Globalization/CultureAndRegionInfoBuilder.xml b/xml/System.Globalization/CultureAndRegionInfoBuilder.xml index e6024c96746..3f8c3e9e9c6 100644 --- a/xml/System.Globalization/CultureAndRegionInfoBuilder.xml +++ b/xml/System.Globalization/CultureAndRegionInfoBuilder.xml @@ -145,7 +145,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. ]]> @@ -185,7 +185,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. The and objects that are assigned to the and properties both support culture-sensitive and case-sensitive string comparison. The object also has methods that include a parameter that supports culture-sensitive, case-insensitive comparison. These two properties should be assigned and objects that represent the same locale. @@ -219,11 +219,11 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the method. Specify `null` in a set operation to indicate that the culture defined by the current object is the alternate user interface culture. If you attempt to set the property to a culture that itself has a different Console Fallback UI Culture, then it will be assigned that final "leaf" culture. + In a get operation, the property corresponds to the method. Specify `null` in a set operation to indicate that the culture defined by the current object is the alternate user interface culture. If you attempt to set the property to a culture that itself has a different Console Fallback UI Culture, then it will be assigned that final "leaf" culture. Languages such as Arabic, Hebrew, Persian, Urdu and Syriac are based on bi-directional text. Windows applications, which employ a graphical user interface, support bi-directional languages. However, console applications, which employ the text user interface of the operating system console, do not provide bi-directional support. Consequently, if a console application is localized to Arabic or Hebrew, it displays unreadable text on the console screen. - The user interface culture specifies the resources that an application needs to support user input and output, and by default is the same as the operating system culture. For example, the property returns an Arabic culture for an Arabic operating system. The application should use the property to retrieve a neutral culture suitable for a console application user interface. + The user interface culture specifies the resources that an application needs to support user input and output, and by default is the same as the operating system culture. For example, the property returns an Arabic culture for an Arabic operating system. The application should use the property to retrieve a neutral culture suitable for a console application user interface. ]]> @@ -321,9 +321,9 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. - For example, the return value of the property for the specific culture English as spoken in the United States is "English (United States)". + For example, the return value of the property for the specific culture English as spoken in the United States is "English (United States)". The value of this property is the same, regardless of the language version of the .NET Framework. @@ -366,7 +366,7 @@ The following code example creates a custom culture with a private use prefix, t ## Remarks The return value is the name of the culture specified in the constructor. If the specified culture name is the same as an existing culture, except for case, the return value is the name of the existing culture, not the specified culture name. - The property corresponds to the property. + The property corresponds to the property. @@ -403,11 +403,11 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. The value of this property is the same, regardless of the language version of the .NET Framework. - The culture's full name might not display properly if the system is not set to display the culture's language correctly. For example, if the property is "ja-JP" for Japanese (Japan), the property does not display correctly on a system that is set to English only. However, multilingual operating systems, such as Windows 2000, display the property correctly. + The culture's full name might not display properly if the system is not set to display the culture's language correctly. For example, if the property is "ja-JP" for Japanese (Japan), the property does not display correctly on a system that is set to English only. However, multilingual operating systems, such as Windows 2000, display the property correctly. @@ -471,7 +471,7 @@ The following code example creates a custom culture with a private use prefix, t property is equivalent to the property. + The property is equivalent to the property. ]]> @@ -503,7 +503,7 @@ The following code example creates a custom culture with a private use prefix, t property is equivalent to the property. + The property is equivalent to the property. ]]> @@ -535,9 +535,9 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. - The application should use the property to provide culture-specific services to customers. For example, the property can be used as a key to access a database record that contains specific information about a region. + The application should use the property to provide culture-specific services to customers. For example, the property can be used as a key to access a database record that contains specific information about a region. ]]> @@ -567,7 +567,7 @@ The following code example creates a custom culture with a private use prefix, t object, contains a localized Gregorian calendar that is associated with a object. The object defines how your application displays dates and times. The property value is the object associated with the first localized Gregorian calendar returned by the property. + Every culture, including the culture defined by the current object, contains a localized Gregorian calendar that is associated with a object. The object defines how your application displays dates and times. The property value is the object associated with the first localized Gregorian calendar returned by the property. ]]> @@ -599,7 +599,7 @@ The following code example creates a custom culture with a private use prefix, t property gets or sets a culture name formatted according to RFC 4646, which can be different from the culture name returned by the property. For example, in the .NET Framework version 1.0, the neutral culture name for Traditional Chinese was "zh-CHT". In contrast, RFC 4646 defines that culture name as "zh-HANT". (Note that in the .NET Framework version 4, the Display Name for "zh-CHT" is "Chinese (Traditional) Legacy".) + The property gets or sets a culture name formatted according to RFC 4646, which can be different from the culture name returned by the property. For example, in the .NET Framework version 1.0, the neutral culture name for Traditional Chinese was "zh-CHT". In contrast, RFC 4646 defines that culture name as "zh-HANT". (Note that in the .NET Framework version 4, the Display Name for "zh-CHT" is "Chinese (Traditional) Legacy".) An RFC 4646 culture name consists of several components. A typical culture name consists of a mandatory language identifier, an optional script identifier, and an optional country/region identifier. For example, a valid RFC 4646 culture name for the Serbian language, the Cyrillic script, and the region of Serbia is "sr-Cyrl-RS". @@ -662,7 +662,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. A list of the three-character ISO 4217 currency symbols is provided in the class topic. For example, the ISO 4217 currency symbol for the United States dollar is "USD". @@ -697,9 +697,9 @@ The following code example creates a custom culture with a private use prefix, t property to determine the relative position of controls such as buttons and scroll bars in a graphical user interface. + The application uses the property to determine the relative position of controls such as buttons and scroll bars in a graphical user interface. - To access the predominant direction of text in a custom culture created from the current object, the application should use the property of the object returned by the property of the custom culture. + To access the predominant direction of text in a custom culture created from the current object, the application should use the property of the object returned by the property of the custom culture. ]]> @@ -728,7 +728,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. The input locale identifier was formerly called the keyboard layout. The identifier can be used for a speech-to-text converter, an Input Method Editor (IME), or any other form of input. @@ -760,7 +760,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. For replacement cultures the culture identifier is mapped to the corresponding National Language Support (NLS) locale identifier. For user-defined custom cultures, the value of this property is always hexadecimal 0x1000. @@ -846,7 +846,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. Your application should call this property only for specific cultures. @@ -924,7 +924,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. For example, the return value of for the United States is "United States". @@ -960,7 +960,7 @@ The following code example creates a custom culture with a private use prefix, t ## Remarks The return value is the name of the culture specified in the constructor. If the specified culture name is the same as an existing culture, except for case, the return value is the name of the existing culture, not the specified culture name. - The property corresponds to the property. + The property corresponds to the property. ]]> @@ -990,7 +990,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. ]]> @@ -1121,7 +1121,7 @@ The following code example creates a custom culture with a private use prefix, t property provides culture-specific casing information for strings. It corresponds to the property. + The property provides culture-specific casing information for strings. It corresponds to the property. The and objects that are assigned to the and properties both support culture-sensitive and case-sensitive string comparison. The object also has methods that include a parameter that supports culture-sensitive, case-insensitive comparison. These two properties should be assigned and objects that represent the same locale. @@ -1156,7 +1156,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. For example, the three-letter abbreviation for English is "eng". @@ -1190,9 +1190,9 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. - The property contains one of the three-letter codes defined in ISO 3166 for country/region. For example, the three-letter code for United States is "USA". + The property contains one of the three-letter codes defined in ISO 3166 for country/region. For example, the three-letter code for United States is "USA". Case is not significant. However, the , , and the properties contain the appropriate code in uppercase. @@ -1228,7 +1228,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. This property returns the same value as the Windows API method `GetLocaleInfo` with the LOCALE_SABBREVLANGNAME value. For example, the three-letter code for English (United States) as defined in the Windows API is "enu". @@ -1263,7 +1263,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. For example, the three-letter code for United States is "USA". @@ -1298,7 +1298,7 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. For example, the two-letter abbreviation for English is "en". @@ -1332,9 +1332,9 @@ The following code example creates a custom culture with a private use prefix, t property corresponds to the property. + The property corresponds to the property. - The property value is one of the two-letter codes defined in ISO 3166 for country/region. For example, the two-letter code for United States is "US". The predefined names are listed in the class topic. + The property value is one of the two-letter codes defined in ISO 3166 for country/region. For example, the two-letter code for United States is "US". The predefined names are listed in the class topic. ]]> diff --git a/xml/System.Globalization/CultureInfo.xml b/xml/System.Globalization/CultureInfo.xml index 7750f9d3e4b..f9d74fd6e1f 100644 --- a/xml/System.Globalization/CultureInfo.xml +++ b/xml/System.Globalization/CultureInfo.xml @@ -168,15 +168,15 @@ Predefined culture identifiers for cultures available on Windows system are listed in the **Language tag** column in the [list of language/region names supported by Windows](https://learn.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). - In most cases, the `culture` parameter is mapped to the corresponding National Language Support (NLS) locale identifier. The value of the `culture` parameter becomes the value of the property of the new . + In most cases, the `culture` parameter is mapped to the corresponding National Language Support (NLS) locale identifier. The value of the `culture` parameter becomes the value of the property of the new . We recommend that you call the locale name constructor , because locale names are preferable to LCIDs. For custom locales, a locale name is required. - The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the specified culture identifier matches the culture identifier of the current Windows culture, this constructor creates a that uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the (for example, if the selected calendar is not one of the ) the results of the methods and the values of the properties are undefined. + The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the specified culture identifier matches the culture identifier of the current Windows culture, this constructor creates a that uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the (for example, if the selected calendar is not one of the ) the results of the methods and the values of the properties are undefined. If the specified culture identifier does not match the identifier of the current Windows culture, this constructor creates a that uses the default values for the specified culture. - The property is always set to `true`. + The property is always set to `true`. For example, suppose that Arabic (Saudi Arabia) is the current Windows culture and the user has changed the calendar from Hijri to Gregorian. @@ -187,7 +187,7 @@ Predefined culture identifiers for cultures available on Windows system are list For cultures that use the euro, .NET Framework and Windows XP set the default currency as euro. However, older versions of Windows do not. Therefore, if the user of an older version of Windows has not changed the currency setting through the regional and language options portion of Control Panel, the currency might be incorrect. To use the .NET Framework default setting for the currency, the application should use a constructor overload that accepts a `useUserOverride` parameter and set it to `false`. > [!NOTE] -> For backwards compatibility, a culture constructed using a `culture` parameter of 0x0004 or 0x7c04 will have a property of `zh-CHS` or `zh-CHT`, respectively. You should instead prefer to construct the culture using the current standard culture names of `zh-Hans` or `zh-Hant`, unless you have a reason for using the older names. +> For backwards compatibility, a culture constructed using a `culture` parameter of 0x0004 or 0x7c04 will have a property of `zh-CHS` or `zh-CHT`, respectively. You should instead prefer to construct the culture using the current standard culture names of `zh-Hans` or `zh-Hant`, unless you have a reason for using the older names. > [!NOTE] > LCIDs are being deprecated, and implementers are strongly encouraged to use newer versions of APIs that support BCP 47 locale names instead. Each LCID can be represented by a BCP 47 locale name, but the reverse is not true. The LCID range is restricted and unable to uniquely identify all the possible combinations of language and region. @@ -267,20 +267,20 @@ Predefined culture identifiers for cultures available on Windows system are list For a list of predefined culture names on Windows systems, see the **Language tag** column in the [list of language/region names supported by Windows](https://learn.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). In addition, starting with Windows 10, `name` can be any valid BCP-47 language tag. - If `name` is , the constructor creates an instance of the invariant culture; this is equivalent to retrieving the value of the property. + If `name` is , the constructor creates an instance of the invariant culture; this is equivalent to retrieving the value of the property. - The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the culture identifier associated with `name` matches the culture identifier of the current Windows culture, this constructor creates a object that uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. + The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the culture identifier associated with `name` matches the culture identifier of the current Windows culture, this constructor creates a object that uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. If the culture identifier associated with `name` does not match the culture identifier of the current Windows culture, this constructor creates a object that uses the default values for the specified culture. - The property is always set to `true`. + The property is always set to `true`. For example, suppose that Arabic (Saudi Arabia) is the current culture of Windows and the user changed the calendar from Hijri to Gregorian: - With `CultureInfo("ar-SA")`, is set to (which is the user setting) and is set to `true`. - With `CultureInfo("th-TH")`, is set to (which is the default calendar for th-TH) and is set to `true`. -The property of the new is set to the culture identifier associated with the specified name. +The property of the new is set to the culture identifier associated with the specified name. ## Examples The following example retrieves the current culture. If it is anything other than the French (France) culture, it calls the constructor to instantiate a object that represents the French (France) culture and makes it the current culture. Otherwise, it instantiates a object that represents the French (Luxembourg) culture and makes it the current culture. @@ -355,7 +355,7 @@ The property of the new property of the new . + In most cases, the `culture` parameter is mapped to the corresponding National Language Support (NLS) locale identifier. The value of the `culture` parameter becomes the value of the property of the new . We recommend that you call the locale name constructor , because locale names are preferable to LCIDs. For custom locales, a locale name is required. @@ -363,11 +363,11 @@ Predefined culture identifiers available on Windows systems are listed in the ** Applications should typically not disallow user overrides. Disallowing overrides does not itself guarantee data stability. For more information, see the blog entry [Culture data shouldn't be considered stable (except for Invariant)](/archive/blogs/shawnste/culture-data-shouldnt-be-considered-stable-except-for-invariant). - If the property is set to `true` and the specified culture identifier matches the identifier of the current Windows culture, this constructor creates a that uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. + If the property is set to `true` and the specified culture identifier matches the identifier of the current Windows culture, this constructor creates a that uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. Otherwise, this constructor creates a that uses the default values for the specified culture. - The value of the `useUserOverride` parameter becomes the value of the property. + The value of the `useUserOverride` parameter becomes the value of the property. For example, suppose that Arabic (Saudi Arabia) is the current culture of Windows and the user has changed the calendar from Hijri to Gregorian. @@ -382,7 +382,7 @@ Predefined culture identifiers available on Windows systems are listed in the ** For cultures that use the euro, the .NET Framework and Windows XP set the default currency as euro. However, older versions of Windows do not. Therefore, if the user of an older version of Windows has not changed the currency setting through the regional and language options portion of Control Panel, the currency might be incorrect. To use the .NET Framework default setting for the currency, the application should set the `useUserOverride` parameter to `false`. > [!NOTE] -> For backwards compatibility, a culture constructed using a `culture` parameter of 0x0004 or 0x7c04 will have a property of zh-CHS or zh-CHT, respectively. You should instead prefer to construct the culture using the current standard culture names of `zh-Hans` or zh-Hant, unless you have a reason for using the older names. +> For backwards compatibility, a culture constructed using a `culture` parameter of 0x0004 or 0x7c04 will have a property of zh-CHS or zh-CHT, respectively. You should instead prefer to construct the culture using the current standard culture names of `zh-Hans` or zh-Hant, unless you have a reason for using the older names. > [!NOTE] > LCIDs are being deprecated, and implementers are strongly encouraged to use newer versions of APIs that support BCP 47 locale names instead. Each LCID can be represented by a BCP 47 locale name, but the reverse is not true. The LCID range is restricted and unable to uniquely identify all the possible combinations of language and region. @@ -453,17 +453,17 @@ Predefined culture identifiers available on Windows systems are listed in the ** For a list of predefined culture names, see the **Language tag** column in the [list of language/region names supported by Windows](https://learn.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). In addition, starting with Windows 10, `name` can be any valid BCP-47 language tag. -If `name` is , the constructor creates an instance of the invariant culture; this is equivalent to retrieving the value of the property. +If `name` is , the constructor creates an instance of the invariant culture; this is equivalent to retrieving the value of the property. The user might choose to override some of the values associated with the current Windows culture through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. Applications should typically not disallow user overrides. Disallowing overrides does not itself guarantee data stability. For more information, see the blog entry [Culture data shouldn't be considered stable (except for Invariant)](/archive/blogs/shawnste/culture-data-shouldnt-be-considered-stable-except-for-invariant). - If the property is set to `true` and the culture identifier associated with the specified culture name matches the culture identifier of the current Windows culture, this constructor creates a that uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. + If the property is set to `true` and the culture identifier associated with the specified culture name matches the culture identifier of the current Windows culture, this constructor creates a that uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. Otherwise, this constructor creates a that uses the default values for the specified culture. - The value of the `useUserOverride` parameter becomes the value of the property. + The value of the `useUserOverride` parameter becomes the value of the property. For example, suppose that Arabic (Saudi Arabia) is the current culture of Windows and the user changed the calendar from Hijri to Gregorian. @@ -475,7 +475,7 @@ If `name` is , the constr - With `CultureInfo("th-TH", false)`, is set to (which is the default calendar for th-TH) and is set to `false`. - The property of the new is set to the culture identifier associated with the specified name. + The property of the new is set to the culture identifier associated with the specified name. For cultures that use the euro, the .NET Framework and Windows XP set the default currency as euro. However, older versions of Windows do not do this. Therefore, if the user of an older version of Windows has not changed the currency setting through the regional and language options portion of Control Panel, the currency might be incorrect. To use the .NET Framework default setting for the currency, the application should set the `useUserOverride` parameter to `false`. @@ -550,11 +550,11 @@ If `name` is , the constr ## Remarks The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. - If is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. + If is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. Therefore, if is `true`, the value of this property might be different from the default calendar used by the culture. - Your application changes the calendar used by the current by setting the property of , which is an instance of the class. The new calendar must be one of the calendars listed in . also includes other properties that customize the date and time formatting associated with that . + Your application changes the calendar used by the current by setting the property of , which is an instance of the class. The new calendar must be one of the calendars listed in . also includes other properties that customize the date and time formatting associated with that . ]]> @@ -613,7 +613,7 @@ If `name` is , the constr The method clears the cache of objects created by and refreshes the information in the , , and properties, based on the current system settings. - The method does not refresh the information in the property for existing threads. However, future threads will have any new property values. + The method does not refresh the information in the property for existing threads. However, future threads will have any new property values. ]]> @@ -742,11 +742,11 @@ If `name` is , the constr property returns a object that provides culture-specific information used in culture-sensitive sorting and string comparison operations. + The property returns a object that provides culture-specific information used in culture-sensitive sorting and string comparison operations. The user might choose to override some of the values associated with the current culture of Windows through the regional and language options portion of Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. - If is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. + If is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. ## Examples The following code example shows how to create a for Spanish (Spain) with the international sort and another with the traditional sort. @@ -826,7 +826,7 @@ If `name` is , the constr Cultures are grouped into three sets: the invariant culture, the neutral cultures, and the specific cultures. For more information, see the description of the class. - If the culture identifier of the specific culture returned by this method matches the culture identifier of the current Windows culture, this method creates a object that uses the Windows culture overrides. The overrides include user settings for the properties of the object returned by the property and the object returned by the property. To instantiate a object that with default culture settings rather than user overrides, call the constructor with a value of `false` for the `useUserOverride` argument. + If the culture identifier of the specific culture returned by this method matches the culture identifier of the current Windows culture, this method creates a object that uses the Windows culture overrides. The overrides include user settings for the properties of the object returned by the property and the object returned by the property. To instantiate a object that with default culture settings rather than user overrides, call the constructor with a value of `false` for the `useUserOverride` argument. Although the method name includes the term "Specific", remember that culture data can change between versions, or due to custom cultures, or because of user overrides. Use the invariant culture or binary or fixed forms for saving data. @@ -910,7 +910,7 @@ If `name` is , the constr enumeration and the property. + The following example demonstrates the enumeration and the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CultureTypes/ct.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CultureInfo/CultureTypes/ct.vb" id="Snippet1"::: @@ -1121,9 +1121,9 @@ The following code example demonstrates how to change the is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. + If is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. - The value of the property and the property is not calculated until your application accesses the property. If the user can change the current culture to a new culture while the application is running and then the application accesses the or property, the application retrieves the defaults for the new culture instead of the overrides for the original culture. To preserve the overrides for the original current culture, the application should access the and properties before changing the current culture. + The value of the property and the property is not calculated until your application accesses the property. If the user can change the current culture to a new culture while the application is running and then the application accesses the or property, the application retrieves the defaults for the new culture instead of the overrides for the original culture. To preserve the overrides for the original current culture, the application should access the and properties before changing the current culture. ]]> @@ -1202,12 +1202,12 @@ You might choose to override some of the values associated with the current cult property enables an application to define the default culture of all threads in an application domain. + In the .NET Framework 4 and previous versions, by default, the culture of all threads is set to the Windows system culture. For applications whose current culture differs from the default system culture, this behavior is often undesirable. In the .NET Framework 4.5, the property enables an application to define the default culture of all threads in an application domain. > [!IMPORTANT] -> If you have not explicitly set the culture of any existing threads executing in an application domain, setting the property also changes the culture of these threads. However, if these threads execute in another application domain, their culture is defined by the property in that application domain or, if no default value is defined, by the default system culture. Because of this, we recommend that you always explicitly set the culture of your main application thread, and not rely on the property to define the culture of the main application thread. +> If you have not explicitly set the culture of any existing threads executing in an application domain, setting the property also changes the culture of these threads. However, if these threads execute in another application domain, their culture is defined by the property in that application domain or, if no default value is defined, by the default system culture. Because of this, we recommend that you always explicitly set the culture of your main application thread, and not rely on the property to define the culture of the main application thread. - Unless it is set explicitly, the value of the property is `null`, and the culture of threads in an application domain that have not been assigned an explicit culture is defined by the default Windows system culture. + Unless it is set explicitly, the value of the property is `null`, and the culture of threads in an application domain that have not been assigned an explicit culture is defined by the default Windows system culture. For more information about cultures, threads, and application domains, see the "Culture and threads" and "Culture and application domains" sections in the reference page. @@ -1291,12 +1291,12 @@ You might choose to override some of the values associated with the current cult property lets you define the default UI culture of all threads in an application domain. + In the .NET Framework 4 and previous versions, by default, the UI culture of all threads is set to the Windows system culture. For applications whose current UI culture differs from the default system culture, this behavior is often undesirable. In .NET Framework 4.5+, the property lets you define the default UI culture of all threads in an application domain. > [!IMPORTANT] -> If you have not explicitly set the UI culture of any existing threads executing in an application domain, setting the property also changes the culture of these threads. However, if these threads execute in another application domain, their culture is defined by the property in that application domain or, if no default value is defined, by the default system culture. Because of this, we recommend that you always explicitly set the culture of your main application thread and do not rely on the property to define the culture of the main application thread. +> If you have not explicitly set the UI culture of any existing threads executing in an application domain, setting the property also changes the culture of these threads. However, if these threads execute in another application domain, their culture is defined by the property in that application domain or, if no default value is defined, by the default system culture. Because of this, we recommend that you always explicitly set the culture of your main application thread and do not rely on the property to define the culture of the main application thread. - Unless it is set explicitly, the value of the property is `null`, and the current culture of all threads in an application domain that have not been assigned an explicit culture is defined by the default Windows system culture. + Unless it is set explicitly, the value of the property is `null`, and the current culture of all threads in an application domain that have not been assigned an explicit culture is defined by the default Windows system culture. For more information about cultures, threads, and application domains, see the "Culture and threads" and "Culture and application domains" sections of . @@ -1428,7 +1428,7 @@ csc /resource:GreetingStrings.resources Example1.cs Culture names may vary due to scripting or formatting conventions. You should use the returned name for display, and not attempt to parse it. - If a custom culture is created by means of the class, the property is initialized to the value of the property. + If a custom culture is created by means of the class, the property is initialized to the value of the property. @@ -1658,7 +1658,7 @@ csc /resource:GreetingStrings.resources Example1.cs ## Remarks Languages such as Arabic, Hebrew, Urdu, and Syriac are based on bidirectional text. Windows applications, which have a graphical user interface, support bidirectional languages. However, console applications, which employ the text user interface of the operating system console, do not provide bidirectional support. Therefore, if you localize a console application to Arabic or Hebrew, your application displays unreadable text on the console screen. - The user interface culture specifies the resources an application needs to support user input and output, and by default is the same as the operating system culture. For example, the property returns an Arabic culture for an Arabic operating system. Use the method to retrieve a culture suitable for a console application user interface. After your application retrieves the fallback user interface culture, it should assign the culture to the current user interface culture of the current thread. For more information, see the "Explicitly Setting the Current UI Culture" section of the property. + The user interface culture specifies the resources an application needs to support user input and output, and by default is the same as the operating system culture. For example, the property returns an Arabic culture for an Arabic operating system. Use the method to retrieve a culture suitable for a console application user interface. After your application retrieves the fallback user interface culture, it should assign the culture to the current user interface culture of the current thread. For more information, see the "Explicitly Setting the Current UI Culture" section of the property. The following are predefined cultures that have a different fallback user interface culture name from the predefined culture name. @@ -1898,7 +1898,7 @@ For a list of predefined culture names on Windows systems, see the **Language ta If `name` is the name of the current culture, the returned object does not reflect any user overrides. This makes the method suitable for server applications or tools that do not have a real user account on the system and that need to load multiple cultures efficiently. - If `name` is , the method returns the invariant culture. This is equivalent to retrieving the value of the property. + If `name` is , the method returns the invariant culture. This is equivalent to retrieving the value of the property. ]]> @@ -2021,7 +2021,7 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the The method obtains a cached, read-only object. It offers better performance than a corresponding call to a constructor. The method is used to create a culture similar to that specified by the `name` parameter, but with different sorting and casing rules. - If `name` or `altName` is the name of the current culture, the returned objects do not reflect any user overrides. If `name` is , the method returns the invariant culture. This is equivalent to retrieving the value of the property. If `altName` is , the method uses the writing system and comparison rules specified by the invariant culture. + If `name` or `altName` is the name of the current culture, the returned objects do not reflect any user overrides. If `name` is , the method returns the invariant culture. This is equivalent to retrieving the value of the property. If `altName` is , the method uses the writing system and comparison rules specified by the invariant culture. ]]> @@ -2088,9 +2088,9 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the ## Remarks > [!NOTE] -> This method and the property are deprecated. Instead of using these APIs, we recommend using the constructors, , and the property. IETF tags and names are identical. +> This method and the property are deprecated. Instead of using these APIs, we recommend using the constructors, , and the property. IETF tags and names are identical. - The RFC 4646 standard that is maintained by the Internet Engineering Task Force (IETF) defines an IETF language tag, which provides a uniform means of identifying a language. The format of an IETF language tag is the same as the culture name returned by the property, but does not identify a culture uniquely. Different cultures share the same IETF language tag if those cultures have identical linguistic characteristics. The linguistic characteristics of a culture are contained in the object associated with a object. + The RFC 4646 standard that is maintained by the Internet Engineering Task Force (IETF) defines an IETF language tag, which provides a uniform means of identifying a language. The format of an IETF language tag is the same as the culture name returned by the property, but does not identify a culture uniquely. Different cultures share the same IETF language tag if those cultures have identical linguistic characteristics. The linguistic characteristics of a culture are contained in the object associated with a object. An IETF language tag consists of a mandatory language identifier, an optional script identifier, and an optional region identifier. @@ -2170,7 +2170,7 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the - , which returns all neutral and specific cultures, cultures installed in the Windows system, and custom cultures created by the user. -- , which returns all custom cultures, such as those registered by the class. In versions of Windows before Windows 10, the value applies to all user-defined custom cultures. Starting with Windows 10, it applies to system cultures that lack complete cultural data and that do not have a unique local identifier, as indicated by the property value. As a result, code such as the following will return different results when run on Windows 10 and on an earlier version of Windows. +- , which returns all custom cultures, such as those registered by the class. In versions of Windows before Windows 10, the value applies to all user-defined custom cultures. Starting with Windows 10, it applies to system cultures that lack complete cultural data and that do not have a unique local identifier, as indicated by the property value. As a result, code such as the following will return different results when run on Windows 10 and on an earlier version of Windows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/DisplayName/getcultures3.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CultureInfo/DisplayName/getcultures3.vb" id="Snippet2"::: @@ -2393,9 +2393,9 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the ## Remarks > [!NOTE] -> This property (and the method) is deprecated. Instead, you should use the property. IETF tags and names are identical. +> This property (and the method) is deprecated. Instead, you should use the property. IETF tags and names are identical. - The RFC 4646 standard that is maintained by the Internet Engineering Task Force (IETF) defines an IETF language tag, which provides a uniform means of identifying a language. The format of an IETF language tag is similar to the culture name returned by the property, but does not identify a culture uniquely. That is, different cultures share the same IETF language tag if those cultures have identical linguistic characteristics. The linguistic characteristics of a culture are contained in the object associated with a object. + The RFC 4646 standard that is maintained by the Internet Engineering Task Force (IETF) defines an IETF language tag, which provides a uniform means of identifying a language. The format of an IETF language tag is similar to the culture name returned by the property, but does not identify a culture uniquely. That is, different cultures share the same IETF language tag if those cultures have identical linguistic characteristics. The linguistic characteristics of a culture are contained in the object associated with a object. An IETF language tag consists of a mandatory language identifier, an optional script identifier, and an optional region identifier. @@ -2830,11 +2830,11 @@ Setting `predefinedOnly` to `true` will ensure a culture is created only if the ## Remarks -For a list of predefined culture names and identifiers that the property can return on Windows systems, see the **Language tag** column in the [list of language/region names supported by Windows](https://learn.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). In addition, starting with Windows 10, `name` can be any valid BCP-47 language tag. Note that culture names are subject to change, and that they also can reflect the names of custom cultures. +For a list of predefined culture names and identifiers that the property can return on Windows systems, see the **Language tag** column in the [list of language/region names supported by Windows](https://learn.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). In addition, starting with Windows 10, `name` can be any valid BCP-47 language tag. Note that culture names are subject to change, and that they also can reflect the names of custom cultures. - The property follows the naming standards provided in the class topic. It returns the short form of the culture name that excludes any indication of an alternate sort order. For example, if you instantiate a object by using the string "de-DE_phoneb" to reflect an alternate sort order, the property returns "de-DE". + The property follows the naming standards provided in the class topic. It returns the short form of the culture name that excludes any indication of an alternate sort order. For example, if you instantiate a object by using the string "de-DE_phoneb" to reflect an alternate sort order, the property returns "de-DE". - To get the full name of the culture, you should use the , , or property. + To get the full name of the culture, you should use the , , or property. @@ -2978,9 +2978,9 @@ For a list of predefined culture names and identifiers that the is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. + If is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. - The values of the property and the property are not calculated until the user accesses the property. If the user uses the Control Panel to change the current culture to a new culture while the application is running and then accesses the or property, the application retrieves the defaults for the new culture. not the overrides for the original culture. To preserve the overrides for the original current culture, the application should access the and properties before changing the current culture. + The values of the property and the property are not calculated until the user accesses the property. If the user uses the Control Panel to change the current culture to a new culture while the application is running and then accesses the or property, the application retrieves the defaults for the new culture. not the overrides for the original culture. To preserve the overrides for the original current culture, the application should access the and properties before changing the current culture. ]]> @@ -3053,7 +3053,7 @@ The following code example shows that CultureInfo.Clone also clones the by setting the property of , which is an instance of the class. The new calendar must be one of the calendars listed in . also includes other properties that customize the date and time formatting associated with that . + Your application changes the calendar used by the current by setting the property of , which is an instance of the class. The new calendar must be one of the calendars listed in . also includes other properties that customize the date and time formatting associated with that . ## Examples The following code example demonstrates how to determine the versions supported by the culture. @@ -3268,7 +3268,7 @@ The following code example shows that CultureInfo.Clone also clones the property provides culture-specific casing information for strings. To perform culture-insensitive casing, the application should use the property of . + The property provides culture-specific casing information for strings. To perform culture-insensitive casing, the application should use the property of . @@ -3552,17 +3552,17 @@ The following code example shows that CultureInfo.Clone also clones the property value for the invariant culture is "iv". + For example, the two-letter abbreviation for English is "en". The property value for the invariant culture is "iv". > [!NOTE] > When communicating between processes or persisting data it is usually better to use the full . Using just the language can lose context and data. - If ISO 639-1 does not define a two-letter language code for a particular culture, the property returns a string that consists of three or more letters. For more information, see the example. + If ISO 639-1 does not define a two-letter language code for a particular culture, the property returns a string that consists of three or more letters. For more information, see the example. ## Examples - The following example lists the cultures whose property does not consist of a two-letter language code. + The following example lists the cultures whose property does not consist of a two-letter language code. :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/TwoLetterISOLanguageName/twoletterisolanguagename1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CultureInfo/TwoLetterISOLanguageName/twoletterisolanguagename1.vb" id="Snippet1"::: @@ -3626,7 +3626,7 @@ The following code example shows that CultureInfo.Clone also clones the is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. + If is `true` and the specified culture matches the current culture of Windows, the uses those overrides, including user settings for the properties of the instance returned by the property, and the properties of the instance returned by the property. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. This property is set when the is created. diff --git a/xml/System.Globalization/CultureNotFoundException.xml b/xml/System.Globalization/CultureNotFoundException.xml index 4518594ac53..e3a1b19bfda 100644 --- a/xml/System.Globalization/CultureNotFoundException.xml +++ b/xml/System.Globalization/CultureNotFoundException.xml @@ -95,7 +95,7 @@ > [!WARNING] > On Windows 7 and later operating systems, the .NET Framework retrieves culture data from the operating system. The exception is thrown if the operating system is unable to find the culture, and the culture is not a custom culture or a replacement culture. - If the calling code attempted to instantiate a object by using a culture name, the property contains the invalid name, and the property of the object returned by the property is `false`. If the calling code attempted to instantiate a object by using a culture identifier, the property of the object returned by the property contains the invalid identifier, and the value of the property is `null`. + If the calling code attempted to instantiate a object by using a culture name, the property contains the invalid name, and the property of the object returned by the property is `false`. If the calling code attempted to instantiate a object by using a culture identifier, the property of the object returned by the property contains the invalid identifier, and the value of the property is `null`. uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. @@ -216,7 +216,7 @@ property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + This constructor initializes the property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. @@ -339,9 +339,9 @@ property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + This constructor initializes the property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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. ]]> @@ -396,9 +396,9 @@ property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + This constructor initializes the property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. + This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. @@ -455,9 +455,9 @@ property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + This constructor initializes the property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - 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. + 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. ]]> @@ -512,9 +512,9 @@ property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + This constructor initializes the property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. + This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. @@ -573,9 +573,9 @@ property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + This constructor initializes the property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - 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. + 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. ]]> @@ -632,9 +632,9 @@ property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + This constructor initializes the property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. + This constructor initializes the property of the new instance using `paramName`. The content of `paramName` is intended to be understood by humans. uses the HRESULT COR_E_ARGUMENT, which has the value 0x80070057. @@ -762,7 +762,7 @@ object by using an invalid culture identifier, the property of the object returned by the property contains the invalid identifier. Otherwise, its property is `false`. + If the calling code attempted to instantiate or retrieve a object by using an invalid culture identifier, the property of the object returned by the property contains the invalid identifier. Otherwise, its property is `false`. ]]> @@ -815,7 +815,7 @@ object by using a culture name, the property contains the invalid name. Otherwise, its value is `null`. + If the calling code attempted to instantiate a object by using a culture name, the property contains the invalid name. Otherwise, its value is `null`. ]]> diff --git a/xml/System.Globalization/CultureTypes.xml b/xml/System.Globalization/CultureTypes.xml index 1166104fdb5..3522407d1c4 100644 --- a/xml/System.Globalization/CultureTypes.xml +++ b/xml/System.Globalization/CultureTypes.xml @@ -64,7 +64,7 @@ ## Remarks -These culture type values are returned by the property, and also serve as a filter that limits the cultures returned by the method. For more information on cultures, see . +These culture type values are returned by the property, and also serve as a filter that limits the cultures returned by the method. For more information on cultures, see . Generally, you enumerate all cultures by using the `CultureTypes.AllCultures` value. This allows enumeration of custom cultures as well as the other culture types. @@ -84,7 +84,7 @@ Note that all `CultureTypes` members have been deprecated except for `CultureTyp ## Examples -The following example demonstrates the `CultureTypes.AllCultures` enumeration member and the property. +The following example demonstrates the `CultureTypes.AllCultures` enumeration member and the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/CultureTypes/ct.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/CultureInfo/CultureTypes/ct.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/DateTimeFormatInfo.xml b/xml/System.Globalization/DateTimeFormatInfo.xml index 201ea5f72e9..c37ed212b76 100644 --- a/xml/System.Globalization/DateTimeFormatInfo.xml +++ b/xml/System.Globalization/DateTimeFormatInfo.xml @@ -155,9 +155,9 @@ object that represents the date and time information of the invariant culture. To create a object for a specific culture, create a object for that culture and retrieve the object returned by its property. + This constructor creates a object that represents the date and time information of the invariant culture. To create a object for a specific culture, create a object for that culture and retrieve the object returned by its property. - The properties of the object created by this constructor can be modified. However, you cannot modify the property, because the invariant culture supports only a localized version of the Gregorian calendar. To create a object that uses a specific calendar, you must instantiate a object that supports that calendar and assign the calendar to the property of the object returned by the property. + The properties of the object created by this constructor can be modified. However, you cannot modify the property, because the invariant culture supports only a localized version of the Gregorian calendar. To create a object that uses a specific calendar, you must instantiate a object that supports that calendar and assign the calendar to the property of the object returned by the property. ]]> @@ -212,14 +212,14 @@ property. + If setting this property, the array must be one-dimensional and must have exactly seven elements. The first element (the element at index zero) represents the first day of the week in the calendar defined by the property. If a custom format string includes the "ddd" format specifier, the or method includes the appropriate member of the array in place of the "ddd" in the result string. - This property is affected if the value of the property changes. If the selected does not support abbreviated day names, the array contains the full day names. + This property is affected if the value of the property changes. If the selected does not support abbreviated day names, the array contains the full day names. ## Examples - The following example creates a read/write object that represents the English (United States) culture and assigns abbreviated day names to its property. It then uses the "ddd" format specifier in a [custom date and time format string](/dotnet/standard/base-types/custom-date-and-time-format-strings) to display the string representation of dates for one week beginning May 28, 2014. + The following example creates a read/write object that represents the English (United States) culture and assigns abbreviated day names to its property. It then uses the "ddd" format specifier in a [custom date and time format string](/dotnet/standard/base-types/custom-date-and-time-format-strings) to display the string representation of dates for one week beginning May 28, 2014. :::code language="csharp" source="~/snippets/csharp/System.Globalization/DateTimeFormatInfo/AbbreviatedDayNames/abbreviateddaynames1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/DateTimeFormatInfo/AbbreviatedDayNames/abbreviateddaynames1.vb" id="Snippet1"::: @@ -293,9 +293,9 @@ ## Remarks In some languages, a month name that is part of a date appears in the genitive case. For example, a date in the ru-RU or Russian (Russia) culture consists of the day number and the genitive month name, such as 1 Января (1 January). For these cultures, if a custom format string includes the "MMM" format specifier, the or method includes the appropriate member of the array in place of the "MMM" in the result string. - In a set operation, the array must be one-dimensional with exactly 13 elements, because objects accommodate calendars that have 13 months. For calendars that have 12 months, the thirteenth element should be . The first element (the element at index zero) represents the first month of the year defined by the property. + In a set operation, the array must be one-dimensional with exactly 13 elements, because objects accommodate calendars that have 13 months. For calendars that have 12 months, the thirteenth element should be . The first element (the element at index zero) represents the first month of the year defined by the property. - If you set the property, you must also set the property. + If you set the property, you must also set the property. ## Examples The following example creates a read/write object that represents the English (United States) culture and assigns abbreviated genitive month names to its and properties. It then displays the string representation of dates that include the abbreviated month name of each month in the culture's supported calendar. @@ -360,14 +360,14 @@ objects accommodate calendars with 13 months. The first element (the element at index zero) represents the first month of the year defined by the property. + If you set this property, the array must be one-dimensional with exactly 13 elements. objects accommodate calendars with 13 months. The first element (the element at index zero) represents the first month of the year defined by the property. - If you set the property, you must also set the property. The and properties are used to format dates using the following format strings: + If you set the property, you must also set the property. The and properties are used to format dates using the following format strings: - A standard date and time format string that aliases a custom format string that includes the "MMM" format specifier. - A custom date and time format string that includes the "MMM" format specifier. - This property is affected if the value of the property changes. If the selected does not support abbreviated month names, the array contains the full month names. + This property is affected if the value of the property changes. If the selected does not support abbreviated month names, the array contains the full month names. ## Examples The following example creates a read/write object that represents the English (United States) culture and assigns abbreviated genitive month names to its and properties. It then displays the string representation of dates that include the abbreviated name of each month in the culture's supported calendar. @@ -440,9 +440,9 @@ property is used for all times from 0:00:00 (midnight) to 11:59:59.999. + The property is used for all times from 0:00:00 (midnight) to 11:59:59.999. - If a custom format string includes the "tt" format specifier and the time is before noon, the or method includes the value of the property in place of "tt" in the result string. If the custom format string includes the "t" custom format specifier, only the first character of the property value is included. You should use "tt" for languages for which it is necessary to maintain the distinction between A.M. and P.M. An example is Japanese, in which the A.M. and P.M. designators differ in the second character instead of the first character. + If a custom format string includes the "tt" format specifier and the time is before noon, the or method includes the value of the property in place of "tt" in the result string. If the custom format string includes the "t" custom format specifier, only the first character of the property value is included. You should use "tt" for languages for which it is necessary to maintain the distinction between A.M. and P.M. An example is Japanese, in which the A.M. and P.M. designators differ in the second character instead of the first character. For cultures that do not use an A.M. designator, this property returns an empty string. @@ -507,7 +507,7 @@ property accepts only calendars that are valid for the culture that is associated with the object. The property specifies the calendars that can be used by a particular culture, and the property specifies the default calendar for the culture. + The property accepts only calendars that are valid for the culture that is associated with the object. The property specifies the calendars that can be used by a particular culture, and the property specifies the default calendar for the culture. [!INCLUDE[japanese-era-note](~/includes/calendar-era.md)] @@ -583,7 +583,7 @@ Changing the value of this property affects the following properties as well: property changes. + This property is affected if the value of the property changes. ]]> @@ -715,10 +715,10 @@ Changing the value of this property affects the following properties as well: object returned by the property reflects user overrides. + The object returned by the property reflects user overrides. ## Examples - The following example uses the property to retrieve a object that represents the formatting conventions of the current culture, which in this case is the en-US culture. It then displays the format string and the result string for six formatting properties. + The following example uses the property to retrieve a object that represents the formatting conventions of the current culture, which in this case is the en-US culture. It then displays the format string and the result string for six formatting properties. :::code language="csharp" source="~/snippets/csharp/System.Globalization/DateTimeFormatInfo/CurrentInfo/CurrentInfo1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/DateTimeFormatInfo/CurrentInfo/CurrentInfo1.vb" id="Snippet1"::: @@ -776,7 +776,7 @@ Changing the value of this property affects the following properties as well: method displays the value of in place of the "/" in the result string. - The property defines the string that replaces the date separator ("/" custom date and time format specifier) in a result string in a formatting operation. It also defines the date separator string in a parsing operation. + The property defines the string that replaces the date separator ("/" custom date and time format specifier) in a result string in a formatting operation. It also defines the date separator string in a parsing operation. ## Examples The following example instantiates a object for the en-US culture, changes its date separator to "-", and displays a date by using the "d", "G", and "g" standard format strings. @@ -841,11 +841,11 @@ Changing the value of this property affects the following properties as well: property. + If setting this property, the array must be one-dimensional and must have exactly seven elements. The first element (the element at index zero) represents the first day of the week in the calendar defined by the property. If a custom format string includes the "dddd" format specifier, the method includes the value of the appropriate member in place of "dddd" in the result string. - This property is affected if the value of the property changes. + This property is affected if the value of the property changes. ]]> @@ -911,7 +911,7 @@ Changing the value of this property affects the following properties as well: property changes. + This property is affected if the value of the property changes. ]]> @@ -968,15 +968,15 @@ Changing the value of this property affects the following properties as well: property. In other words, the custom format string assigned to this property defines the format of the result string for the "F" standard format string. For more information, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings). + The "F" standard format string is an alias for the property. In other words, the custom format string assigned to this property defines the format of the result string for the "F" standard format string. For more information, see [Standard Date and Time Format Strings](/dotnet/standard/base-types/standard-date-and-time-format-strings). - The value of the property is generated dynamically by concatenating the and properties separated by a space. This dynamic assignment occurs under the following conditions: + The value of the property is generated dynamically by concatenating the and properties separated by a space. This dynamic assignment occurs under the following conditions: - If the property value is retrieved before it has been explicitly set. -- When the value of the property changes. -- When the value of the property changes. +- When the value of the property changes. +- When the value of the property changes. -This property is affected if the value of the property changes. +This property is affected if the value of the property changes. ## Examples The following example displays the value of for a few cultures. @@ -1130,7 +1130,7 @@ This property is affected if the value of the property of the appropriate class derived from . For example: displays a list of eras that are supported by this implementation. + The valid values for `era` are listed in the property of the appropriate class derived from . For example: displays a list of eras that are supported by this implementation. In the class, the abbreviated era name is the first character of the full era name. This character is either the single-character case-insensitive Latin alphabet abbreviation or the single-character Kanji abbreviation. @@ -1309,7 +1309,7 @@ This property is affected if the value of the object that represents the invariant culture by calling the constructor. It could also retrieve a that represents the invariant culture from the property. + The example instantiates a object that represents the invariant culture by calling the constructor. It could also retrieve a that represents the invariant culture from the property. ]]> @@ -1608,7 +1608,7 @@ This property is affected if the value of the property of the appropriate class derived from . For example: displays a list of eras that are supported by this implementation. + The valid values for `era` are listed in the property of the appropriate class derived from . For example: displays a list of eras that are supported by this implementation. [!INCLUDE[japanese-era-note](~/includes/calendar-era.md)] @@ -1760,7 +1760,7 @@ This property is affected if the value of the object for a specific culture using one of the following methods: -- The property. +- The property. - The method, where `provider` is a object. A object can be created only for the invariant culture or for specific cultures, not for neutral cultures. @@ -2083,7 +2083,7 @@ This property is affected if the value of the property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "D" standard format string. The following example illustrates the relationships among the following: the "D" standard format string, the custom format string returned by the property, and the culture-specific representation of a date. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "D" standard format string. The following example illustrates the relationships among the following: the "D" standard format string, the custom format string returned by the property, and the culture-specific representation of a date. :::code language="csharp" source="~/snippets/csharp/System.Globalization/DateTimeFormatInfo/LongDatePattern/longdatepattern1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/DateTimeFormatInfo/LongDatePattern/longdatepattern1.vb" id="Snippet2"::: @@ -2092,13 +2092,13 @@ This property is affected if the value of the property of a object that represents the Arabic (Syria) culture changes when the object used by the culture changes. + The value of this property may change if the calendar used by a culture changes. For instance, the following example shows how the property of a object that represents the Arabic (Syria) culture changes when the object used by the culture changes. :::code language="csharp" source="~/snippets/csharp/System.Globalization/DateTimeFormatInfo/LongDatePattern/longdatepattern2.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/DateTimeFormatInfo/LongDatePattern/longdatepattern2.vb" id="Snippet3"::: ## Examples - The following example displays the value of the property for a few cultures. + The following example displays the value of the property for a few cultures. :::code language="csharp" source="~/snippets/csharp/System.Globalization/DateTimeFormatInfo/LongDatePattern/dtfi_longdatepattern.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/DateTimeFormatInfo/LongDatePattern/dtfi_longdatepattern.vb" id="Snippet1"::: @@ -2169,7 +2169,7 @@ This property is affected if the value of the property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "T" standard format string. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "T" standard format string. We recommend that you set the time separator in the long time pattern to an exact string instead of using the time separator placeholder. For example, to obtain the pattern h-mm-ss, set the long date pattern to "h-mm-ss". @@ -2241,9 +2241,9 @@ This property is affected if the value of the property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "m" and "M" standard format strings. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "m" and "M" standard format strings. - This property is affected if the value of the property changes. + This property is affected if the value of the property changes. We recommend that you set the date separator in the month and day pattern to an exact string instead of using the date separator placeholder. For example, to obtain the pattern MM-DD, set the month and day pattern to "MM-DD". @@ -2320,7 +2320,7 @@ This property is affected if the value of the objects accommodate calendars with 13 months. The first element (the element at index zero) represents the first month of the year defined by the property. If you set the property, you must also set the property. + When this property is set, the array must be one-dimensional and must have exactly 13 elements. objects accommodate calendars with 13 months. The first element (the element at index zero) represents the first month of the year defined by the property. If you set the property, you must also set the property. ## Examples The following example demonstrates several methods and properties that specify date and time format patterns, native calendar name, and full and abbreviated month and day names. @@ -2386,13 +2386,13 @@ This property is affected if the value of the objects accommodate calendars with 13 months. The first element (the element at index zero) represents the first month of the year defined by the property. + When this property is set, the array must be one-dimensional and must have exactly 13 elements. objects accommodate calendars with 13 months. The first element (the element at index zero) represents the first month of the year defined by the property. - If you set the property, you must also set the property. + If you set the property, you must also set the property. If the custom pattern includes the format pattern "MMMM", displays the value of in place of the "MMMM" in the format pattern. - This property is affected if the value of the property changes. + This property is affected if the value of the property changes. ]]> @@ -2521,7 +2521,7 @@ This property is affected if the value of the property is used for all times from 12:00:00 (noon) to 23:59:59.999. + The property is used for all times from 12:00:00 (noon) to 23:59:59.999. If the custom pattern includes the format pattern "tt" and the time is after noon, displays the value of in place of the "tt" in the format pattern. If the custom pattern includes the format pattern "t", only the first character of is displayed. Your application should use "tt" for languages for which it is necessary to maintain the distinction between AM and PM. An example is Japanese, for which the AM and PM designators differ in the second character instead of the first character. @@ -2649,7 +2649,7 @@ This property is affected if the value of the property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "r" and "R" standard format strings. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "r" and "R" standard format strings. The RFC1123 pattern reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture. The custom format string is "ddd, dd MMM yyyy HH':'mm':'ss 'GMT'". @@ -2800,17 +2800,17 @@ This property is affected if the value of the property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "d" standard format string. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "d" standard format string. - This property is affected if the value of the property changes. + This property is affected if the value of the property changes. ## Examples - The following example displays the value of the property and the value of a date formatted using the property for a few cultures. + The following example displays the value of the property and the value of a date formatted using the property for a few cultures. :::code language="csharp" source="~/snippets/csharp/System.Globalization/DateTimeFormatInfo/ShortDatePattern/dtfi_shortdatepattern.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/DateTimeFormatInfo/ShortDatePattern/dtfi_shortdatepattern.vb" id="Snippet1"::: - The following example modifies the property of a object that represents the formatting conventions of the English (United States) culture. It also displays a date value twice, first to reflect the original property and then to reflect the new property value. + The following example modifies the property of a object that represents the formatting conventions of the English (United States) culture. It also displays a date value twice, first to reflect the original property and then to reflect the new property value. :::code language="csharp" source="~/snippets/csharp/System.Globalization/DateTimeFormatInfo/ShortDatePattern/shortdatepattern1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/DateTimeFormatInfo/ShortDatePattern/shortdatepattern1.vb" id="Snippet2"::: @@ -2950,7 +2950,7 @@ The default array starts on Sunday. property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "t" standard format string. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "t" standard format string. We recommend that you set the time separator in the short time pattern to an exact string instead of using the time separator placeholder. For example, to obtain the pattern h-mm-ss, set the short time pattern to "h-mm-ss". @@ -3016,9 +3016,9 @@ The default array starts on Sunday. property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "s" standard format string. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "s" standard format string. - The format string returned by the property reflects a defined standard (ISO 8601), and the property is read-only. Therefore, it is always the same, regardless of the culture. The custom format string is "yyyy'-'MM'-'dd'T'HH':'mm':'ss". + The format string returned by the property reflects a defined standard (ISO 8601), and the property is read-only. Therefore, it is always the same, regardless of the culture. The custom format string is "yyyy'-'MM'-'dd'T'HH':'mm':'ss". ## Examples The following example displays the value of for a few cultures. @@ -3123,7 +3123,7 @@ If the custom pattern includes the format pattern ":", [!NOTE] > Standard format patterns, such as , don't necessarily use ":". Changing may not have an effect when using these patterns. - The time separator is derived from the property. We recommend that you set the time separator in short or long time patterns to an exact string instead of using the time separator placeholder. For example, to obtain the pattern h-mm-ss, set the pattern to "h-mm-ss". This practice also enables you to set patterns such as "h'h 'mm'm 'ss's'" (3h 36m 12s) that include multiple types of separators. The property defines the string that replaces the time separator (":" custom date and time format specifier) in a result string in a formatting operation. It also defines the time separator string in a parsing operation. + The time separator is derived from the property. We recommend that you set the time separator in short or long time patterns to an exact string instead of using the time separator placeholder. For example, to obtain the pattern h-mm-ss, set the pattern to "h-mm-ss". This practice also enables you to set patterns such as "h'h 'mm'm 'ss's'" (3h 36m 12s) that include multiple types of separators. The property defines the string that replaces the time separator (":" custom date and time format specifier) in a result string in a formatting operation. It also defines the time separator string in a parsing operation. ## Examples The following example instantiates a object for the en-US culture, changes its date separator to ".", and displays a date by using the "t", "T", "F", "f", "G", and "g" standard format strings. @@ -3188,9 +3188,9 @@ If the custom pattern includes the format pattern ":", property defines the format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "u" standard format string. It can be used to display dates and times in a sortable order with the universal time designator "Z" at the end. The format is sortable because it uses leading zeros for year, month, day, hour, minute, and second. The custom format string ("yyyy'-'MM'-'dd HH':'mm':'ss'Z'") is the same regardless of culture or format provider. + The property defines the format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "u" standard format string. It can be used to display dates and times in a sortable order with the universal time designator "Z" at the end. The format is sortable because it uses leading zeros for year, month, day, hour, minute, and second. The custom format string ("yyyy'-'MM'-'dd HH':'mm':'ss'Z'") is the same regardless of culture or format provider. - The format string returned by the property reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture. The custom format string is "yyyy'-'MM'-'dd HH':'mm':'ss'Z'". + The format string returned by the property reflects a defined standard, and the property is read-only. Therefore, it is always the same, regardless of the culture. The custom format string is "yyyy'-'MM'-'dd HH':'mm':'ss'Z'". ## Examples The following example displays the value of for a few cultures. @@ -3263,9 +3263,9 @@ If the custom pattern includes the format pattern ":", property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "y" and "Y" standard format strings. + The property defines the culture-specific format of date strings that are returned by calls to the and methods and by composite format strings that are supplied the "y" and "Y" standard format strings. - This property is affected if the value of the property changes. + This property is affected if the value of the property changes. We recommend that you set the date separator in the year month pattern to an exact string instead of using the date separator placeholder. For example, to get the pattern MM-yyyy, set the year month pattern to "MM-yyyy". diff --git a/xml/System.Globalization/DaylightTime.xml b/xml/System.Globalization/DaylightTime.xml index fe091dd2169..6ff4877d804 100644 --- a/xml/System.Globalization/DaylightTime.xml +++ b/xml/System.Globalization/DaylightTime.xml @@ -57,14 +57,14 @@ Defines the period of daylight saving time. - [!WARNING] -> The object returned by the method recognizes only the time zone adjustment rule that is currently in effect, and ignores any previous adjustment rules for which the system has information. Instead, it applies the current adjustment rule backward in time to periods when it may not have been in effect. To retrieve information about all the known adjustment rules for a particular time zone, use the method. - +> The object returned by the method recognizes only the time zone adjustment rule that is currently in effect, and ignores any previous adjustment rules for which the system has information. Instead, it applies the current adjustment rule backward in time to periods when it may not have been in effect. To retrieve information about all the known adjustment rules for a particular time zone, use the method. + ]]> @@ -114,11 +114,11 @@ The object that represents the difference between standard time and daylight saving time, in ticks. Initializes a new instance of the class with the specified start, end, and time difference information. - property of the new object. The `end` parameter becomes the value of the property of the new object. The `delta` parameter becomes the value of the property of the new object. - + property of the new object. The `end` parameter becomes the value of the property of the new object. The `delta` parameter becomes the value of the property of the new object. + ]]> @@ -168,13 +168,13 @@ Gets the time interval that represents the difference between standard time and daylight saving time. The time interval that represents the difference between standard time and daylight saving time. - property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. - - If the property value is positive, at the start of daylight saving time, the clock time is advanced by the length of time specified by this property. At the end of daylight saving time, the clock time is set back by the length of time specified by this property. If the property value is negative, the clock time is set back at the start of daylight saving time and advanced at the end. - + property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. + + If the property value is positive, at the start of daylight saving time, the clock time is advanced by the length of time specified by this property. At the end of daylight saving time, the clock time is set back by the length of time specified by this property. If the property value is negative, the clock time is set back at the start of daylight saving time and advanced at the end. + ]]> @@ -222,13 +222,13 @@ Gets the object that represents the date and time when the daylight saving period ends. The object that represents the date and time when the daylight saving period ends. The value is in local time. - property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. - - When the daylight saving period ends, the clock time is set back to standard time. - + property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. + + When the daylight saving period ends, the clock time is set back to standard time. + ]]> @@ -274,13 +274,13 @@ Gets the object that represents the date and time when the daylight saving period begins. The object that represents the date and time when the daylight saving period begins. The value is in local time. - property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. - - When the daylight saving period begins, the clock time is advanced by the number of ticks defined by the property to take advantage of the extended daylight hours. - + property. Generally, the class is a more accurate source of information on time zone adjustments than the and classes. + + When the daylight saving period begins, the clock time is advanced by the number of ticks defined by the property to take advantage of the extended daylight hours. + ]]> diff --git a/xml/System.Globalization/DigitShapes.xml b/xml/System.Globalization/DigitShapes.xml index 3b7c12af858..542e70bf08d 100644 --- a/xml/System.Globalization/DigitShapes.xml +++ b/xml/System.Globalization/DigitShapes.xml @@ -55,15 +55,15 @@ Specifies the culture-specific display of digits. - value specifies that no digit shape is substituted for the Unicode input, a digit shape is substituted based on context, or a native national digit shape is substituted for the input. - - The Arabic, Indic, and Thai languages have classical shapes for numbers that are different from the digits 0 through 9 (Unicode U+0030 through U+0039), which are most often used on computers. The application uses the enumeration with the property to specify how to display digits U+0030 through U+0039 in the absence of other formatting information. - - The enumeration is primarily used by applications intended for cultures that use bidirectional scripts. For example, the reading order of Arabic and Indic scripts is bidirectional. - + value specifies that no digit shape is substituted for the Unicode input, a digit shape is substituted based on context, or a native national digit shape is substituted for the input. + + The Arabic, Indic, and Thai languages have classical shapes for numbers that are different from the digits 0 through 9 (Unicode U+0030 through U+0039), which are most often used on computers. The application uses the enumeration with the property to specify how to display digits U+0030 through U+0039 in the absence of other formatting information. + + The enumeration is primarily used by applications intended for cultures that use bidirectional scripts. For example, the reading order of Arabic and Indic scripts is bidirectional. + ]]> diff --git a/xml/System.Globalization/EastAsianLunisolarCalendar.xml b/xml/System.Globalization/EastAsianLunisolarCalendar.xml index e93026a2c8c..684a2a403ae 100644 --- a/xml/System.Globalization/EastAsianLunisolarCalendar.xml +++ b/xml/System.Globalization/EastAsianLunisolarCalendar.xml @@ -147,7 +147,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -222,7 +222,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -1227,7 +1227,7 @@ method uses the property to determine the appropriate century. + The method uses the property to determine the appropriate century. supports either a two-digit year or a four-digit year. Passing a two-digit year value (less than 100) causes the method to convert the value to a four-digit value according to the value representing the appropriate century. If the application supplies a four-digit year value that is within the supported calendar range to , the method returns the actual input value. If the application supplies a four-digit value that is outside the supported calendar range, or if it supplies a negative value, the method throws an exception. diff --git a/xml/System.Globalization/GregorianCalendar.xml b/xml/System.Globalization/GregorianCalendar.xml index a13416a6990..5f666bdd6ea 100644 --- a/xml/System.Globalization/GregorianCalendar.xml +++ b/xml/System.Globalization/GregorianCalendar.xml @@ -98,7 +98,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Globalization/GregorianCalendar/Overview/minimum1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/GregorianCalendar/Overview/minimum1.vb" id="Snippet1"::: - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application can set the property to a new . + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application can set the property to a new . ignores punctuation in abbreviated era names, only if the is selected in and the culture uses "A.D." as the era name, that is, "A.D." is equivalent to "AD". @@ -106,7 +106,7 @@ ## Examples The following code example shows that ignores the punctuation in the era name, only if the calendar is Gregorian and the culture uses the era name "A.D.". - + :::code language="csharp" source="~/snippets/csharp/System.Globalization/DateTimeFormatInfo/GetEra/gregorian_getera.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/DateTimeFormatInfo/GetEra/gregorian_getera.vb" id="Snippet1"::: @@ -171,7 +171,7 @@ value is . If the property of the is set to a that is created with this constructor, the dates and times are localized in the language associated with the . + The default value is . If the property of the is set to a that is created with this constructor, the dates and times are localized in the language associated with the . @@ -296,7 +296,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -423,7 +423,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -553,7 +553,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -1849,7 +1849,7 @@ property is the first moment of January 1, 0001 C.E., the Gregorian calendar was not introduced until October 15, 1582, and its adoption throughout the European continent and worldwide was slow. Until they adopted the Gregorian calendar, most cultures in the European, American, and Australian continents used the Julian calendar, which is represented by the class. + Although the value of the property is the first moment of January 1, 0001 C.E., the Gregorian calendar was not introduced until October 15, 1582, and its adoption throughout the European continent and worldwide was slow. Until they adopted the Gregorian calendar, most cultures in the European, American, and Australian continents used the Julian calendar, which is represented by the class. diff --git a/xml/System.Globalization/HebrewCalendar.xml b/xml/System.Globalization/HebrewCalendar.xml index 74cce4cba45..8b252596acf 100644 --- a/xml/System.Globalization/HebrewCalendar.xml +++ b/xml/System.Globalization/HebrewCalendar.xml @@ -109,7 +109,7 @@ The date January 1, 2001 A.D. in the Gregorian calendar is equivalent to the sixth day of Tevet in the year 5761 A.M. in the Hebrew calendar. - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . @@ -234,7 +234,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -243,7 +243,7 @@ ## Examples The following code example displays the values of several components of a in terms of the Hebrew calendar. - + :::code language="csharp" source="~/snippets/csharp/System.Globalization/HebrewCalendar/AddMonths/hebrewcalendar_addget.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/HebrewCalendar/AddMonths/hebrewcalendar_addget.vb" id="Snippet1"::: @@ -328,7 +328,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -399,7 +399,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -1791,9 +1791,9 @@ method uses the `year` parameter, the property, and a year to calculate a 4-digit year. The century is determined by finding the sole occurrence of the `year` parameter within that 100-year range. For example, if is set to 5729, the 100-year range is from 5630 to 5729. Therefore, a value of 30 is interpreted as 5630, while a value of 29 is interpreted as 5729. + The method uses the `year` parameter, the property, and a year to calculate a 4-digit year. The century is determined by finding the sole occurrence of the `year` parameter within that 100-year range. For example, if is set to 5729, the 100-year range is from 5630 to 5729. Therefore, a value of 30 is interpreted as 5630, while a value of 29 is interpreted as 5729. - If the property has the special value 99, the method ignores the settings in the regional and language options in Control Panel and returns the value of the `year` parameter unchanged. + If the property has the special value 99, the method ignores the settings in the regional and language options in Control Panel and returns the value of the `year` parameter unchanged. supports either a two-digit year or a four-digit year. Passing a two-digit year value (less than 100) causes the method to convert the value to a four-digit value according to the value representing the appropriate century. If the application supplies a four-digit year value that is within the supported calendar range to , the method returns the actual input value. If the application supplies a four-digit value that is outside the supported calendar range, or if it supplies a negative value, the method throws an exception. @@ -1856,7 +1856,7 @@ property allows a 2-digit year to be properly translated to a 4-digit year. For example, if this property is set to 5729, the 100-year range is from 5630 to 5729. Therefore, a 2-digit value of 30 is interpreted as 5630, while a 2-digit value of 29 is interpreted as 5729. + The property allows a 2-digit year to be properly translated to a 4-digit year. For example, if this property is set to 5729, the 100-year range is from 5630 to 5729. Therefore, a 2-digit value of 30 is interpreted as 5630, while a 2-digit value of 29 is interpreted as 5729. The initial value of this property is derived from the settings in the regional and language options portion of Control Panel. If the initial system setting changes during the life of your application the class does not automatically detect the change. diff --git a/xml/System.Globalization/HijriCalendar.xml b/xml/System.Globalization/HijriCalendar.xml index 74f16ea1e85..dd7400f9235 100644 --- a/xml/System.Globalization/HijriCalendar.xml +++ b/xml/System.Globalization/HijriCalendar.xml @@ -107,9 +107,9 @@ The date January 1, 2001 A.D. in the Gregorian calendar is roughly equivalent to the sixth day of Shawwal in the year 1421 A.H. in the Hijri calendar. - This implementation of the class adjusts the calendar date by adding or subtracting a value from zero to two days to accommodate the variances in the start and the end of Ramadan and to accommodate the date difference between countries/regions. That value is stored in the property. If is not set explicitly, it derives its value from the settings in the regional and language options portion of Control Panel and is stored in the registry value HKEY_CURRENT_USER\Control Panel\International\AddHijriDate. However, that information can change during the life of the . The class does not detect changes in the system settings automatically. + This implementation of the class adjusts the calendar date by adding or subtracting a value from zero to two days to accommodate the variances in the start and the end of Ramadan and to accommodate the date difference between countries/regions. That value is stored in the property. If is not set explicitly, it derives its value from the settings in the regional and language options portion of Control Panel and is stored in the registry value HKEY_CURRENT_USER\Control Panel\International\AddHijriDate. However, that information can change during the life of the . The class does not detect changes in the system settings automatically. - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -223,7 +223,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -232,7 +232,7 @@ ## Examples The following code example displays the values of several components of a in terms of the Hijri calendar. - + :::code language="csharp" source="~/snippets/csharp/System.Globalization/HijriCalendar/AddMonths/hijricalendar_addget.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/HijriCalendar/AddMonths/hijricalendar_addget.vb" id="Snippet1"::: @@ -315,7 +315,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -392,7 +392,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -1310,7 +1310,7 @@ class adjusts the calendar date by adding or subtracting a value from zero to two days to accommodate the variances in the start and the end of Ramadan and to accommodate the date difference between countries/regions. That value is stored in the property. If is not set explicitly, it derives its value from the settings in the regional and language options portion of Control Panel and is stored in the registry value HKEY_CURRENT_USER\Control Panel\International\AddHijriDate. However, that information can change during the life of the . The class does not detect changes in the system settings automatically. + This implementation of the class adjusts the calendar date by adding or subtracting a value from zero to two days to accommodate the variances in the start and the end of Ramadan and to accommodate the date difference between countries/regions. That value is stored in the property. If is not set explicitly, it derives its value from the settings in the regional and language options portion of Control Panel and is stored in the registry value HKEY_CURRENT_USER\Control Panel\International\AddHijriDate. However, that information can change during the life of the . The class does not detect changes in the system settings automatically. diff --git a/xml/System.Globalization/IdnMapping.xml b/xml/System.Globalization/IdnMapping.xml index e88d16c4bbb..91d9a4c5173 100644 --- a/xml/System.Globalization/IdnMapping.xml +++ b/xml/System.Globalization/IdnMapping.xml @@ -196,10 +196,10 @@ property is `false`. The IDNA specification permits unassigned code points only in queries for matching strings (that is, in domain name lookup). For more information about the use of unassigned code points in domain names, see [RFC 3454, "Preparation of Internationalized Strings (stringprep)"](https://go.microsoft.com/fwlink/?LinkId=231873) and [RFC 5891, "Internationalized Domain Names in Applications (IDNA): Protocol"](https://go.microsoft.com/fwlink/?LinkId=231875). + A registered domain name cannot contain unassigned code points. Consequently, the default value of the property is `false`. The IDNA specification permits unassigned code points only in queries for matching strings (that is, in domain name lookup). For more information about the use of unassigned code points in domain names, see [RFC 3454, "Preparation of Internationalized Strings (stringprep)"](https://go.microsoft.com/fwlink/?LinkId=231873) and [RFC 5891, "Internationalized Domain Names in Applications (IDNA): Protocol"](https://go.microsoft.com/fwlink/?LinkId=231875). > [!IMPORTANT] -> If the property is `false`, the behavior associated with the property depends on the underlying operating system. On Windows 8, the class conforms to IDNA 2008, which is based on the Unicode 6.0 standard. On previous versions of Windows, the class is based on IDNA 2003, which is based on Unicode 3.*x*. Some code points that were unassigned in IDNA 2003 have been assigned characters and are supported in IDNA 2008. For example, U+0221 was introduced in Unicode 4.0. On Windows 8, it is encoded as "xn—6la". On previous versions of Windows, it throws an exception. +> If the property is `false`, the behavior associated with the property depends on the underlying operating system. On Windows 8, the class conforms to IDNA 2008, which is based on the Unicode 6.0 standard. On previous versions of Windows, the class is based on IDNA 2003, which is based on Unicode 3.*x*. Some code points that were unassigned in IDNA 2003 have been assigned characters and are supported in IDNA 2008. For example, U+0221 was introduced in Unicode 4.0. On Windows 8, it is encoded as "xn—6la". On previous versions of Windows, it throws an exception. ]]> @@ -330,9 +330,9 @@ - Unicode control characters from U+0001 through U+001F, and U+007F. -- Unassigned Unicode characters, if the value of the property is `false`. +- Unassigned Unicode characters, if the value of the property is `false`. -- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, if the value of the property is `true`. +- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, if the value of the property is `true`. - Characters that are prohibited by a specific version of the IDNA standard. For more information about prohibited characters, see [RFC 3454: Preparation of Internationalized Strings ("stringprep")](https://go.microsoft.com/fwlink/?LinkId=231873) for IDNA 2003, and [RFC 5982: The Unicode Code Points and Internationalized Domain Names for Applications](https://go.microsoft.com/fwlink/?LinkId=231877) for IDNA 2008. @@ -424,9 +424,9 @@ - Unicode control characters from U+0001 through U+001F, and U+007F. -- Unassigned Unicode characters, depending on the value of the property. +- Unassigned Unicode characters, depending on the value of the property. -- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, depending on the value of the property. +- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, depending on the value of the property. - Characters that are prohibited by a specific version of the IDNA standard. For more information about prohibited characters, see [RFC 3454: Preparation of Internationalized Strings ("stringprep")](https://go.microsoft.com/fwlink/?LinkId=231873) for IDNA 2003, and [RFC 5982: The Unicode Code Points and Internationalized Domain Names for Applications](https://go.microsoft.com/fwlink/?LinkId=231877) for IDNA 2008. @@ -520,9 +520,9 @@ - Unicode control characters from U+0001 through U+001F, and U+007F. -- Unassigned Unicode characters, depending on the value of the property. +- Unassigned Unicode characters, depending on the value of the property. -- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, depending on the value of the property. +- Non-standard characters in the US-ASCII character range, such as the SPACE (U+0020), EXCLAMATION MARK (U+0021), and LOW LINE (U+005F) characters, depending on the value of the property. - Characters that are prohibited by a specific version of the IDNA standard. For more information about prohibited characters, see [RFC 3454: Preparation of Internationalized Strings ("stringprep")](https://go.microsoft.com/fwlink/?LinkId=231873) for IDNA 2003, and [RFC 5982: The Unicode Code Points and Internationalized Domain Names for Applications](https://go.microsoft.com/fwlink/?LinkId=231877) for IDNA 2008. @@ -897,15 +897,15 @@ ## Remarks Domain names that follow standard naming rules consist of a specific subset of characters in the US-ASCII character range. The characters are the letters A through Z, the digits 0 through 9, the hyphen (-) character (U+002D), and the period (.) character. The case of the characters is not significant. Relaxed naming conventions allow the use of a broader range of ASCII characters, including the space character (U+0020), the exclamation point character (U+0021), and the underbar character (U+005F). If is `true`, only standard characters can appear in a label returned by the method. - By default, the value of the property is `false`, and an expanded subset of ASCII characters is permitted in a label. + By default, the value of the property is `false`, and an expanded subset of ASCII characters is permitted in a label. > [!NOTE] -> The class prohibits the use of the nondisplayable characters U+0000 through U+001F, and U+007F in domain name labels regardless of the setting of the property. This prohibition reduces the risk of security attacks such as name spoofing. +> The class prohibits the use of the nondisplayable characters U+0000 through U+001F, and U+007F in domain name labels regardless of the setting of the property. This prohibition reduces the risk of security attacks such as name spoofing. ## Examples - The following example generates URLs that contain characters in the ASCII range from U+0000 to U+007F and passes them to the method of two objects. One object has its property set to `true`, and the other object has it set to `false`. The output displays the characters that are invalid when the property is `true` but valid when it is `false`. + The following example generates URLs that contain characters in the ASCII range from U+0000 to U+007F and passes them to the method of two objects. One object has its property set to `true`, and the other object has it set to `false`. The output displays the characters that are invalid when the property is `true` but valid when it is `false`. :::code language="csharp" source="~/snippets/csharp/System.Globalization/IdnMapping/UseStd3AsciiRules/usestd3asciirules1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/IdnMapping/UseStd3AsciiRules/usestd3asciirules1.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/JapaneseLunisolarCalendar.xml b/xml/System.Globalization/JapaneseLunisolarCalendar.xml index cbdc6300b25..62db083e5fb 100644 --- a/xml/System.Globalization/JapaneseLunisolarCalendar.xml +++ b/xml/System.Globalization/JapaneseLunisolarCalendar.xml @@ -71,34 +71,34 @@ Represents time in divisions, such as months, days, and years. Years are calculated as for the Japanese calendar, while days and months are calculated using the lunisolar calendar. - class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. The method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. - + class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. The method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Class Library, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). - -The `JapaneseLuniSolarCalendar` class recognizes one era for every emperor's reign. For example, the two most recent eras are the Heisei era, beginning in the Gregorian calendar year 1989, and the Reiwa era, beginning in the Gregorian calendar year 2019. The era name is typically displayed before the year. For example, the Gregorian calendar year 2001 is the Japanese calendar year Heisei 13. Note that the first year of an era is called "Gannen." Therefore, the Gregorian calendar year 1989 was the Japanese calendar year Heisei Gannen. +> For information about using the class and the other calendar classes in the .NET Class Library, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). + +The `JapaneseLuniSolarCalendar` class recognizes one era for every emperor's reign. For example, the two most recent eras are the Heisei era, beginning in the Gregorian calendar year 1989, and the Reiwa era, beginning in the Gregorian calendar year 2019. The era name is typically displayed before the year. For example, the Gregorian calendar year 2001 is the Japanese calendar year Heisei 13. Note that the first year of an era is called "Gannen." Therefore, the Gregorian calendar year 1989 was the Japanese calendar year Heisei Gannen. [!INCLUDE[japanese-era-note](~/includes/calendar-era.md)] Unlike the class, the `JapaneseLunisolarCalendar` class does not support dates in the range of the Meiji and Taisho eras. - This class assigns numbers to the eras as follows: - -|GetEra value|Era Name|Era Abbreviation|Gregorian Dates| -|------------------|--------------|----------------------|---------------------| + This class assigns numbers to the eras as follows: + +|GetEra value|Era Name|Era Abbreviation|Gregorian Dates| +|------------------|--------------|----------------------|---------------------| |5|令和 (Reiwa)|令和 (R, r)|May 1, 2019 to present| -|4|平成 (Heisei)|平 (H, h)|January 8, 1989 to April 30, 2019| -|3|昭和 (Showa)|昭 (S, s)|December 25, 1926 to January 7, 1989| -|2|大正 (Taisho)|大 (T, t)|July 30, 1912 to December 24, 1926| -|1|明治 (Meiji)|明 (M, m)|September 8, 1868 to July 29, 1912| +|4|平成 (Heisei)|平 (H, h)|January 8, 1989 to April 30, 2019| +|3|昭和 (Showa)|昭 (S, s)|December 25, 1926 to January 7, 1989| +|2|大正 (Taisho)|大 (T, t)|July 30, 1912 to December 24, 1926| +|1|明治 (Meiji)|明 (M, m)|September 8, 1868 to July 29, 1912| + + Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Japanese lunisolar calendar. It cannot be used as the default calendar for any culture supported by the class. + + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. You can change the default calendar to any one of the optional calendars supported by a instance. To do this, set the property of the object returned by the property to the new . - Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Japanese lunisolar calendar. It cannot be used as the default calendar for any culture supported by the class. - - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. You can change the default calendar to any one of the optional calendars supported by a instance. To do this, set the property of the object returned by the property to the new . - ]]> @@ -188,11 +188,11 @@ Unlike the class, the `JapaneseLuni Gets the number of days in the year that precedes the year that is specified by the property. The number of days in the year that precedes the year specified by . - @@ -241,17 +241,17 @@ Unlike the class, the `JapaneseLuni Gets the eras that are relevant to the object. An array of 32-bit signed integers that specify the relevant eras. - defines the Meiji and Taisho eras (eras 1 and 2, respectively), the calendar does not support dates in their ranges. For example, a call to or with a date in those era ranges throws an . - The property returns the same values as the property. - + The property returns the same values as the property. + ]]> @@ -304,7 +304,7 @@ While the defines the Meij Retrieves the era that corresponds to the specified . An integer that represents the era specified in the parameter. - defines the Meij Specifies the current era. - is not used by any of the cultures supported by the class. Therefore, the class can be used only to calculate dates in the Julian calendar. - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -208,7 +208,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -217,7 +217,7 @@ ## Examples The following code example displays the values of several components of a in terms of the Julian calendar. - + :::code language="csharp" source="~/snippets/csharp/System.Globalization/JulianCalendar/AddMonths/juliancalendar_addget.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/JulianCalendar/AddMonths/juliancalendar_addget.vb" id="Snippet1"::: @@ -300,7 +300,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -377,7 +377,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/KoreanCalendar.xml b/xml/System.Globalization/KoreanCalendar.xml index 8506b6c728d..1eed15706a2 100644 --- a/xml/System.Globalization/KoreanCalendar.xml +++ b/xml/System.Globalization/KoreanCalendar.xml @@ -110,7 +110,7 @@ The date January 1, 2001 A.D. in the Gregorian calendar is equivalent to the first day of January in the year 4334 of the current era in the Korean calendar. - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -225,7 +225,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -234,7 +234,7 @@ ## Examples The following code example displays the values of several components of a in terms of the Korean calendar. - + :::code language="csharp" source="~/snippets/csharp/System.Globalization/KoreanCalendar/AddMonths/koreancalendar_addget.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/KoreanCalendar/AddMonths/koreancalendar_addget.vb" id="Snippet1"::: @@ -316,7 +316,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -394,7 +394,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -1204,9 +1204,9 @@ contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. - The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . - The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . For example, in , for January 1 returns 1. diff --git a/xml/System.Globalization/KoreanLunisolarCalendar.xml b/xml/System.Globalization/KoreanLunisolarCalendar.xml index c8aba37821f..ad915b98698 100644 --- a/xml/System.Globalization/KoreanLunisolarCalendar.xml +++ b/xml/System.Globalization/KoreanLunisolarCalendar.xml @@ -71,22 +71,22 @@ Represents time in divisions, such as months, days, and years. Years are calculated using the Gregorian calendar, while days and months are calculated using the lunisolar calendar. - class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. - + class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. + > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). - - The class calculates years using the Gregorian calendar, and days and months using the class. - - A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. - - Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Korean lunisolar calendar. - - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . - +> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). + + The class calculates years using the Gregorian calendar, and days and months using the class. + + A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + + Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Korean lunisolar calendar. + + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + ]]> @@ -176,11 +176,11 @@ Gets the number of days in the year that precedes the year specified by the property. The number of days in the year that precedes the year specified by . - @@ -325,13 +325,13 @@ Specifies the Gregorian era that corresponds to the current object. - class recognizes only the current era. - + class recognizes only the current era. + ]]> @@ -426,7 +426,7 @@ Gets the minimum date and time supported by the class. The earliest date and time supported by the class. - property is used with the "C" standard format string without a precision specifier in numeric formatting operations. It defines the default number of fractional digits that appear after the decimal separator. This value is overridden if a precision specifier is used. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). + The property is used with the "C" standard format string without a precision specifier in numeric formatting operations. It defines the default number of fractional digits that appear after the decimal separator. This value is overridden if a precision specifier is used. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/CurrencyDecimalDigits/currencydecimaldigits.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/CurrencyDecimalDigits/currencydecimaldigits.vb" id="Snippet1"::: @@ -360,10 +360,10 @@ ## Remarks On Windows, the initial value of this property is derived from the settings in the **Region and Language** item in Control Panel. - The property is used with the "C" standard format string to define the symbol that separates integral from fractional digits. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). + The property is used with the "C" standard format string to define the symbol that separates integral from fractional digits. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/CurrencyDecimalSeparator/currencydecimalseparator.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/CurrencyDecimalSeparator/currencydecimalseparator.vb" id="Snippet1"::: @@ -433,10 +433,10 @@ On Windows, the initial value of this property is derived from the settings in t ## Remarks On Windows, the initial value of this property is derived from the settings in the **Regional and Language** item in Control Panel. - The property is used with the "C" standard format string to define the symbol that separates groups of integral digits. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). + The property is used with the "C" standard format string to define the symbol that separates groups of integral digits. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/CurrencyGroupSeparator/currencygroupseparator.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/CurrencyGroupSeparator/currencygroupseparator.vb" id="Snippet1"::: @@ -503,14 +503,14 @@ On Windows, the initial value of this property is derived from the settings in t property is used with the "C" standard format string to define the number of digits that appear in integral groups. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). Every element in the one-dimensional array must be an integer from 1 through 9. The last element can be 0. + The property is used with the "C" standard format string to define the number of digits that appear in integral groups. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). Every element in the one-dimensional array must be an integer from 1 through 9. The last element can be 0. The first element of the array defines the number of elements in the least significant group of digits immediately to the left of the . Each subsequent element refers to the next significant group of digits to the left of the previous group. If the last element of the array is not 0, the remaining digits are grouped based on the last element of the array. If the last element is 0, the remaining digits are not grouped. For example, if the array contains { 3, 4, 5 }, the digits are grouped similar to "\\$55,55555,55555,55555,4444,333.00". If the array contains { 3, 4, 0 }, the digits are grouped similar to "\\$55555555555555555,4444,333.00". ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/CurrencyGroupSizes/currencygroupsizes.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/CurrencyGroupSizes/currencygroupsizes.vb" id="Snippet1"::: @@ -582,7 +582,7 @@ On Windows, the initial value of this property is derived from the settings in t property is used with the "C" standard format string to define the pattern of negative currency values. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). This property has one of the values in the following table. The symbol "$" is the , the symbol "-" is the , and `n` is a number. + The property is used with the "C" standard format string to define the pattern of negative currency values. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). This property has one of the values in the following table. The symbol "$" is the , the symbol "-" is the , and `n` is a number. | Value | Associated pattern | |-------|--------------------| @@ -605,7 +605,7 @@ On Windows, the initial value of this property is derived from the settings in t | 16 | $- n | ## Examples - The following example shows how the property defines the format of negative currency values. It retrieves all the specific cultures that are defined on the host computer and displays each culture's property value, its associated pattern, and a number formatted as a currency value. + The following example shows how the property defines the format of negative currency values. It retrieves all the specific cultures that are defined on the host computer and displays each culture's property value, its associated pattern, and a number formatted as a currency value. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/CurrencyNegativePattern/currencynegativepattern1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/CurrencyNegativePattern/currencynegativepattern1.vb" id="Snippet1"::: @@ -672,7 +672,7 @@ On Windows, the initial value of this property is derived from the settings in t property is used with the "C" standard format string to define pattern of positive currency values. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). This property has one of the values in the following table. The symbol "$" is the and `n` is a number. + The property is used with the "C" standard format string to define pattern of positive currency values. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). This property has one of the values in the following table. The symbol "$" is the and `n` is a number. | Value | Associated pattern | |-------|--------------------| @@ -744,7 +744,7 @@ The pattern does not support a positive sign. property is included in the result string when a numeric value is formatted with the "C" [standard numeric format string](/dotnet/standard/base-types/standard-numeric-format-strings). + The string assigned to the property is included in the result string when a numeric value is formatted with the "C" [standard numeric format string](/dotnet/standard/base-types/standard-numeric-format-strings). ## Examples The following example displays the currency symbol for the current culture and uses the "C" standard numeric format string to format a currency value. @@ -821,10 +821,10 @@ The pattern does not support a positive sign. object from the property is equivalent to retrieving a object from the `CultureInfo.CurrentCulture.NumberFormat` property. + Retrieving a object from the property is equivalent to retrieving a object from the `CultureInfo.CurrentCulture.NumberFormat` property. ## Examples - The following example shows that the objects returned by the and `CultureInfo.CurrentCulture.NumberFormat` properties are identical. It then uses reflection to display the property values of the object returned by the property on a system whose current culture is en-US. + The following example shows that the objects returned by the and `CultureInfo.CurrentCulture.NumberFormat` properties are identical. It then uses reflection to display the property values of the object returned by the property on a system whose current culture is en-US. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/CurrentInfo/currentinfo1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/CurrentInfo/currentinfo1.vb" id="Snippet1"::: @@ -886,7 +886,7 @@ The pattern does not support a positive sign. [!IMPORTANT] -> The property is reserved for future use. Currently, it is not used in either parsing or formatting operations for the current object. +> The property is reserved for future use. Currently, it is not used in either parsing or formatting operations for the current object. ]]> @@ -1032,7 +1032,7 @@ The pattern does not support a positive sign. Your application gets a object for a specific culture using one of the following methods: -- Through the property. +- Through the property. - Through the method where `provider` is a . A object is created only for the invariant culture or for specific cultures, not for neutral cultures. For more information about the invariant culture, specific cultures, and neutral cultures, see the class. @@ -1274,10 +1274,10 @@ The pattern does not support a positive sign. ## Remarks > [!IMPORTANT] -> The character set that's specified by the property has no effect on parsing or formatting operations. Only the Basic Latin digits 0 (U+0030) through 9 (U+0039) are used when formatting or parsing numeric values or date and time values. +> The character set that's specified by the property has no effect on parsing or formatting operations. Only the Basic Latin digits 0 (U+0030) through 9 (U+0039) are used when formatting or parsing numeric values or date and time values. ## Examples - The following example demonstrates the property. + The following example demonstrates the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/NativeDigits/nd.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/NativeDigits/nd.vb" id="Snippet1"::: @@ -1414,7 +1414,7 @@ The pattern does not support a positive sign. This property is used in both formatting and parsing operations. For more information on its use in formatting operations, see the [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) topics. ## Examples - The following example instantiates a read-write object that represents the invariant culture and assigns the OVERLINE character (U+203E) to its property. It then uses this object to format an array of negative floating-point numbers. + The following example instantiates a read-write object that represents the invariant culture and assigns the OVERLINE character (U+203E) to its property. It then uses this object to format an array of negative floating-point numbers. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/NegativeSign/negativesign1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/NegativeSign/negativesign1.vb" id="Snippet1"::: @@ -1474,10 +1474,10 @@ The pattern does not support a positive sign. property is used with the "F" and "N" standard format strings without a precision specifier in numeric formatting operations. It defines the default number of fractional digits that appear after the decimal separator. This value is overridden if a precision specifier is used. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). + The property is used with the "F" and "N" standard format strings without a precision specifier in numeric formatting operations. It defines the default number of fractional digits that appear after the decimal separator. This value is overridden if a precision specifier is used. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/NumberDecimalDigits/numberdecimaldigits.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/NumberDecimalDigits/numberdecimaldigits.vb" id="Snippet1"::: @@ -1543,12 +1543,12 @@ The pattern does not support a positive sign. property is used with the "E", "F", "G", "N", and "R" standard format strings to define the symbol that separates integral from fractional digits. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). + The property is used with the "E", "F", "G", "N", and "R" standard format strings to define the symbol that separates integral from fractional digits. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). On Windows, the initial value of this property is derived from the settings in the **Region and Language** item in Control Panel. ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/NumberDecimalSeparator/numberdecimalseparator.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/NumberDecimalSeparator/numberdecimalseparator.vb" id="Snippet1"::: @@ -1615,12 +1615,12 @@ On Windows, the initial value of this property is derived from the settings in t property is used with the "N" standard format string to define the symbol that separates groups of integral digits. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). + The property is used with the "N" standard format string to define the symbol that separates groups of integral digits. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). On Windows, the initial value of this property is derived from the settings in the **Region and Language** item in Control Panel. ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/NumberGroupSeparator/numbergroupseparator.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/NumberGroupSeparator/numbergroupseparator.vb" id="Snippet1"::: @@ -1686,7 +1686,7 @@ On Windows, the initial value of this property is derived from the settings in t property affects the result of number values that are formatted by using the "N" . If a custom numeric format string or other standard numeric format strings are used, the value of the property is ignored. + The value of the property affects the result of number values that are formatted by using the "N" . If a custom numeric format string or other standard numeric format strings are used, the value of the property is ignored. Every element in the one-dimensional array must be an integer from 1 through 9. The last element can be 0. @@ -1695,7 +1695,7 @@ On Windows, the initial value of this property is derived from the settings in t For example, if the array contains { 3, 4, 5 }, the digits are grouped similar to "55,55555,55555,55555,4444,333.00". If the array contains { 3, 4, 0 }, the digits are grouped similar to "55555555555555555,4444,333.00". ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/NumberGroupSizes/numbergroupsizes.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/NumberGroupSizes/numbergroupsizes.vb" id="Snippet1"::: @@ -1771,7 +1771,7 @@ On Windows, the initial value of this property is derived from the settings in t property defines the format of negative values formatted with the "N" standard numeric format string. This property has one of the values in the following table. The symbol "-" is the and `n` is a number. + The property defines the format of negative values formatted with the "N" standard numeric format string. This property has one of the values in the following table. The symbol "-" is the and `n` is a number. | Value | Associated pattern | |-------|--------------------| @@ -1781,7 +1781,7 @@ On Windows, the initial value of this property is derived from the settings in t | 3 | n- | | 4 | n - | - The default value for the invariant culture returned by the property is 1, which represents "-n", where *n* is a number. + The default value for the invariant culture returned by the property is 1, which represents "-n", where *n* is a number. ## Examples The following example displays a value using different patterns. @@ -1850,10 +1850,10 @@ On Windows, the initial value of this property is derived from the settings in t property is used with the "P" standard format string without a precision specifier in numeric formatting operations. It defines the default number of fractional digits that appear after the decimal separator. This value is overridden if a precision specifier is used. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). + The property is used with the "P" standard format string without a precision specifier in numeric formatting operations. It defines the default number of fractional digits that appear after the decimal separator. This value is overridden if a precision specifier is used. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/PercentDecimalDigits/percentdecimaldigits.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/PercentDecimalDigits/percentdecimaldigits.vb" id="Snippet1"::: @@ -1920,10 +1920,10 @@ On Windows, the initial value of this property is derived from the settings in t property is used with the "P" standard format string to define the symbol that separates integral from fractional digits. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). + The property is used with the "P" standard format string to define the symbol that separates integral from fractional digits. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/PercentDecimalSeparator/percentdecimalseparator.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/PercentDecimalSeparator/percentdecimalseparator.vb" id="Snippet1"::: @@ -1991,10 +1991,10 @@ On Windows, the initial value of this property is derived from the settings in t property is used with the "P" standard format string to define the symbol that separates groups of integers. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). + The property is used with the "P" standard format string to define the symbol that separates groups of integers. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/PercentGroupSeparator/percentgroupseparator.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/PercentGroupSeparator/percentgroupseparator.vb" id="Snippet1"::: @@ -2061,14 +2061,14 @@ On Windows, the initial value of this property is derived from the settings in t property is used with the "P" standard format string to define the number of digits that appear in integral groups. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). Every element in the one-dimensional array must be an integer from 1 through 9. The last element can be 0. + The property is used with the "P" standard format string to define the number of digits that appear in integral groups. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). Every element in the one-dimensional array must be an integer from 1 through 9. The last element can be 0. The first element of the array defines the number of elements in the least significant group of digits immediately to the left of the . Each subsequent element refers to the next significant group of digits to the left of the previous group. If the last element of the array is not 0, the remaining digits are grouped based on the last element of the array. If the last element is 0, the remaining digits are not grouped. For example, if the array contains { 3, 4, 5 }, the digits are grouped similar to "55,55555,55555,55555,4444,333.00%". If the array contains { 3, 4, 0 }, the digits are grouped similar to "55555555555555555,4444,333.00%". ## Examples - The following example demonstrates the effect of changing the property. + The following example demonstrates the effect of changing the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/NumberFormatInfo/PercentGroupSizes/percentgroupsizes.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/NumberFormatInfo/PercentGroupSizes/percentgroupsizes.vb" id="Snippet1"::: @@ -2140,7 +2140,7 @@ On Windows, the initial value of this property is derived from the settings in t property is used with the "P" standard format string to define the pattern of negative percentage values. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). This property has one of the values in the following table. The symbol "%" is the , the symbol "-" is the , and `n` is a number. + The property is used with the "P" standard format string to define the pattern of negative percentage values. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). This property has one of the values in the following table. The symbol "%" is the , the symbol "-" is the , and `n` is a number. | Value | Associated pattern | |-------|--------------------| @@ -2219,7 +2219,7 @@ On Windows, the initial value of this property is derived from the settings in t property is used with the "P" standard format string to define pattern of positive percentage values. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). This property has one of the values in the following table. The symbol "%" is the and `n` is a number. + The property is used with the "P" standard format string to define pattern of positive percentage values. For more information, see [Standard Numeric Format Strings](/dotnet/standard/base-types/standard-numeric-format-strings). This property has one of the values in the following table. The symbol "%" is the and `n` is a number. | Value | Associated pattern | |-------|--------------------| @@ -2289,7 +2289,7 @@ On Windows, the initial value of this property is derived from the settings in t property is included in the result string when a numeric value is formatted with the "P" or with a format string that includes the "%" . + The string assigned to the property is included in the result string when a numeric value is formatted with the "P" or with a format string that includes the "%" . ]]> @@ -2354,7 +2354,7 @@ On Windows, the initial value of this property is derived from the settings in t property is included in the result string when a numeric value is formatted with a format string that includes the "‰" . + The string assigned to the property is included in the result string when a numeric value is formatted with a format string that includes the "‰" . ]]> diff --git a/xml/System.Globalization/PersianCalendar.xml b/xml/System.Globalization/PersianCalendar.xml index 0f439ea920c..9fd6272a525 100644 --- a/xml/System.Globalization/PersianCalendar.xml +++ b/xml/System.Globalization/PersianCalendar.xml @@ -195,7 +195,7 @@ property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -270,7 +270,7 @@ property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -342,7 +342,7 @@ ## Examples - The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -398,7 +398,7 @@ property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/PersianCalendar/Overview/pcal.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/PersianCalendar/Overview/pcal.vb" id="Snippet1"::: @@ -1325,14 +1325,14 @@ property is the last moment of December 31, 9999 C.E. in the Gregorian calendar. In the .NET Framework 4.6, this value is equivalent to the 13th day of the 10th month of the year 9378 in the Persian calendar. In previous versions of the .NET Framework, it is equivalent to the 10th day of the 10th month of the year 9378 in the Persian calendar. For more information, see "The PersianCalendar class and .NET Framework versions" in the topic. + The value of the property is the last moment of December 31, 9999 C.E. in the Gregorian calendar. In the .NET Framework 4.6, this value is equivalent to the 13th day of the 10th month of the year 9378 in the Persian calendar. In previous versions of the .NET Framework, it is equivalent to the 10th day of the 10th month of the year 9378 in the Persian calendar. For more information, see "The PersianCalendar class and .NET Framework versions" in the topic. 9999 C.E. is equivalent to the year 9378 in the Persian calendar. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/PersianCalendar/Overview/pcal.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/PersianCalendar/Overview/pcal.vb" id="Snippet1"::: @@ -1389,14 +1389,14 @@ property is equivalent to the first moment of March 22, 622 C.E. in the Gregorian calendar. In previous versions of the .NET Framework, it is equivalent to the first moment of March 21, 622 C.E. in the Gregorian calendar. For more information, see "The PersianCalendar class and .NET Framework versions" in the topic. + Starting with the .NET Framework 4.6, the value of the property is equivalent to the first moment of March 22, 622 C.E. in the Gregorian calendar. In previous versions of the .NET Framework, it is equivalent to the first moment of March 21, 622 C.E. in the Gregorian calendar. For more information, see "The PersianCalendar class and .NET Framework versions" in the topic. 622 C.E. is equivalent to the year 0001 in the Persian calendar. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/PersianCalendar/Overview/pcal.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/PersianCalendar/Overview/pcal.vb" id="Snippet1"::: @@ -1602,7 +1602,7 @@ property. The return value is the upper boundary of a 100-year range that allows a two-digit year to be properly translated to a four-digit year. For example, if the 100-year range is from 1930 through 2029, then a two-digit value of 30 is interpreted as 1930 while a two-digit value of 29 is interpreted as 2029. + This method converts the `year` parameter to a four-digit year representation using the property. The return value is the upper boundary of a 100-year range that allows a two-digit year to be properly translated to a four-digit year. For example, if the 100-year range is from 1930 through 2029, then a two-digit value of 30 is interpreted as 1930 while a two-digit value of 29 is interpreted as 2029. supports either a two-digit year or a four-digit year. Passing a two-digit year value (less than 100) causes the method to convert the value to a four-digit value according to the value representing the appropriate century. If the application supplies a four-digit year value that is within the supported calendar range to , the method returns the actual input value. If the application supplies a four-digit value that is outside the supported calendar range, or if it supplies a negative value, the method throws an exception. @@ -1677,7 +1677,7 @@ ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/PersianCalendar/Overview/pcal.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/PersianCalendar/Overview/pcal.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/RegionInfo.xml b/xml/System.Globalization/RegionInfo.xml index 49a020c849a..255d3cdf57d 100644 --- a/xml/System.Globalization/RegionInfo.xml +++ b/xml/System.Globalization/RegionInfo.xml @@ -160,7 +160,7 @@ The culture identifier is mapped to the corresponding National Language Support (NLS) locale identifier. For more information, see [Windows LCID reference](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c). -The value of the property of the new object instantiated by calling this constructor is the ISO 3166 2-letter code for the country/region, not the combined language and country/region code. For example, if a object is instantiated with the culture identifier 0x0409 for the English (United States) culture, the value of the property is "US". In contrast, if a object is instantiated with the combined language and country/region code `en-US` for the English (United States) culture, the value of the property is "en-US" in .NET Framework and just "US" in .NET Core and .NET 5+. +The value of the property of the new object instantiated by calling this constructor is the ISO 3166 2-letter code for the country/region, not the combined language and country/region code. For example, if a object is instantiated with the culture identifier 0x0409 for the English (United States) culture, the value of the property is "US". In contrast, if a object is instantiated with the combined language and country/region code `en-US` for the English (United States) culture, the value of the property is "en-US" in .NET Framework and just "US" in .NET Core and .NET 5+. ## Examples @@ -328,7 +328,7 @@ The following code example compares two instances of property. +The following code example demonstrates the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/RegionInfo/CurrencyEnglishName/rgn5props.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/RegionInfo/CurrencyEnglishName/rgn5props.vb" id="Snippet1"::: @@ -393,11 +393,11 @@ The following code example demonstrates the object is created with a specific culture and more than one language is used in the corresponding country/region, the property retrieves the currency name associated with the specific culture. -The value of this property depends on the language that's associated with a particular country/region. Therefore, if you intend to use the property, you should instantiate the object by passing the constructor a combined language and country/region code. For example, if a object is instantiated with a combined language and country/region code of "en-CA" for English (Canada), the value of its property is "Canadian Dollar". If it is instantiated with a combined language and country/region code of "fr-CA" for French (Canada), the value of its property is "Dollar canadien". Therefore, creating the `RegionInfo` object with only a country/region name ("CA" in this case) is not specific enough to distinguish the appropriate native currency name. +The value of this property depends on the language that's associated with a particular country/region. Therefore, if you intend to use the property, you should instantiate the object by passing the constructor a combined language and country/region code. For example, if a object is instantiated with a combined language and country/region code of "en-CA" for English (Canada), the value of its property is "Canadian Dollar". If it is instantiated with a combined language and country/region code of "fr-CA" for French (Canada), the value of its property is "Dollar canadien". Therefore, creating the `RegionInfo` object with only a country/region name ("CA" in this case) is not specific enough to distinguish the appropriate native currency name. ## Examples -The following code example demonstrates the property. +The following code example demonstrates the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/RegionInfo/CurrencyEnglishName/rgn5props.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/RegionInfo/CurrencyEnglishName/rgn5props.vb" id="Snippet1"::: @@ -461,7 +461,7 @@ The following code example demonstrates the object is created with a specific culture and more than one language is used in the corresponding country/region, the property returns the currency symbol associated with the specific culture. +If the current object is created with a specific culture and more than one language is used in the corresponding country/region, the property returns the currency symbol associated with the specific culture. ## Examples @@ -528,7 +528,7 @@ The following code example displays the properties of the . The class does not automatically detect changes in the system settings, but the property is updated when you call the method. +The value of this property is based on the culture selected through the regional and language options portion of Control Panel. However, that information can change during the life of the . The class does not automatically detect changes in the system settings, but the property is updated when you call the method. ]]> @@ -587,9 +587,9 @@ The value of this property is based on the culture selected through the regional property displays the country/region name in the language of the localized version of .NET. For example, the property displays the country/region in English on the English version of .NET, and in Spanish on the Spanish version of .NET. +The property displays the country/region name in the language of the localized version of .NET. For example, the property displays the country/region in English on the English version of .NET, and in Spanish on the Spanish version of .NET. -The value of the property is taken from the resource files in the language of the current user interface culture, represented by . Custom regions or those synthesized from the operating system might not have resource information, in which case the value for is the same as the value of the property. +The value of the property is taken from the resource files in the language of the current user interface culture, represented by . Custom regions or those synthesized from the operating system might not have resource information, in which case the value for is the same as the value of the property. ## Examples @@ -802,13 +802,13 @@ The following code example compares two instances of property to provide culture-specific services to customers. For example, the property can be used as a key to access a database record that contains specific information about a country/region. +The application should use the property to provide culture-specific services to customers. For example, the property can be used as a key to access a database record that contains specific information about a country/region. This property value corresponds to the Windows `GetUserGeoID` function. For a list of geographical identifiers, see [Table of Geographical Locations](/windows/win32/intl/table-of-geographical-locations). ## Examples -The following code example demonstrates the property. +The following code example demonstrates the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/RegionInfo/CurrencyEnglishName/rgn5props.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/RegionInfo/CurrencyEnglishName/rgn5props.vb" id="Snippet1"::: @@ -1176,9 +1176,9 @@ The following code example displays the properties of the object is created with the constructor that takes a culture identifier parameter, the property value is one of the two-letter codes defined in ISO 3166 for the country/region and is formatted in uppercase. For example, the two-letter code for the United States is "US". +If the current object is created with the constructor that takes a culture identifier parameter, the property value is one of the two-letter codes defined in ISO 3166 for the country/region and is formatted in uppercase. For example, the two-letter code for the United States is "US". -If the current object is created with the constructor and is passed a full culture name such as "en-US", the property value is a full culture name in .NET Framework and just the region name in .NET Core and .NET 5+. +If the current object is created with the constructor and is passed a full culture name such as "en-US", the property value is a full culture name in .NET Framework and just the region name in .NET Core and .NET 5+. ## Examples @@ -1259,7 +1259,7 @@ We recommend that you use the culture name–for example, "en-US" for Englis ## Examples -The following code example demonstrates the property. +The following code example demonstrates the property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/RegionInfo/CurrencyEnglishName/rgn5props.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/RegionInfo/CurrencyEnglishName/rgn5props.vb" id="Snippet1"::: diff --git a/xml/System.Globalization/SortKey.xml b/xml/System.Globalization/SortKey.xml index eab41bb6af9..4597354001b 100644 --- a/xml/System.Globalization/SortKey.xml +++ b/xml/System.Globalization/SortKey.xml @@ -344,7 +344,7 @@ property in comparing strings, see the class topic. + For more information about the use of the data returned by the property in comparing strings, see the class topic. @@ -457,7 +457,7 @@ object, and the value of the property. + The return value is the concatenation of the string "SortKey - ", the culture identifier and compare options of the current object, and the value of the property. This method overrides . diff --git a/xml/System.Globalization/SortVersion.xml b/xml/System.Globalization/SortVersion.xml index ba780181c00..a015b7ce288 100644 --- a/xml/System.Globalization/SortVersion.xml +++ b/xml/System.Globalization/SortVersion.xml @@ -120,7 +120,7 @@ object with the specified version and sort ID. The `fullVersion` argument is assigned to the property. The `sortId` argument is assigned to the property. + This constructor instantiates a object with the specified version and sort ID. The `fullVersion` argument is assigned to the property. The `sortId` argument is assigned to the property. This constructor is useful for recreating a object from data that has been serialized or saved. This version can then be compared with the current application version to determine whether the version of Unicode used to display and order the application's strings is available. @@ -305,7 +305,7 @@ property reflects the Unicode version used to normalize and compare strings. + The value of the property reflects the Unicode version used to normalize and compare strings. ]]> @@ -458,7 +458,7 @@ objects are not equal if one is `null` and the other is not, or if they have different or property values. + Two objects are not equal if one is `null` and the other is not, or if they have different or property values. ]]> @@ -507,7 +507,7 @@ property reflects the culture whose conventions influence string comparison and sorting. + The value of the property reflects the culture whose conventions influence string comparison and sorting. ]]> diff --git a/xml/System.Globalization/StringInfo.xml b/xml/System.Globalization/StringInfo.xml index fcc28c4b554..8fc2e1aa504 100644 --- a/xml/System.Globalization/StringInfo.xml +++ b/xml/System.Globalization/StringInfo.xml @@ -89,7 +89,7 @@ To instantiate a object that represents a - Call the constructor and pass it the string that the object is to represent as an argument. -- Call the default constructor, and assign the string that the object is to represent to the property. +- Call the default constructor, and assign the string that the object is to represent to the property. You can work with the individual text elements in a string in two ways: @@ -178,7 +178,7 @@ This example uses the object is initialized to the empty string (""). You can assign another string to it by using the property. You can also instantiate a object that represents a specified string in a single step by calling the constructor. + The value of the new object is initialized to the empty string (""). You can assign another string to it by using the property. You can also instantiate a object that represents a specified string in a single step by calling the constructor. ]]> @@ -232,7 +232,7 @@ This example uses the property. + This constructor assigns the value argument to the object's property. ]]> @@ -953,7 +953,7 @@ A grapheme cluster is a sequence of one or more Unicode code points that should The length of each element is easily computed as the difference between successive indexes. The length of the array will always be less than or equal to the length of the string. For example, given the string "\u4f00\u302a\ud800\udc00\u4f01", this method returns the indexes 0, 2, and 4. ## Equivalent Members - Starting in version 2.0 of the .NET Framework, the method and property provide an easy to use implementation of the functionality offered by the method. + Starting in version 2.0 of the .NET Framework, the method and property provide an easy to use implementation of the functionality offered by the method. @@ -1018,9 +1018,9 @@ A grapheme cluster is a sequence of one or more Unicode code points that should object is instantiated, its property is set to one of the following values: + When a object is instantiated, its property is set to one of the following values: -- if the default is called. You should then use the property to assign the string that this object rperesents. +- if the default is called. You should then use the property to assign the string that this object rperesents. - The string supplied as the `value` argument to the constructor. diff --git a/xml/System.Globalization/TaiwanCalendar.xml b/xml/System.Globalization/TaiwanCalendar.xml index 09349e43305..d3f3e9c41a7 100644 --- a/xml/System.Globalization/TaiwanCalendar.xml +++ b/xml/System.Globalization/TaiwanCalendar.xml @@ -108,7 +108,7 @@ The date January 1, 2001 C.E. in the Gregorian calendar is equivalent to the first day of January in the year 90 of the current era in the Taiwan calendar. - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -226,7 +226,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -235,7 +235,7 @@ ## Examples The following code example demonstrates the use of the method. - + :::code language="csharp" source="~/snippets/csharp/System.Globalization/TaiwanCalendar/AddMonths/taiwancalendar_addget.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/TaiwanCalendar/AddMonths/taiwancalendar_addget.vb" id="Snippet1"::: @@ -313,7 +313,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -384,7 +384,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -1160,11 +1160,11 @@ ## Remarks This method can be used to determine the number of weeks in the year by setting the `time` parameter to the last day of the year. - The property contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. + The property contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. - The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . - The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . For example, in , the method for January 1 returns 1. diff --git a/xml/System.Globalization/TaiwanLunisolarCalendar.xml b/xml/System.Globalization/TaiwanLunisolarCalendar.xml index 96a9cbc8966..5fff0acb896 100644 --- a/xml/System.Globalization/TaiwanLunisolarCalendar.xml +++ b/xml/System.Globalization/TaiwanLunisolarCalendar.xml @@ -71,22 +71,22 @@ Represents the Taiwan lunisolar calendar. As for the Taiwan calendar, years are calculated using the Gregorian calendar, while days and months are calculated using the lunisolar calendar. - class calculates years using the Gregorian calendar, days and months using the class, and recognizes only the current era. - + class calculates years using the Gregorian calendar, days and months using the class, and recognizes only the current era. + > [!NOTE] -> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). - - The class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. - - A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. - - Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Taiwan lunisolar calendar. - - Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . - +> For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). + + The class is derived from the class, which represents the lunisolar calendar. The class supports the sexagenary year cycle (which repeats every 60 years) in addition to solar years and lunar months. Each solar year in the calendar is associated with a Sexagenary Year, a Celestial Stem, and a Terrestrial Branch, and these calendars can have leap months after any month of the year. + + A leap month can occur after any month in a year. For example, the method returns a number between 1 and 13 that indicates the month associated with a specified date. If there is a leap month between the eighth and ninth months of the year, the method returns 8 for the eighth month, 9 for the leap eighth month, and 10 for the ninth month. + + Currently, the is not used by any of the cultures supported by the class. Therefore, this class can be used only to calculate dates in the Taiwan lunisolar calendar. + + Each object supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + ]]> @@ -176,11 +176,11 @@ Gets the number of days in the year that precedes the year specified by the property. The number of days in the year that precedes the year specified by . - @@ -229,11 +229,11 @@ Gets the eras that are relevant to the current object. An array that consists of a single element having a value that is always the current era. - diff --git a/xml/System.Globalization/TextElementEnumerator.xml b/xml/System.Globalization/TextElementEnumerator.xml index 78b173e4f76..32052347ada 100644 --- a/xml/System.Globalization/TextElementEnumerator.xml +++ b/xml/System.Globalization/TextElementEnumerator.xml @@ -94,9 +94,9 @@ The class allows you to work with the text elements in a string rather than with single objects. - You instantiate a object that represents a particular string by passing the string to the method. This returns an enumerator that is positioned before the first text element in the string. Calling the method also brings the enumerator back to this position. Because this represents an invalid state, you must call to advance the enumerator to the first text element of the string before reading the value of the property to return the current text element. + You instantiate a object that represents a particular string by passing the string to the method. This returns an enumerator that is positioned before the first text element in the string. Calling the method also brings the enumerator back to this position. Because this represents an invalid state, you must call to advance the enumerator to the first text element of the string before reading the value of the property to return the current text element. - When working with a object, you are responsible for positioning the enumerator. The property returns the same text element until you call either or . The enumerator is in an invalid state if it is positioned before the first text element or after the last text element in the string. When the enumerator is in an invalid state, attempting to retrieve the value of the property throws an exception. You can determine whether the enumerator is in an invalid state by testing whether the return value of the property is `false`. + When working with a object, you are responsible for positioning the enumerator. The property returns the same text element until you call either or . The enumerator is in an invalid state if it is positioned before the first text element or after the last text element in the string. When the enumerator is in an invalid state, attempting to retrieve the value of the property throws an exception. You can determine whether the enumerator is in an invalid state by testing whether the return value of the property is `false`. The object represents a snapshot of the current state of a string variable or string literal at the moment that the object is instantiated. Note that: @@ -286,7 +286,7 @@ property. + This method returns the same text element as the property. ]]> diff --git a/xml/System.Globalization/TextInfo.xml b/xml/System.Globalization/TextInfo.xml index 34a65a86f2e..906e8f7bbd3 100644 --- a/xml/System.Globalization/TextInfo.xml +++ b/xml/System.Globalization/TextInfo.xml @@ -105,9 +105,9 @@ A writing system is the collection of scripts and orthographic rules required to represent a language as text. The class represents a writing system. -The application should use the property to obtain the object for a particular object. If a security decision depends on a string comparison or a case-change operation, the application should use the property of the object returned by the property to ensure that the behavior of the operation is consistent regardless of the operating system culture settings. +The application should use the property to obtain the object for a particular object. If a security decision depends on a string comparison or a case-change operation, the application should use the property of the object returned by the property to ensure that the behavior of the operation is consistent regardless of the operating system culture settings. -The user might use the regional and language options portion of Control Panel to override the values associated with the current culture of Windows. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the property is set to `true`, the property values of the objects returned by the , , and properties are also retrieved from the user settings. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. +The user might use the regional and language options portion of Control Panel to override the values associated with the current culture of Windows. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the property is set to `true`, the property values of the objects returned by the , , and properties are also retrieved from the user settings. If the user settings are incompatible with the culture associated with the , for example, if the selected calendar is not one of the , the results of the methods and the values of the properties are undefined. ]]> @@ -294,11 +294,11 @@ The user might use the regional and language options portion of Control Panel to object is created from a specific culture, and the property returns the name of that culture. + A object is created from a specific culture, and the property returns the name of that culture. - The property always reflects a specific culture rather than a neutral culture. If has a neutral culture as its value, then the corresponding has as its value an arbitrary specific culture that uses the same language. For example, the property returns "en" for the English neutral culture, but the corresponding property might return "en-US" for the English (United States) culture. If the object is associated with a specific culture instead of a neutral culture, the value of its property is always identical to the property value of its associated object. + The property always reflects a specific culture rather than a neutral culture. If has a neutral culture as its value, then the corresponding has as its value an arbitrary specific culture that uses the same language. For example, the property returns "en" for the English neutral culture, but the corresponding property might return "en-US" for the English (United States) culture. If the object is associated with a specific culture instead of a neutral culture, the value of its property is always identical to the property value of its associated object. - Similarly, the property never reflects a particular sort. It always corresponds to a default sort order. For example, the default sort order for Spanish (Spain) is the international sort order. If is es-ES_tradnl (Spanish with the traditional sort order) then the corresponding is es-ES (Spanish with the default international sort order). + Similarly, the property never reflects a particular sort. It always corresponds to a default sort order. For example, the default sort order for Spanish (Spain) is the international sort order. If is es-ES_tradnl (Spanish with the traditional sort order) then the corresponding is es-ES (Spanish with the default international sort order). ]]> @@ -537,7 +537,7 @@ The user might use the regional and language options portion of Control Panel to property is `true`, the application cannot change any of the properties of the current object. + If the property is `true`, the application cannot change any of the properties of the current object. ]]> @@ -600,7 +600,7 @@ The user might use the regional and language options portion of Control Panel to property indicates the dominant direction of written text and the relative position of user interface elements such as buttons and scroll bars. + The property indicates the dominant direction of written text and the relative position of user interface elements such as buttons and scroll bars. ]]> @@ -660,9 +660,9 @@ The user might use the regional and language options portion of Control Panel to Certain predefined culture names and identifiers are used by this and other classes in the namespace. For detailed culture information for Windows systems, see the **Language tag** column in the [list of language/region names supported by Windows](https://learn.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). -The property always reflects a specific culture identifier instead of a neutral culture identifier. If is set to a neutral culture identifier, the corresponding has as its value an arbitrary specific culture identifier that uses the same language. For example, the property returns 0x0009 for the English neutral culture, named "en". However, the corresponding property might return 0x0409 for the English (United States) culture, named en-US. +The property always reflects a specific culture identifier instead of a neutral culture identifier. If is set to a neutral culture identifier, the corresponding has as its value an arbitrary specific culture identifier that uses the same language. For example, the property returns 0x0009 for the English neutral culture, named "en". However, the corresponding property might return 0x0409 for the English (United States) culture, named en-US. - Similarly, the property always corresponds to a default sort order, and never reflects a specific sort order. For example, the default sort order for Spanish (Spain) is the international sort order. If is set to "0x040A" (Spanish with the traditional sort order), the corresponding value is "0x0C0A" (Spanish with the default international sort order). + Similarly, the property always corresponds to a default sort order, and never reflects a specific sort order. For example, the default sort order for Spanish (Spain) is the international sort order. If is set to "0x040A" (Spanish with the traditional sort order), the corresponding value is "0x0C0A" (Spanish with the default international sort order). ]]> diff --git a/xml/System.Globalization/ThaiBuddhistCalendar.xml b/xml/System.Globalization/ThaiBuddhistCalendar.xml index b25301b3507..fa040ce996a 100644 --- a/xml/System.Globalization/ThaiBuddhistCalendar.xml +++ b/xml/System.Globalization/ThaiBuddhistCalendar.xml @@ -110,7 +110,7 @@ The date January 1, 2001 A.D. in the Gregorian calendar is equivalent to the first day of January in the year 2544 of the current era in the Thai Buddhist calendar. - Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . + Each supports a set of calendars. The property returns the default calendar for the culture, and the property returns an array containing all the calendars supported by the culture. To change the calendar used by a , the application should set the property of to a new . ]]> @@ -224,7 +224,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -233,7 +233,7 @@ ## Examples The following example demonstrates the use of the method. - + :::code language="csharp" source="~/snippets/csharp/System.Globalization/ThaiBuddhistCalendar/AddMonths/thaibuddhistcalendar_addget.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/ThaiBuddhistCalendar/AddMonths/thaibuddhistcalendar_addget.vb" id="Snippet1"::: @@ -310,7 +310,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -381,7 +381,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -1161,9 +1161,9 @@ contains culture-specific values that can be used for the `rule` and `firstDayOfWeek` parameters. - The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that represents the first day of the week for a specific culture, using the calendar specified in the property of . - The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . + The property of contains the default value that defines a calendar week for a specific culture, using the calendar specified in the property of . For example, in , for January 1 returns 1. diff --git a/xml/System.Globalization/UmAlQuraCalendar.xml b/xml/System.Globalization/UmAlQuraCalendar.xml index 869a42771e0..3e6d0944435 100644 --- a/xml/System.Globalization/UmAlQuraCalendar.xml +++ b/xml/System.Globalization/UmAlQuraCalendar.xml @@ -74,7 +74,7 @@ class is nearly identical to the class, except the Um Al Qura calendar uses a table-based algorithm licensed from the Saudi government to calculate dates, can express dates to the year 1500 A.H., and does not support the property. + The class is nearly identical to the class, except the Um Al Qura calendar uses a table-based algorithm licensed from the Saudi government to calculate dates, can express dates to the year 1500 A.H., and does not support the property. > [!NOTE] > For information about using the class and the other calendar classes in the .NET Framework, see [Working with Calendars](/dotnet/standard/datetime/working-with-calendars). @@ -195,7 +195,7 @@ If the value of the `months` parameter is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet5"::: @@ -278,7 +278,7 @@ If `years` is negative, the resulting is earlier than the specified . - The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. + The property of the returned value always equals . You can preserve the property of the `time` parameter by calling the method, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AddDays/add1.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AddDays/add1.vb" id="Snippet8"::: @@ -347,7 +347,7 @@ type found in the .NET Framework and displays the value of its property. + The following example uses reflection to instantiate each type found in the .NET Framework and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Globalization/Calendar/AlgorithmType/algorithmtype1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/Calendar/AlgorithmType/algorithmtype1.vb" id="Snippet1"::: @@ -1192,7 +1192,7 @@ ## Examples The following example calls the method for the last day of the second month (February) for five years in each of the eras. - + :::code language="csharp" source="~/snippets/csharp/System.Globalization/HijriCalendar/IsLeapDay/hijricalendar_isleapday.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Globalization/HijriCalendar/IsLeapDay/hijricalendar_isleapday.vb" id="Snippet1"::: @@ -1384,7 +1384,7 @@ ## Remarks > [!NOTE] -> Starting with the .NET Framework 4.5, the value of the property is 11/16/2077. In previous versions of the .NET Framework, its value is the last moment of May 13, 2029 C.E. in the Gregorian calendar. +> Starting with the .NET Framework 4.5, the value of the property is 11/16/2077. In previous versions of the .NET Framework, its value is the last moment of May 13, 2029 C.E. in the Gregorian calendar. @@ -1594,9 +1594,9 @@ method uses the `year` parameter, the property, and a year to calculate a 4-digit year. The century is determined by finding the sole occurrence of the 2-digit `year` parameter within that 100-year range. For example, if is set to 1429, the 100-year range is from 1330 through 1429. Therefore, a 2-digit value of 30 is interpreted as 1330, while a 2-digit value of 29 is interpreted as 1429. + The method uses the `year` parameter, the property, and a year to calculate a 4-digit year. The century is determined by finding the sole occurrence of the 2-digit `year` parameter within that 100-year range. For example, if is set to 1429, the 100-year range is from 1330 through 1429. Therefore, a 2-digit value of 30 is interpreted as 1330, while a 2-digit value of 29 is interpreted as 1429. - If the property is the special value 99, the method ignores the settings in the regional and language options in Control Panel and returns the `year` parameter unchanged. + If the property is the special value 99, the method ignores the settings in the regional and language options in Control Panel and returns the `year` parameter unchanged. supports either a two-digit year or a four-digit year. Passing a two-digit year value (less than 100) causes the method to convert the value to a four-digit value according to the value representing the appropriate century. If the application supplies a four-digit year value that is within the supported calendar range to , the method returns the actual input value. If the application supplies a four-digit value that is outside the supported calendar range, or if it supplies a negative value, the method throws an exception. diff --git a/xml/System.IO.Compression/DeflateStream.xml b/xml/System.IO.Compression/DeflateStream.xml index df300e2735d..51f53f09ca4 100644 --- a/xml/System.IO.Compression/DeflateStream.xml +++ b/xml/System.IO.Compression/DeflateStream.xml @@ -520,7 +520,7 @@ The current position in the stream is updated when the asynchronous read or writ Multiple simultaneous asynchronous requests render the request completion order uncertain. -Use the property to determine whether the current object supports reading. +Use the property to determine whether the current object supports reading. If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . @@ -616,7 +616,7 @@ If a stream is writable, writing at the end of the stream expands the stream. The current position in the stream is updated when you issue the asynchronous read or write operation, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. -Use the property to determine whether the current object supports writing. +Use the property to determine whether the current object supports writing. If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . @@ -1344,7 +1344,7 @@ This method stores in the task it returns all non-usage exceptions that the meth > [!IMPORTANT] > Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. +Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. This method read a maximum of `buffer.Length` bytes from the current stream and store them in `buffer`. The current position within the Deflate stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the Deflate stream remains unchanged. This method will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the stream has not been reached. @@ -1486,7 +1486,7 @@ The following example shows how to compress and decompress bytes by using the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. If the operation is canceled before it completes, the returned task contains the value for the property. @@ -1555,7 +1555,7 @@ If the operation is canceled before it completes, the returned task contains the The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in desktop apps where a time-consuming stream operation can block the UI thread and make the app appear as if it's not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -Use the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. If the operation is canceled before it completes, the returned task contains the value for the property. @@ -1603,7 +1603,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. ]]> @@ -1745,7 +1745,7 @@ Use the property to determ property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. +Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. If the write operation is successful, the position within the Deflate stream advances by the number of bytes written. If an exception occurs, the position within the Deflate stream remains unchanged. @@ -1863,7 +1863,7 @@ The following example shows how to compress and decompress bytes by using 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. @@ -1929,7 +1929,7 @@ If the operation is canceled before it completes, the returned task contains the The `WriteAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in desktop apps where a time-consuming stream operation can block the UI thread and make the app appear as if it's not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -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. diff --git a/xml/System.IO.Compression/GZipStream.xml b/xml/System.IO.Compression/GZipStream.xml index a5736f0c8d1..c67e2aa4c2f 100644 --- a/xml/System.IO.Compression/GZipStream.xml +++ b/xml/System.IO.Compression/GZipStream.xml @@ -537,7 +537,7 @@ The current position in the stream is updated when the asynchronous read or writ Multiple simultaneous asynchronous requests render the request completion order uncertain. -Use the property to determine whether the current object supports reading. +Use the property to determine whether the current object supports reading. If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from . Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling . ]]> @@ -1357,7 +1357,7 @@ This method stores in the task it returns all non-usage exceptions that the meth > [!IMPORTANT] > Starting in .NET 6, this method might not read as many bytes as were requested. For more information, see [Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream](/dotnet/core/compatibility/core-libraries/6.0/partial-byte-reads-in-streams). -Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. +Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. This method reads a maximum of `buffer.Length` bytes from the current stream and stores them in `buffer`. The current position within the GZip stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the GZip stream remains unchanged. In the event that no data is available, this method blocks until at least one byte of data can be read. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the stream has not been reached. @@ -1505,7 +1505,7 @@ The following example shows how to compress and decompress bytes by using the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. If the operation is canceled before it completes, the returned task contains the value for the property. @@ -1574,7 +1574,7 @@ If the operation is canceled before it completes, the returned task contains the The `ReadAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in desktop apps where a time-consuming stream operation can block the UI thread and make the app appear as if it's not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -Use the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. If the operation is canceled before it completes, the returned task contains the value for the property. @@ -1624,7 +1624,7 @@ This method stores in the task it returns all non-usage exceptions that the meth ## Remarks -Use the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. ]]> @@ -1768,7 +1768,7 @@ Use the property to determine ## Remarks -Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. +Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. If the write operation is successful, the position within the GZip stream advances by the number of bytes written. If an exception occurs, the position within the GZip stream remains unchanged. @@ -1895,7 +1895,7 @@ The following example shows how to compress and decompress bytes by using 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. @@ -1963,7 +1963,7 @@ If the operation is canceled before it completes, the returned task contains the The `WriteAsync` method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in desktop apps where a time-consuming stream operation can block the UI thread and make the app appear as if it's not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -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. diff --git a/xml/System.IO.Compression/ZipArchive.xml b/xml/System.IO.Compression/ZipArchive.xml index 64de6e09a71..65b273937d5 100644 --- a/xml/System.IO.Compression/ZipArchive.xml +++ b/xml/System.IO.Compression/ZipArchive.xml @@ -503,7 +503,7 @@ If the comment byte length is larger than , it will ## Remarks The `entryName` string should reflect the relative path of the entry you want to create within the zip archive. There is no restriction on the string you provide. However, if it is not formatted as a relative path, the entry is created, but you may get an exception when you extract the contents of the zip archive. If an entry with the specified path and name already exists in the archive, a second entry is created with the same path and name. - The value of the property for the new entry is set to the current time. The entry is compressed using the default compression level of the underlying compression algorithm. If you want to specify a different compression level, use the method. + The value of the property for the new entry is set to the current time. The entry is compressed using the default compression level of the underlying compression algorithm. If you want to specify a different compression level, use the method. ## Examples The following example shows how to create an entry and write to it by using a stream. @@ -568,7 +568,7 @@ If the comment byte length is larger than , it will ## Remarks The `entryName` string should reflect the relative path of the entry you want to create within the zip archive. There is no restriction on the string you provide. However, if it is not formatted as a relative path, the entry is created, but you may get an exception when you extract the contents of the zip archive. If an entry with the specified name already exists in the archive, a second entry is created with the same name. - The value of the property for the new entry is set to the current time. Set the `compressionLevel` parameter to if you want the file to be compressed as much as possible. Set the `compressionLevel` parameter to only if you are concerned that the compression operation will not complete quickly enough for your scenario. + The value of the property for the new entry is set to the current time. Set the `compressionLevel` parameter to if you want the file to be compressed as much as possible. Set the `compressionLevel` parameter to only if you are concerned that the compression operation will not complete quickly enough for your scenario. ## Examples The following example shows how to create an entry with the optimal compression level. It also writes to the new entry by using a stream. @@ -801,7 +801,7 @@ If the comment byte length is larger than , it will property to retrieve the entire collection of entries. Use the method to retrieve a single entry by name. + Use the property to retrieve the entire collection of entries. Use the method to retrieve a single entry by name. ## Examples The following example shows how to open a zip archive and iterate through the collection of entries. @@ -918,7 +918,7 @@ If the comment byte length is larger than , it will property when you create an instance of the class. Use the or constructor to provide a value for the property. + You specify a value for the property when you create an instance of the class. Use the or constructor to provide a value for the property. ]]> diff --git a/xml/System.IO.Compression/ZipArchiveEntry.xml b/xml/System.IO.Compression/ZipArchiveEntry.xml index 0d47c774df8..121530f9b44 100644 --- a/xml/System.IO.Compression/ZipArchiveEntry.xml +++ b/xml/System.IO.Compression/ZipArchiveEntry.xml @@ -172,7 +172,7 @@ If the comment byte length is larger than , it will This property cannot be retrieved when the mode is set to , or the mode is set to and the entry has been opened. ## Examples - The following example shows how to retrieve entries in a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. + The following example shows how to retrieve entries in a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/GetEntry/program1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/GetEntry/program1.vb" id="Snippet1"::: @@ -488,7 +488,7 @@ If the comment byte length is larger than , it will This property cannot be retrieved when the mode is set to , or the mode is set to and the entry has been opened. ## Examples - The following example shows how to retrieve entries from a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. + The following example shows how to retrieve entries from a zip archive, and evaluate the properties of the entries. It uses the property to display the name of the entry, and the and properties to calculate how much the file was compressed. :::code language="csharp" source="~/snippets/csharp/System.IO.Compression/ZipArchive/GetEntry/program1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Compression/ZipArchive/GetEntry/program1.vb" id="Snippet1"::: diff --git a/xml/System.IO.Compression/ZipFileExtensions.xml b/xml/System.IO.Compression/ZipFileExtensions.xml index 7d3e9fbac6d..31e6457ad5f 100644 --- a/xml/System.IO.Compression/ZipFileExtensions.xml +++ b/xml/System.IO.Compression/ZipFileExtensions.xml @@ -125,7 +125,7 @@ property of the entry is set to the last time the file on the file system was changed. + The new entry in the archive contains the contents of the file specified by `sourceFileName`. If an entry with the specified name (`entryName`) already exists in the archive, a second entry is created with an identical name. The property of the entry is set to the last time the file on the file system was changed. When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. @@ -218,7 +218,7 @@ property of the entry is set to the last time the file on the file system was changed. + The new entry in the archive contains the contents of the file specified by `sourceFileName`. If an entry with the specified name (`entryName`) already exists in the archive, a second entry is created with an identical name. The property of the entry is set to the last time the file on the file system was changed. When `ZipArchiveMode.Update` is present, the size limit of an entry is limited to . This limit is because update mode uses a internally to allow the seeking required when updating an archive, and has a maximum equal to the size of an int. @@ -750,7 +750,7 @@ A has been compressed usi ## Remarks If the destination file already exists, this method does not overwrite it; it throws an exception. To overwrite an existing file, use the method overload instead. - The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. + The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. You cannot use this method to extract a directory; use the method instead. @@ -852,7 +852,7 @@ A has been compressed usi property. + The last write time of the file is set to the last time the entry in the zip archive was changed; this value is stored in the property. You cannot use this method to extract a directory; use the method instead. diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorage.xml b/xml/System.IO.IsolatedStorage/IsolatedStorage.xml index 8900870ef68..c75e370b10a 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorage.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorage.xml @@ -266,7 +266,7 @@ property overrides this property. + The property overrides this property. ]]> @@ -676,7 +676,7 @@ property returns the value of , which is expressed in bytes. Derived classes can express the value in other units of measure. A potential example of such an implementation is an isolated storage database. + The default implementation of the property returns the value of , which is expressed in bytes. Derived classes can express the value in other units of measure. A potential example of such an implementation is an isolated storage database. You cannot set , but the quota is configured in the security policy, and can be set. Code receives a quota of space on the basis of its evidence, so the same code can receive a different quota if it is run with different evidence (for example, the same application run locally and from a share on an intranet can receive different quotas). implements this property. @@ -732,7 +732,7 @@ property overrides this property. + The property overrides this property. ]]> @@ -988,7 +988,7 @@ property overrides this property. + The property overrides this property. ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml index fd084e36f0a..f34421fc316 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageException.xml @@ -310,7 +310,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml index cabd50981b4..c0aadf17c58 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageFile.xml @@ -593,7 +593,7 @@ The current size cannot be accurately determined for stores that are participating in a roaming user profile. Because roaming profiles are often cached on multiple client machines and later synchronized with a server, quotas cannot be enforced for such stores and the current size is not reported. - The [How to: Anticipate Out-of-Space Conditions with Isolated Storage](/dotnet/standard/io/how-to-anticipate-out-of-space-conditions-with-isolated-storage) example demonstrates the use of the property. + The [How to: Anticipate Out-of-Space Conditions with Isolated Storage](/dotnet/standard/io/how-to-anticipate-out-of-space-conditions-with-isolated-storage) example demonstrates the use of the property. ]]> @@ -2785,7 +2785,7 @@ ## Remarks The number of bytes available is constrained by the isolated storage quota set by the administrator. Quota is configured in security policy on the basis of evidence, so the same code can receive a different quota if it is run with different evidence. For example, an application that is run locally and also from a share on an intranet would likely receive different quotas. - The [How to: Anticipate Out-of-Space Conditions with Isolated Storage](/dotnet/standard/io/how-to-anticipate-out-of-space-conditions-with-isolated-storage) example demonstrates the use of the property. + The [How to: Anticipate Out-of-Space Conditions with Isolated Storage](/dotnet/standard/io/how-to-anticipate-out-of-space-conditions-with-isolated-storage) example demonstrates the use of the property. ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml index d17b05e834f..b79c5da29a9 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageFileStream.xml @@ -908,7 +908,7 @@ ## Examples - The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. + The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet11"::: @@ -1018,7 +1018,7 @@ ## Examples - The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. + The following code example demonstrates how you could use the property, as a check to see whether a stream can be read before calling the or methods. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet13"::: @@ -1589,7 +1589,7 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) ## Examples - The following code example demonstrates how you can use the property to verify that an is synchronous. For the complete context of this example, see the overview. + The following code example demonstrates how you can use the property to verify that an is synchronous. For the complete context of this example, see the overview. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet7"::: @@ -1648,7 +1648,7 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) ## Examples - The following code example demonstrates the property. + The following code example demonstrates the property. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet14"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet14"::: @@ -1762,12 +1762,12 @@ Dim source As New IsolatedStorageFileStream(UserName,FileMode.Open,isoFile) property is `true`. + Setting this property works when the property is `true`. ## Examples - The following code example uses the property to write data to a file. + The following code example uses the property to write data to a file. :::code language="csharp" source="~/snippets/csharp/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.cs" id="Snippet14"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.IsolatedStorage/IsolatedStorageFile/Close/source.vb" id="Snippet14"::: @@ -2087,7 +2087,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property is not supported and always generates an exception. + The property is not supported and always generates an exception. ]]> diff --git a/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml b/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml index 20080c0e238..34b8fe53765 100644 --- a/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml +++ b/xml/System.IO.IsolatedStorage/IsolatedStorageSecurityOptions.xml @@ -16,13 +16,13 @@ Specifies options that affect security in isolated storage. - property gets this enumeration to determine which operations can be performed in isolated storage. - - A host application can override the method to perform policy decisions based on a object, and then allow or prevent the increase in the quota size for isolated storage. - + property gets this enumeration to determine which operations can be performed in isolated storage. + + A host application can override the method to perform policy decisions based on a object, and then allow or prevent the increase in the quota size for isolated storage. + ]]> diff --git a/xml/System.IO.Log/FileRegion.xml b/xml/System.IO.Log/FileRegion.xml index 05c72df03a0..42d624f53cd 100644 --- a/xml/System.IO.Log/FileRegion.xml +++ b/xml/System.IO.Log/FileRegion.xml @@ -17,19 +17,19 @@ Represents a region of a file to be archived. This class cannot be inherited. - object contains the information necessary to generate a consistent backup of the data in a . The actual data is contained in the enumerable collection of objects returned by the property. Each instance represents a sequence of bytes in a file that must be archived. - - - -## Examples - The following example demonstrates how to archive a log store to XML using the and classes. - + object contains the information necessary to generate a consistent backup of the data in a . The actual data is contained in the enumerable collection of objects returned by the property. Each instance represents a sequence of bytes in a file that must be archived. + + + +## Examples + The following example demonstrates how to archive a log store to XML using the and classes. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/fileregion/cs/fileregion.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/fileregion/vb/fileregion.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/fileregion/vb/fileregion.vb" id="Snippet0"::: + ]]> @@ -54,19 +54,19 @@ Gets the length of the file in bytes. The length of the file in bytes. - property of the stream returned by the method. - - - -## Examples - The following example demonstrates how to archive a log store to XML using the and classes. - + property of the stream returned by the method. + + + +## Examples + The following example demonstrates how to archive a log store to XML using the and classes. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/fileregion/cs/fileregion.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/fileregion/vb/fileregion.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/fileregion/vb/fileregion.vb" id="Snippet0"::: + ]]> @@ -92,14 +92,14 @@ Returns a stream that can be used to read the data to be archived. A stream that contains the data to be archived. - and classes. - + and classes. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/fileregion/cs/fileregion.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/fileregion/vb/fileregion.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/fileregion/vb/fileregion.vb" id="Snippet0"::: + ]]> The request could not be performed because of an unexpected I/O exception. @@ -129,14 +129,14 @@ Gets the offset into the file where the data begins. The offset into the file where the data begins. - and classes. - + and classes. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/fileregion/cs/fileregion.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/fileregion/vb/fileregion.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/fileregion/vb/fileregion.vb" id="Snippet0"::: + ]]> @@ -161,14 +161,14 @@ Gets the fully qualified location of the file containing this region. The fully qualified location of the file containing this region. - and classes. - + and classes. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/fileregion/cs/fileregion.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/fileregion/vb/fileregion.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/fileregion/vb/fileregion.vb" id="Snippet0"::: + ]]> diff --git a/xml/System.IO.Log/IRecordSequence.xml b/xml/System.IO.Log/IRecordSequence.xml index 9fe7cbc7074..54611c150fc 100644 --- a/xml/System.IO.Log/IRecordSequence.xml +++ b/xml/System.IO.Log/IRecordSequence.xml @@ -45,17 +45,17 @@ The interface also exposes a few basic properties which provides information about log boundaries. -- The property contains the sequence number of the first valid record in the record sequence. +- The property contains the sequence number of the first valid record in the record sequence. -- The property contains a sequence number that is guaranteed to be larger than the sequence number of the last appended record. +- The property contains a sequence number that is guaranteed to be larger than the sequence number of the last appended record. -- The property contains the sequence number of the last written restart area. +- The property contains the sequence number of the last written restart area. -- The property contains the size of the largest record that can be appended to, or read from the sequence. +- The property contains the size of the largest record that can be appended to, or read from the sequence. -- The property contains the total size of all reservations made in this record sequence. +- The property contains the total size of all reservations made in this record sequence. -- If the property is set to `true`, and an operation fails because there is no space in the sequence, the record sequence will attempt to free space, and retry the Append operation. +- If the property is set to `true`, and an operation fails because there is no space in the sequence, the record sequence will attempt to free space, and retry the Append operation. ]]> diff --git a/xml/System.IO.Log/LogArchiveSnapshot.xml b/xml/System.IO.Log/LogArchiveSnapshot.xml index 410d63d5b2e..a7908d819ad 100644 --- a/xml/System.IO.Log/LogArchiveSnapshot.xml +++ b/xml/System.IO.Log/LogArchiveSnapshot.xml @@ -17,21 +17,21 @@ Represents a snapshot of the instance that can be used to generate an archive. - object contains the information necessary to generate a consistent backup of the data in a . The actual data is contained in the enumerable collection of objects returned by the property. Each instance represents a sequence of bytes in a file that must be archived. - - The , , and properties are for informational purposes only. They can be recorded along with the archive data to provide optional information, but are not required to restore the data. - - - -## Examples - The following example shows how to use the class to archive a to an XML document. - + object contains the information necessary to generate a consistent backup of the data in a . The actual data is contained in the enumerable collection of objects returned by the property. Each instance represents a sequence of bytes in a file that must be archived. + + The , , and properties are for informational purposes only. They can be recorded along with the archive data to provide optional information, but are not required to restore the data. + + + +## Examples + The following example shows how to use the class to archive a to an XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/logarchievesnapshot/cs/logarchievesnapshot.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/logarchievesnapshot/vb/logarchievesnapshot.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/logarchievesnapshot/vb/logarchievesnapshot.vb" id="Snippet0"::: + ]]> @@ -56,14 +56,14 @@ Gets an enumerable collection of instances containing the actual archival data. An enumerable collection of instances containing the actual archival data. - class to archive a to an XML document. - + class to archive a to an XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/logarchievesnapshot/cs/logarchievesnapshot.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/logarchievesnapshot/vb/logarchievesnapshot.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/logarchievesnapshot/vb/logarchievesnapshot.vb" id="Snippet0"::: + ]]> @@ -132,14 +132,14 @@ Gets the last sequence number of the at the time the snapshot was taken. The last sequence number of the at the time the snapshot was taken. - class to archive a to an XML document. - + class to archive a to an XML document. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/logarchievesnapshot/cs/logarchievesnapshot.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/logarchievesnapshot/vb/logarchievesnapshot.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/logarchievesnapshot/vb/logarchievesnapshot.vb" id="Snippet0"::: + ]]> diff --git a/xml/System.IO.Log/LogExtentCollection.xml b/xml/System.IO.Log/LogExtentCollection.xml index 4662555f5ac..6556ce0eb14 100644 --- a/xml/System.IO.Log/LogExtentCollection.xml +++ b/xml/System.IO.Log/LogExtentCollection.xml @@ -31,7 +31,7 @@ Although objects are represented on disk as files, they should not be moved or deleted as normal files. Rather, you should use the methods provided by this class for adding and deleting instances directly. Extents are usually removed when they no longer contain any active data. However, if the `force` parameter in the method is `true`, an exception is thrown if they cannot be removed immediately. - You cannot remove the last extent in the , which means that the property cannot be zero after an extent is added. + You cannot remove the last extent in the , which means that the property cannot be zero after an extent is added. @@ -315,7 +315,7 @@ ## Remarks A instance can be removed from the collection only if it is not part of the active region of the . If the `force` parameter is `true` and the extent cannot be removed immediately, an exception is thrown. If the `force` parameter is `false` and the extent cannot be removed immediately, the removal is deferred until it is no longer part of the active region. - You cannot remove the last extent in the , which means that the property cannot be zero once an extent has been added. + You cannot remove the last extent in the , which means that the property cannot be zero once an extent has been added. ]]> @@ -367,7 +367,7 @@ ## Remarks A instance can be removed from the collection only if it is not part of the active region of the . If the `force` parameter is `true` and the extent cannot be removed immediately, an exception is thrown. If the `force` parameter is `false` and the extent cannot be removed immediately, the removal is deferred until it is no longer part of the active region. - You cannot remove the last extent in the , which means that the property cannot be zero once an extent has been added. + You cannot remove the last extent in the , which means that the property cannot be zero once an extent has been added. ]]> diff --git a/xml/System.IO.Log/LogPolicy.xml b/xml/System.IO.Log/LogPolicy.xml index 1bcddae271e..7607cecd2c7 100644 --- a/xml/System.IO.Log/LogPolicy.xml +++ b/xml/System.IO.Log/LogPolicy.xml @@ -17,21 +17,21 @@ Represents the policy associated with a . - instance and its clients. A instance is used to examine and modify the policy associated with a specific . A policy can describe the minimum and maximum allowable log sizes, or how the instance is allowed to grow. In addition, you can also control whether a instance can be archived. - - After changing any of the properties, you should use the method to ensure that the changes are applied to the . You can call the method to discard changes or to get the most current policy. - - - -## Examples - This example shows how to use the class to set policy for a log record sequence. - + instance and its clients. A instance is used to examine and modify the policy associated with a specific . A policy can describe the minimum and maximum allowable log sizes, or how the instance is allowed to grow. In addition, you can also control whether a instance can be archived. + + After changing any of the properties, you should use the method to ensure that the changes are applied to the . You can call the method to discard changes or to get the most current policy. + + + +## Examples + This example shows how to use the class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -57,14 +57,14 @@ if the can grow its size automatically; otherwise, . - class to set policy for a log record sequence. - + class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -89,19 +89,19 @@ Gets or sets the percentage of free space the can shrink. The percentage of free space the can shrink. - is greater than the amount specified by this property, the automatically reduces its size until it reaches the size specified by the property. - - - -## Examples - This example shows how to use the class to set policy for a log record sequence. - + is greater than the amount specified by this property, the automatically reduces its size until it reaches the size specified by the property. + + + +## Examples + This example shows how to use the class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -126,25 +126,25 @@ Sets this policy as the current policy for the . - after making any changes to ensure that the changes are recorded. - - - -## Examples - This example shows how to use the class to set policy for a log record sequence. - + after making any changes to ensure that the changes are recorded. + + + +## Examples + This example shows how to use the class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> - The set of policies installed on the log is invalid. - - -or- - + The set of policies installed on the log is invalid. + + -or- + A policy of the log prevented this operation from completing. The request could not be performed because of an unexpected I/O exception. Setting this policy is not supported on the current platform. @@ -175,19 +175,19 @@ Gets or sets the rate of automatic growth of the . The rate of automatic growth of the . - becomes full, this policy value determines how much more space can be added. Space will not be added if it causes the number of extents in the to exceed . - - - -## Examples - This example shows how to use the class to set policy for a log record sequence. - + becomes full, this policy value determines how much more space can be added. Space will not be added if it causes the number of extents in the to exceed . + + + +## Examples + This example shows how to use the class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -212,14 +212,14 @@ Gets or sets the maximum number of instances the can contain. The maximum number of instances the can contain. - class to set policy for a log record sequence. - + class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -244,14 +244,14 @@ Gets or sets the minimum number of instances the can contain. An integer that specifies the minimum number of instances the can contain. Since the CLFS requires that the minimum extent count to be 2 extents, this value should be at least 2. - class to set policy for a log record sequence. - + class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -276,19 +276,19 @@ Gets or sets the prefix string for automatically created extents. The prefix string for automatically created extents. - file. - - - -## Examples - This example shows how to use the class to set policy for a log record sequence. - + file. + + + +## Examples + This example shows how to use the class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -313,14 +313,14 @@ Gets or sets the suffix number for new extents. The suffix number for new extents. - class to set policy for a log record sequence. - + class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -345,19 +345,19 @@ Gets or sets the amount of space that the event requires for advancing the base of the log. The amount of space that the event requires for advancing the base of the log. - class to set policy for a log record sequence. - + class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -382,20 +382,20 @@ Reads the current policy for the , discarding any changes that may have been made. - class to set policy for a log record sequence. - + class to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> - The set of policies installed on the log is invalid. - - -or- - + The set of policies installed on the log is invalid. + + -or- + A policy of the log prevented this operation from completing. The request could not be performed because of an unexpected I/O exception. Setting this policy is not supported on the current platform. diff --git a/xml/System.IO.Log/LogRecordSequence.xml b/xml/System.IO.Log/LogRecordSequence.xml index 402777ea580..86d065d05cb 100644 --- a/xml/System.IO.Log/LogRecordSequence.xml +++ b/xml/System.IO.Log/LogRecordSequence.xml @@ -24,19 +24,19 @@ Represents a record sequence stored in a . - class provides an implementation of the record sequence interface on top of a Common Log File System (CLFS) log. In addition to the standard record-oriented features, it provides a policy model for avoiding log-full conditions, and multiplexing of clients on the same physical file. It works with the class, which provides an interface for directly manipulating and managing a CLFS log file. The relationship between the class and the class is similar to the relationship between a disk file and a object. The disk file provides the concrete storage, and has attributes such as length and last access time; while the object provides a view on the file that can be used to read from it and write to it. Similarly, the class has attributes like a policy and a collection of disk extents; and the class provides a record-oriented mechanism for reading and writing data. - - - -## Examples - This example shows how to use the class: - + class provides an implementation of the record sequence interface on top of a Common Log File System (CLFS) log. In addition to the standard record-oriented features, it provides a policy model for avoiding log-full conditions, and multiplexing of clients on the same physical file. It works with the class, which provides an interface for directly manipulating and managing a CLFS log file. The relationship between the class and the class is similar to the relationship between a disk file and a object. The disk file provides the concrete storage, and has attributes such as length and last access time; while the object provides a view on the file that can be used to read from it and write to it. Similarly, the class has attributes like a policy and a collection of disk extents; and the class provides a record-oriented mechanism for reading and writing data. + + + +## Examples + This example shows how to use the class: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet0"::: + ]]> @@ -70,11 +70,11 @@ The that this record sequence should use. Initializes a new instance of the class with the specified log store. - @@ -103,24 +103,24 @@ One of the values that determines how to open or create the store. Initializes a new instance of the class with a specified path to the log store and the access mode. - on a new object that it opens with the specified path and mode. It is given read/write access to the store, and the store is opened sharing Read access. - + on a new object that it opens with the specified path and mode. It is given read/write access to the store, and the store is opened sharing Read access. + ]]> is . - is an empty string (""). - - -or- - - contains only white space. - - -or- - + is an empty string (""). + + -or- + + contains only white space. + + -or- + contains one or more invalid characters. contains an invalid value. @@ -157,20 +157,20 @@ The desired number of buffers. Initializes a new instance of the class with the specified log store, buffer size for each record, and buffer number. - is . - is negative or zero. - - -or- - + is negative or zero. + + -or- + is negative or zero. @@ -198,24 +198,24 @@ One of the values that determines how the file can be accessed by the . Initializes a new instance of the class with a specified path to the log store and the access and share modes. - on a new object that it opens with the specified path, mode, and access. The store is opened sharing Read access. - + on a new object that it opens with the specified path, mode, and access. The store is opened sharing Read access. + ]]> is . - is an empty string (""). - - -or- - - contains only white space. - - -or- - + is an empty string (""). + + -or- + + contains only white space. + + -or- + contains one or more invalid characters. contains an invalid value. @@ -254,32 +254,32 @@ One of the values that determines how the log store will be shared among processes. Initializes a new instance of the class with a specified path to the log store and the access mode. - on a new object that it opens with the specified path, mode, and access. The store is opened sharing the specified access. - - - -## Examples - This example shows how to use this constructor: - + on a new object that it opens with the specified path, mode, and access. The store is opened sharing the specified access. + + + +## Examples + This example shows how to use this constructor: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet1"::: + ]]> is . - is an empty string (""). - - -or- - - contains only white space. - - -or- - + is an empty string (""). + + -or- + + contains only white space. + + -or- + contains one or more invalid characters. contains an invalid value. @@ -322,24 +322,24 @@ The desired number of buffers. Initializes a new instance of the class with a specified path to the log store, file permission, access and share modes, and the buffer size and count for records. - on a new object that it opens with the specified path, mode, and access. The store is opened sharing the specified access. - + on a new object that it opens with the specified path, mode, and access. The store is opened sharing the specified access. + ]]> is . - is an empty string (""). - - -or- - - contains only white space. - - -or- - + is an empty string (""). + + -or- + + contains only white space. + + -or- + contains one or more invalid characters. contains an invalid value. @@ -384,38 +384,38 @@ A valid value that specifies the security to set on the newly created store if the store must be created. Initializes a new instance of the class. To be added. - The file specified by is not valid. - - -or- - - The specified log store file name is not valid. - - -or- - - has a value of , and cannot be used without write access. - - -or- - + The file specified by is not valid. + + -or- + + The specified log store file name is not valid. + + -or- + + has a value of , and cannot be used without write access. + + -or- + has a value of , and cannot be used without write access. One or more of the arguments are . One or more of the arguments are out of range. The file specified by cannot be found. - The request could not be performed because of an unexpected I/O exception. - - -or- - - The file specified by cannot be accessed because it is in use by another process. - - -or- - - The file specified by cannot be created because the file or directory already exists. - - -or- - - The log handle could not be bound to the thread pool. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + + The file specified by cannot be accessed because it is in use by another process. + + -or- + + The file specified by cannot be created because the file or directory already exists. + + -or- + + The log handle could not be bound to the thread pool. + + -or- + The specified log file format or version is invalid. This operation is not supported. The method was called after the sequence has been disposed of. @@ -452,51 +452,51 @@ Specifies the new base for the log. This must lie in the range between the current base sequence number and the last sequence number of the log inclusively. Moves the base sequence number of the log forward. This method cannot be inherited. - event to free up space in a record. The event indicates that the tail of the sequence (that is, the base sequence number) needs to be moved forward to free up space. Freeing space can be done by either writing restart areas using the method, or truncating the log and using the method to advance the base sequence number of a log to the one specified by the `newBaseSequenceNumber` parameter. The code sample in the Example section demonstrates the second approach. - - Note that calling this method is the same as setting a new base sequence number using the method, except that no restart record is written to the log. - - - -## Examples - This example shows how to use the method with the event to free up space in a log sequence. - -``` -recordSequence.RetryAppend = true; -recordSequence.TailPinned += new EventHandler(HandleTailPinned); - -void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) -{ - // tailPinnedEventArgs.TargetSequenceNumber is the target - // sequence number to free up space to. - // However, this sequence number is not necessarily valid. We have - // to use this sequence number as a starting point for finding a - // valid point within the log to advance toward. You need to - // identify a record with a sequence number equal to, or greater - // than TargetSequenceNumber; let's call this - // realTargetSequenceNumber. Once found, move the base - - recordSequence.AdvanceBaseSequenceNumber(realTargetSequenceNumber); - -} -``` - + event to free up space in a record. The event indicates that the tail of the sequence (that is, the base sequence number) needs to be moved forward to free up space. Freeing space can be done by either writing restart areas using the method, or truncating the log and using the method to advance the base sequence number of a log to the one specified by the `newBaseSequenceNumber` parameter. The code sample in the Example section demonstrates the second approach. + + Note that calling this method is the same as setting a new base sequence number using the method, except that no restart record is written to the log. + + + +## Examples + This example shows how to use the method with the event to free up space in a log sequence. + +``` +recordSequence.RetryAppend = true; +recordSequence.TailPinned += new EventHandler(HandleTailPinned); + +void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) +{ + // tailPinnedEventArgs.TargetSequenceNumber is the target + // sequence number to free up space to. + // However, this sequence number is not necessarily valid. We have + // to use this sequence number as a starting point for finding a + // valid point within the log to advance toward. You need to + // identify a record with a sequence number equal to, or greater + // than TargetSequenceNumber; let's call this + // realTargetSequenceNumber. Once found, move the base + + recordSequence.AdvanceBaseSequenceNumber(realTargetSequenceNumber); + +} +``` + ]]> is not valid for this sequence. - A new or existing archive tail or base of the active log is invalid. - - -or- - + A new or existing archive tail or base of the active log is invalid. + + -or- + is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The specified log does not have any extents. One or more extents must be created before a record sequence may be used. The method was called after the sequence has been disposed of. @@ -513,14 +513,14 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Writes a log record to the . - member - + member + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet5"::: + ]]> @@ -558,40 +558,40 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Writes a log record to the . This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - - - -## Examples - The following example demonstrates how to use this method to append a log record to the sequence. - + flag using the `recordAppendOptions` parameter, or call the method. + + + +## Examples + The following example demonstrates how to use this method to append a log record to the sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet13"::: + ]]> - or is not valid for this sequence. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + or is not valid for this sequence. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the arguments are . or is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The operation cannot be performed because the record sequence was opened with read-only access. The method was called after the sequence has been disposed of. @@ -633,32 +633,32 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Appends a log record to the . This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - + flag using the `recordAppendOptions` parameter, or call the method. + ]]> - or is not valid for this sequence. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + or is not valid for this sequence. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the arguments are . or is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The operation cannot be performed because the record sequence was opened with read-only access. The method was called after the sequence has been disposed of. @@ -702,34 +702,34 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Appends a log record to the , using space previously reserved in the sequence. This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - + flag using the `recordAppendOptions` parameter, or call the method. + ]]> - or is not valid for this sequence. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + or is not valid for this sequence. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the arguments are . or is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The operation cannot be performed because the record sequence was opened with read-only access. The method was called after the sequence has been disposed of. @@ -774,34 +774,34 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Appends a log record to the , using space previously reserved in the sequence. This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - + flag using the `recordAppendOptions` parameter, or call the method. + ]]> - or is not valid for this sequence. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + or is not valid for this sequence. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the arguments are . or is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The operation cannot be performed because the record sequence was opened with read-only access. The method was called after the sequence has been disposed of. @@ -834,21 +834,21 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Gets the sequence number of the first valid record in the current . The lowest sequence number that corresponds to a valid record in the . - and less than . - - The value of this property can be changed by calling the method or method. - - - -## Examples - This example shows how to use the member in a loop. - + and less than . + + The value of this property can be changed by calling the method or method. + + + +## Examples + This example shows how to use the member in a loop. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet10"::: + ]]> The property was accessed after the sequence has been disposed of. @@ -900,34 +900,34 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Begins an asynchronous append operation. This method cannot be inherited. An that represents the asynchronous append, which could still be pending. - returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - + returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + ]]> - or is not valid for this sequence. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + or is not valid for this sequence. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the arguments are . or is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The operation cannot be performed because the record sequence was opened with read-only access. The method was called after the sequence has been disposed of. @@ -973,34 +973,34 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Begins an asynchronous append operation. This method cannot be inherited. An that represents the asynchronous append, which could still be pending. - returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - + returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + ]]> - or is not valid for this sequence. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + or is not valid for this sequence. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the arguments are . or is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The operation cannot be performed because the record sequence was opened with read-only access. The method was called after the sequence has been disposed of. @@ -1048,36 +1048,36 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Begins an asynchronous append operation. This method cannot be inherited. An that represents the asynchronous append, which could still be pending. - returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - + returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. + + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + ]]> - or is not valid for this sequence. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + or is not valid for this sequence. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the arguments are . or is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The operation cannot be performed because the record sequence was opened with read-only access. The method was called after the sequence has been disposed of. @@ -1126,36 +1126,36 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Begins an asynchronous append operation. This method cannot be inherited. An that represents the asynchronous append, which could still be pending. - returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. - - Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - + returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + The appended record will consume space that has been previously reserved, using a reservation specified by the `reservations` parameter. If the append succeeds, it will consume the smallest reservation area that can hold the data, and that reservation area will be removed from the collection. + + Normally, this method completes before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + ]]> - or is not valid for this sequence. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + or is not valid for this sequence. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the arguments are . or is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The operation cannot be performed because the record sequence was opened with read-only access. The method was called after the sequence has been disposed of. @@ -1196,15 +1196,15 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Begins an asynchronous flush operation, using space previously reserved in the sequence. This method cannot be inherited. An that represents the asynchronous flush operation, which could still be pending. - returned by the current method to the method to ensure that the flush completes and resources are freed appropriately. If an error occurs during an asynchronous flush, an exception is not thrown until the method is called with the returned by this method. - - Calling this method ensures that all records that have been appended to the are durably written. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous flush request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + returned by the current method to the method to ensure that the flush completes and resources are freed appropriately. If an error occurs during an asynchronous flush, an exception is not thrown until the method is called with the returned by this method. + + Calling this method ensures that all records that have been appended to the are durably written. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous flush request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> @@ -1270,38 +1270,38 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Begins an asynchronous reserve and append operation. This method cannot be inherited. An that represents this asynchronous operation, which could still be pending. - returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. + + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> - or is not valid for this sequence. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + or is not valid for this sequence. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the arguments are . or is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The operation cannot be performed because the record sequence was opened with read-only access. The method was called after the sequence has been disposed of. @@ -1352,19 +1352,19 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Begins an asynchronous reserve and append operation. This method cannot be inherited. An that represents this asynchronous operation, which could still be pending. - returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. - - Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + returned by this method to the method to ensure that the append operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous append, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + The specified reservations are added to the provided reservation collection in an atomic operation with a record append operation. If the append fails, no space is reserved. + + Normally, this method may complete before the record has been written. To ensure that a record has been written, either specify the flag using the `recordAppendOptions` parameter, or call the method. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> One or more of the arguments is invalid. @@ -1417,45 +1417,45 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Begins an asynchronous restart area write operation, using space previously reserved in the sequence. This method cannot be inherited. An that represents the asynchronous restart area write operation, which could still be pending. - returned by this method to the method to ensure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - When the operation successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - - If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + returned by this method to the method to ensure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + When the operation successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + + If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> - is not valid for this sequence. - - -or- - - The specified log enumeration start sequence number is invalid. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + is not valid for this sequence. + + -or- + + The specified log enumeration start sequence number is invalid. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the parameters is . - A new or existing archive tail or base of the active log is invalid. - - -or- - + A new or existing archive tail or base of the active log is invalid. + + -or- + is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The method was called after the sequence has been disposed of. There is not enough memory to continue the execution of the program. @@ -1498,45 +1498,45 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Begins an asynchronous restart area write operation, using space previously reserved in the sequence. This method cannot be inherited. An that represents the asynchronous restart area write operation, which could still be pending. - returned by this method to the method to ensure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. - - Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. - - When the operation successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - - If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + returned by this method to the method to ensure that the restart area write operation has completed and resources can be freed appropriately. If an error has occurred during an asynchronous restart area write operation, an exception is not thrown until the method is called with the returned by this method. + + Data contained in the `data` parameter will be concatenated into a single byte array for appending as the record. However, no provision is made for splitting data back into array segments when the record is read. + + When the operation successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + + If a is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can hold the data, and that reservation will be removed from the collection. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> - is not valid for this sequence. - - -or- - - The specified log enumeration start sequence number is invalid. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + is not valid for this sequence. + + -or- + + The specified log enumeration start sequence number is invalid. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the parameters is . - A new or existing archive tail or base of the active log is invalid. - - -or- - + A new or existing archive tail or base of the active log is invalid. + + -or- + is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The method was called after the sequence has been disposed of. There is not enough memory to continue the execution of the program. @@ -1568,43 +1568,43 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Creates a new . This method cannot be inherited. The newly created . - class. - -``` -//Using the ReserveAndAppend Method -ReservationCollection reservations = recordSequence.CreateReservationCollection(); -long[] lengthOfUndoRecords = new long[] { 1000 }; -recordSequence.ReserveAndAppend(recordData, - userSqn, - previousSqn, - RecordSequenceAppendOptions.None, - reservations, - lengthOfUndoRecords); -recordSequence.Append(undoRecordData, // If necessary … - userSqn, - previousSqn, - RecordSequenceAppendOptions.ForceFlush, - reservations); - -// Using the Manual Approach -ReservationCollection reservations = recordSequence.CreateReservationCollection(); -reservations.Add(lengthOfUndoRecord); -try -{ - recordSequence.Append(recordData, userSqn, previousSqn, RecordAppendOptions.None); -} -catch (Exception) -{ - reservations.Remove(lengthOfUndoRecord); - throw; -} - -recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions.ForceFlush, reservations); -``` - + class. + +``` +//Using the ReserveAndAppend Method +ReservationCollection reservations = recordSequence.CreateReservationCollection(); +long[] lengthOfUndoRecords = new long[] { 1000 }; +recordSequence.ReserveAndAppend(recordData, + userSqn, + previousSqn, + RecordSequenceAppendOptions.None, + reservations, + lengthOfUndoRecords); +recordSequence.Append(undoRecordData, // If necessary … + userSqn, + previousSqn, + RecordSequenceAppendOptions.ForceFlush, + reservations); + +// Using the Manual Approach +ReservationCollection reservations = recordSequence.CreateReservationCollection(); +reservations.Add(lengthOfUndoRecord); +try +{ + recordSequence.Append(recordData, userSqn, previousSqn, RecordAppendOptions.None); +} +catch (Exception) +{ + reservations.Remove(lengthOfUndoRecord); + throw; +} + +recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions.ForceFlush, reservations); +``` + ]]> There is not enough memory to continue the execution of the program. @@ -1633,17 +1633,17 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Releases the resources used by the component. - to release resources: - + to release resources: + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet11"::: - - :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet11"::: + + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet12"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet12"::: + ]]> The method was called after the sequence has been disposed of. @@ -1677,21 +1677,21 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Ends an asynchronous append operation. This method cannot be inherited. The sequence number of the appended log record. - is called. - - This method must be called exactly once on every returned by the method. - + is called. + + This method must be called exactly once on every returned by the method. + ]]> is invalid. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. has already been called for this asynchronous operation. @@ -1729,13 +1729,13 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Ends an asynchronous flush operation. This method cannot be inherited. The sequence number of the last record written. - is called. - - This method must be called exactly once on every returned by the method. - + is called. + + This method must be called exactly once on every returned by the method. + ]]> @@ -1777,21 +1777,21 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Ends an asynchronous reserve and append operation. This method cannot be inherited. The sequence number of the appended log record. - is called. - - This method must be called exactly once on every returned by the method. - + is called. + + This method must be called exactly once on every returned by the method. + ]]> is invalid. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. has already been called for this asynchronous operation. @@ -1829,13 +1829,13 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Ends an asynchronous restart area write operation. This method cannot be inherited. The sequence number of the written log record. - is called. - - This method must be called exactly once on every returned by the method. - + is called. + + This method must be called exactly once on every returned by the method. + ]]> @@ -1883,11 +1883,11 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Ensures that all appended records have been written. This method cannot be inherited. The sequence number of the last record written. - have been durably written. - + have been durably written. + ]]> An I/O error occurred while flushing the data. @@ -1926,11 +1926,11 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Ensures that all appended records up to and including the record with the specified sequence number have been durably written. This method cannot be inherited. The sequence number of the last record written. - @@ -1969,11 +1969,11 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Gets the sequence number which is greater than the last record appended. A sequence number which is greater than the last record appended. - and less than . All other sequence numbers are invalid. - + and less than . All other sequence numbers are invalid. + ]]> The property was accessed after the sequence has been disposed of. @@ -1999,14 +1999,14 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Gets the that contains the data for this record sequence. This method cannot be inherited. The that contains the data for this record sequence. - member to add extents. - + member to add extents. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet11"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet11"::: + ]]> @@ -2065,53 +2065,53 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Returns an enumerable collection of records in the sequence. This method cannot be inherited. An enumerable collection of records in the sequence. - in a loop. - + in a loop. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mymultiplexlog.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mymultiplexlog.vb" id="Snippet10"::: + ]]> - is not valid for this sequence. - - -or- - - is invalid. - - -or- - + is not valid for this sequence. + + -or- + + is invalid. + + -or- + The specified element was not found in the collection. is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - - The request could not be performed because of an I/O device error. - - -or - - The buffer size used to write the log record is larger than the buffer size being used to read it. - - -or- - - The record sequence is corrupted. - - -or- - - The specified log file format or version is invalid. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + + The request could not be performed because of an I/O device error. + + -or + + The buffer size used to write the log record is larger than the buffer size being used to read it. + + -or- + + The record sequence is corrupted. + + -or- + + The specified log file format or version is invalid. + + -or- + The record was written with an incompatible version of the record sequence. The operation is invalid because the enumeration has not been started. A call to must be made. The method was called after the sequence has been disposed of. @@ -2143,40 +2143,40 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Returns an enumerable collection of the restart areas in the sequence. This method cannot be inherited. An enumerable collection of the restart areas in the sequence. - is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - - The request could not be performed because of an I/O device error. - - -or - - The buffer size used to write the log record is larger than the buffer size being used to read it. - - -or- - - The record sequence is corrupted. - - -or- - - The specified log file format or version is invalid. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + + The request could not be performed because of an I/O device error. + + -or + + The buffer size used to write the log record is larger than the buffer size being used to read it. + + -or- + + The record sequence is corrupted. + + -or- + + The specified log file format or version is invalid. + + -or- + The record was written with an incompatible version of the record sequence. - The operation is invalid because the enumeration has not been started. A call to must be made. - - -or - + The operation is invalid because the enumeration has not been started. A call to must be made. + + -or + The enumeration has ended. The method was called after the sequence has been disposed of. There is not enough memory to continue the execution of the program. @@ -2236,55 +2236,55 @@ recordSequence.Append(undoRecordData, userSqn, previousSqn, RecordAppendOptions. Automatically makes a single reservation and appends a record to the sequence. This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - - - -## Examples - The following example shows how to use this method to make reservations. Notice that this task can only be performed when using the CLFS-based class. - -``` -ReservationCollection reservations = recordSequence.CreateReservationCollection(); -long[] lengthOfUndoRecords = new long[] { 1000 }; -recordSequence.ReserveAndAppend(recordData, - userSqn, - previousSqn, - RecordSequenceAppendOptions.None, - reservations, - lengthOfUndoRecords); -recordSequence.Append(undoRecordData, // If necessary … - userSqn, - previousSqn, - RecordSequenceAppendOptions.ForceFlush, - reservations); -``` - + flag using the `recordAppendOptions` parameter, or call the method. + + + +## Examples + The following example shows how to use this method to make reservations. Notice that this task can only be performed when using the CLFS-based class. + +``` +ReservationCollection reservations = recordSequence.CreateReservationCollection(); +long[] lengthOfUndoRecords = new long[] { 1000 }; +recordSequence.ReserveAndAppend(recordData, + userSqn, + previousSqn, + RecordSequenceAppendOptions.None, + reservations, + lengthOfUndoRecords); +recordSequence.Append(undoRecordData, // If necessary … + userSqn, + previousSqn, + RecordSequenceAppendOptions.ForceFlush, + reservations); +``` + ]]> - or is not valid for this sequence. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + or is not valid for this sequence. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the arguments are . or is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The operation cannot be performed because the record sequence was opened with read-only access. The method was called after the sequence has been disposed of. @@ -2338,15 +2338,15 @@ recordSequence.Append(undoRecordData, // If necessary … Automatically makes a single reservation and appends a record to the sequence. This method cannot be inherited. The sequence number of the appended log record. - flag using the `recordAppendOptions` parameter, or call the method. - + flag using the `recordAppendOptions` parameter, or call the method. + ]]> One or more of the arguments is invalid. @@ -2411,13 +2411,13 @@ recordSequence.Append(undoRecordData, // If necessary … Gets the sequence number of the restart area closest to the end of the log. The sequence number of the restart area closest to the end of the log. - method, you can remove the most recently written restart area. - + method, you can remove the most recently written restart area. + ]]> The property was accessed after the sequence has been disposed of. @@ -2447,19 +2447,19 @@ recordSequence.Append(undoRecordData, // If necessary … if appends are automatically retried if the log is full; otherwise, . The default is . - call fails because there is not enough space in the sequence, the record sequence will try to free space and retry the append. - - - -## Examples - This example shows how to use the property. - + call fails because there is not enough space in the sequence, the record sequence will try to free space and retry the append. + + + +## Examples + This example shows how to use the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet3"::: + ]]> The property was accessed after the sequence has been disposed of. @@ -2485,35 +2485,35 @@ recordSequence.Append(undoRecordData, // If necessary … - The new last sequence number in the . - + The new last sequence number in the . + This should refer to a current valid record currently in the log. Sets the last record in the . - is not valid for this sequence. - A new or existing archive tail or base of the active log is invalid. - - -or- - + A new or existing archive tail or base of the active log is invalid. + + -or- + is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - - The end of the log has been reached. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + + The end of the log has been reached. + + -or- + The specified log file format or version is invalid. The method was called after the sequence has been disposed of. There is not enough memory to continue the execution of the program. @@ -2542,40 +2542,40 @@ recordSequence.Append(undoRecordData, // If necessary … Signals the need to move the tail of the sequence. - method to clear space. The code sample in the Example section demonstrates the second approach. - - You can also call the method outside of the event to free space. A restart area is similar to a checkpoint in other log processing systems. Calling this method indicates that the application considers all prior records before the restart area as fully completed, and usable for future record appends. Similar to any other records, the record written by this method requires actual free space in the log to function. - - - -## Examples - This example shows how to use the event. - -``` -recordSequence.RetryAppend = true; -recordSequence.TailPinned += new EventHandler(HandleTailPinned); - -void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) -{ - // tailPinnedEventArgs.TargetSequenceNumber is the target - // sequence number to free up space to. - // However, this sequence number is not necessarily valid. We have - // to use this sequence number as a starting point for finding a - // valid point within the log to advance toward. You need to - // identify a record with a sequence number equal to, or greater - // than TargetSequenceNumber; let's call this - // realTargetSequenceNumber. Once found, move the base - - recordSequence.AdvanceBaseSequenceNumber(realTargetSequenceNumber); - -} -``` - + method to clear space. The code sample in the Example section demonstrates the second approach. + + You can also call the method outside of the event to free space. A restart area is similar to a checkpoint in other log processing systems. Calling this method indicates that the application considers all prior records before the restart area as fully completed, and usable for future record appends. Similar to any other records, the record written by this method requires actual free space in the log to function. + + + +## Examples + This example shows how to use the event. + +``` +recordSequence.RetryAppend = true; +recordSequence.TailPinned += new EventHandler(HandleTailPinned); + +void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) +{ + // tailPinnedEventArgs.TargetSequenceNumber is the target + // sequence number to free up space to. + // However, this sequence number is not necessarily valid. We have + // to use this sequence number as a starting point for finding a + // valid point within the log to advance toward. You need to + // identify a record with a sequence number equal to, or greater + // than TargetSequenceNumber; let's call this + // realTargetSequenceNumber. Once found, move the base + + recordSequence.AdvanceBaseSequenceNumber(realTargetSequenceNumber); + +} +``` + ]]> @@ -2588,13 +2588,13 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Writes a restart area to the . - method. - + method. + ]]> @@ -2626,15 +2626,15 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Writes a restart area to the . This method cannot be inherited. The sequence number of the written restart area. - method. - - The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - + method. + + The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + ]]> One or more of the arguments is invalid. @@ -2673,15 +2673,15 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Writes a restart area to the . This method cannot be inherited. The sequence number of the written restart area. - method. - - The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - + method. + + The data in the byte array segments will be concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + ]]> One or more of the arguments is invalid. @@ -2722,19 +2722,19 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Writes a restart area to the and updates the base sequence number. This method cannot be inherited. The sequence number of the written restart area. - method. - - When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - - When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + method. + + When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + + When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> One or more of the arguments is invalid. @@ -2772,19 +2772,19 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Writes a restart area to the and updates the base sequence number. This method cannot be inherited. The sequence number of the written restart area. - method. - - When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - - When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + method. + + When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + + When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> One or more of the arguments is invalid. @@ -2824,21 +2824,21 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Writes a restart area to the using a reservation, and updates the base sequence number. This method cannot be inherited. The sequence number of the written restart area. - method. - - When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - - If a reservation is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can contain the data, and that reservation will be removed from the collection. - - When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + method. + + When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + + If a reservation is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can contain the data, and that reservation will be removed from the collection. + + When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> One or more of the arguments is invalid. @@ -2878,47 +2878,47 @@ void HandleTailPinned(object sender, TailPinnedEventArgs tailPinnedEventArgs) Writes a restart area to the using a reservation, and updates the base sequence number. This method cannot be inherited. The sequence number of the written restart area. - method. - - When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. - - If a reservation is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can contain the data, and that reservation will be removed from the collection. - - When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. - - If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. - + method. + + When a restart area is written, the data in the byte array segments are concatenated into a single byte array for appending as the record. No provision is made for splitting data back into array segments when the restart area is read. + + If a reservation is specified, the written restart area will consume space that has been previously reserved, using a reservation contained in the collection. If the method succeeds, it will consume the smallest reservation that can contain the data, and that reservation will be removed from the collection. + + When this method successfully completes, the base sequence number has been updated. All log records with sequence numbers less than the new base sequence number are inaccessible. + + If a record sequence has been disposed of, or if you pass an invalid argument, exceptions are thrown immediately within this operation. Errors that occurred during an asynchronous append request, for example, a disk failure during the I/O request, will result in exceptions being thrown when the method is called. + ]]> - is not valid for this sequence. - - -or- - - The specified log enumeration start sequence number is invalid. - - -or- - - cannot be appended because it is larger than the maximum record size. - - -or- - + is not valid for this sequence. + + -or- + + The specified log enumeration start sequence number is invalid. + + -or- + + cannot be appended because it is larger than the maximum record size. + + -or- + was not created by this record sequence. One or more of the parameters is . - A new or existing archive tail or base of the active log is invalid. - - -or- - + A new or existing archive tail or base of the active log is invalid. + + -or- + is not between the base and last sequence numbers of this sequence. - The request could not be performed because of an unexpected I/O exception. - - -or- - + The request could not be performed because of an unexpected I/O exception. + + -or- + The request could not be performed because of an I/O device error. The method was called after the sequence has been disposed of. There is not enough memory to continue the execution of the program. diff --git a/xml/System.IO.Log/LogStore.xml b/xml/System.IO.Log/LogStore.xml index 0fab8210ddf..19ba243a69d 100644 --- a/xml/System.IO.Log/LogStore.xml +++ b/xml/System.IO.Log/LogStore.xml @@ -28,9 +28,9 @@ The relationship between the class and the class is similar to the relationship between a disk file and a object. The disk file provides the actual storage and has attributes such as length and last access time, while the object provides a view on the file that can be used to read from it and write to it. Similarly, the class has attributes like a policy and a collection of disk extents, and the class provides a record-oriented mechanism for reading and writing data. - Unlike the file record sequence represented by the class, a instance stores its data in a collection of disk extents, represented by instances. The extents in a given instance are all of uniform size, and space is added to and removed from a instance in extent increments. To add and remove log extents, use the and methods of the object, which can be returned by the property. + Unlike the file record sequence represented by the class, a instance stores its data in a collection of disk extents, represented by instances. The extents in a given instance are all of uniform size, and space is added to and removed from a instance in extent increments. To add and remove log extents, use the and methods of the object, which can be returned by the property. - A instance can have policies associated with it. These are represented by instances that can be returned by the property. A policy dictates rules that the log will attempt to follow, such as maximum number of extents and minimum size, and instructions on growing or shrinking the under certain conditions. In addition, you can specify whether a instance can be archived. Policies are set per log and are volatile, which means that once every handle to the log is closed, the policy no longer exists. + A instance can have policies associated with it. These are represented by instances that can be returned by the property. A policy dictates rules that the log will attempt to follow, such as maximum number of extents and minimum size, and instructions on growing or shrinking the under certain conditions. In addition, you can specify whether a instance can be archived. Policies are set per log and are volatile, which means that once every handle to the log is closed, the policy no longer exists. diff --git a/xml/System.IO.Log/PolicyUnit.xml b/xml/System.IO.Log/PolicyUnit.xml index d018177b0c2..68461298ad6 100644 --- a/xml/System.IO.Log/PolicyUnit.xml +++ b/xml/System.IO.Log/PolicyUnit.xml @@ -17,21 +17,21 @@ Represents a size measurement in a log store policy. - structure represents a size measurement in a log store policy. The enumeration lists the units of measurement that can be represented. - - You can use the property to determine the size of the measurement. To determine the unit of measurement, use the property. You can convert other data types to a by using the and methods. - - - -## Examples - This example shows how to use the class and structure to set policy for a log record sequence. - + structure represents a size measurement in a log store policy. The enumeration lists the units of measurement that can be represented. + + You can use the property to determine the size of the measurement. To determine the unit of measurement, use the property. You can convert other data types to a by using the and methods. + + + +## Examples + This example shows how to use the class and structure to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -60,14 +60,14 @@ One of the values. Initializes a new instance of the structure with the specified value and type. - class and structure to set policy for a log record sequence. - + class and structure to set policy for a log record sequence. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/s_uelogrecordsequence/cs/mylogrecordsequence.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/s_uelogrecordsequence/vb/mylogrecordsequence.vb" id="Snippet2"::: + ]]> @@ -181,11 +181,11 @@ if both instances are equal; otherwise, . - instances for equality. For both objects to be equal, they must have the same values for both the and properties. - + instances for equality. For both objects to be equal, they must have the same values for both the and properties. + ]]> @@ -217,11 +217,11 @@ if both instances are not equal; otherwise, . - instances for inequality. For both objects to not be equal, they must have different values for the and properties. - + instances for inequality. For both objects to not be equal, they must have different values for the and properties. + ]]> diff --git a/xml/System.IO.Packaging/CertificateEmbeddingOption.xml b/xml/System.IO.Packaging/CertificateEmbeddingOption.xml index c769f848a85..aae9cfa592c 100644 --- a/xml/System.IO.Packaging/CertificateEmbeddingOption.xml +++ b/xml/System.IO.Packaging/CertificateEmbeddingOption.xml @@ -33,7 +33,7 @@ If the certificate is `NotEmbedded` in the package, an application that verifies ## Examples -The following example shows how to use `CertificateEmbeddingOption` in order to set the property. +The following example shows how to use `CertificateEmbeddingOption` in order to set the property. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/CertificateEmbeddingOption/Overview/PackageDigitalSignature.cs" id="SnippetPackageDigSigSign"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PackageDigitalSignature/visualbasic/packagedigitalsignature.vb" id="SnippetPackageDigSigSign"::: diff --git a/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml b/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml index dba25a02227..f9452aafca4 100644 --- a/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml +++ b/xml/System.IO.Packaging/EncryptedPackageEnvelope.xml @@ -869,7 +869,7 @@ for an encrypted package by use the property. + The following example shows how to obtain for an encrypted package by use the property. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: diff --git a/xml/System.IO.Packaging/PackUriHelper.xml b/xml/System.IO.Packaging/PackUriHelper.xml index 205df6c4f66..9397db074aa 100644 --- a/xml/System.IO.Packaging/PackUriHelper.xml +++ b/xml/System.IO.Packaging/PackUriHelper.xml @@ -937,7 +937,7 @@ The partUri extracted from does not conform to the v property of a relationship part must identify either the ("/") or a that is not a . + The property of a relationship part must identify either the ("/") or a that is not a . For example, if the package part "/files/document.xaml" is the source owner of the relationship part "/files/_rels/document.xaml.rels", calling with the `relationshipPartUri` parameter of "/files/_rels/document.xaml.rels" returns the of "/files/document.xaml". diff --git a/xml/System.IO.Packaging/PackWebRequest.xml b/xml/System.IO.Packaging/PackWebRequest.xml index 4fdcd2a2c74..f00b50889f5 100644 --- a/xml/System.IO.Packaging/PackWebRequest.xml +++ b/xml/System.IO.Packaging/PackWebRequest.xml @@ -24,13 +24,13 @@ Makes a request to an entire or to a in a package, identified by a pack URI. - APIs use a defined pack uri syntax to refer to parts that are contained in a package. - - For more information about the abstract class that this class derives from and the operation of requests and responses, see . - + APIs use a defined pack uri syntax to refer to parts that are contained in a package. + + For more information about the abstract class that this class derives from and the operation of requests and responses, see . + ]]> @@ -69,11 +69,11 @@ Gets or sets the . The to use with pack URI web request. - property is distinct from the of the inner returned by the method. - + property is distinct from the of the inner returned by the method. + ]]> The specified to set is not valid. @@ -106,15 +106,15 @@ Gets or sets the name of the connection group. The connection group name. - property enables the request to be associated with a connection group. A connection group is useful when application makes requests to the same server for different users. - - The property is an empty string if the request resolves from the cache. - - The property is shared with the inner (). - + property enables the request to be associated with a connection group. A connection group is useful when application makes requests to the same server for different users. + + The property is an empty string if the request resolves from the cache. + + The property is shared with the inner (). + ]]> @@ -146,15 +146,15 @@ Gets or sets the Content-length HTTP header. The content length, in bytes. - returns 0 if the request resolves from the cache. - - The property is shared with the inner (). - + returns 0 if the request resolves from the cache. + + The property is shared with the inner (). + ]]> Set is not supported, is read-only. @@ -187,15 +187,15 @@ Gets or sets the Content-type HTTP header. The contents of the header. - returns an empty string if the request resolves from the cache. - - The property is shared with the inner (). - + returns an empty string if the request resolves from the cache. + + The property is shared with the inner (). + ]]> @@ -227,13 +227,13 @@ Gets or sets the authentication credentials. The authentication credentials to use with the request. - property is shared with the inner (). - + property is shared with the inner (). + ]]> @@ -267,11 +267,11 @@ Gets the inner . A created from the inner-URI if the request resolves to a valid transport protocol such http or ftp; or a created with a null-URI if the request resolves from the cache. - is provided for advanced scenarios only and is not needed for normal operation. - + is provided for advanced scenarios only and is not needed for normal operation. + ]]> The inner URI does not resolve to a valid transport protocol such as http for ftp, nor can the request be resolved from the . @@ -305,11 +305,11 @@ Do not use- is not supported by . If is called, a is thrown. - exists to implement the contract required by the abstract base class. The pack URI protocol does not support writing. - + exists to implement the contract required by the abstract base class. The pack URI protocol does not support writing. + ]]> Occurs on any call to . The pack URI protocol does not support writing. @@ -350,13 +350,13 @@ Returns the response stream for the request. The response stream for the request. - returns value of type . The return value it is actually of type specific to the response of the pack URI protocol. - - The method should be called when the application is finished with the stream. - + returns value of type . The return value it is actually of type specific to the response of the pack URI protocol. + + The method should be called when the application is finished with the stream. + ]]> @@ -388,13 +388,13 @@ Gets or sets the collection of header name/value pairs associated with the request. A header collection object. - property is shared with the inner (). - + property is shared with the inner (). + ]]> @@ -426,13 +426,13 @@ Gets or sets the protocol method to use with the pack URI request. The protocol method name that performs this request. - property returns an empty string if the request resolves from the cache. The property is only set when request references an external Web request, such as http or ftp. - - The property is shared with the inner (). - + property returns an empty string if the request resolves from the cache. The property is only set when request references an external Web request, such as http or ftp. + + The property is shared with the inner (). + ]]> @@ -465,13 +465,13 @@ to send a WWW-authenticate HTTP header with the initial request; otherwise, . - property returns `false` for requests resolved from the cache; there is no pre-authentication scheme for the pack URI protocol. - - The property is shared with the inner (). - + property returns `false` for requests resolved from the cache; there is no pre-authentication scheme for the pack URI protocol. + + The property is shared with the inner (). + ]]> @@ -513,11 +513,11 @@ Gets or sets the network proxy for Internet access. The to use for Internet access. - property is shared with the inner (). - + property is shared with the inner (). + ]]> @@ -585,13 +585,13 @@ Gets or sets the length of time before the request times out. The number of milliseconds to wait before the request times out. - cache, returns a value of -1. - - The property is shared with the inner request (). - + cache, returns a value of -1. + + The property is shared with the inner request (). + ]]> diff --git a/xml/System.IO.Packaging/Package.xml b/xml/System.IO.Packaging/Package.xml index 6ef31d84fcf..446c2c8cb85 100644 --- a/xml/System.IO.Packaging/Package.xml +++ b/xml/System.IO.Packaging/Package.xml @@ -1003,7 +1003,7 @@ property has no default value. The file access setting is specified in the constructor call when you create a new package, or in the call when you open an existing package. + The property has no default value. The file access setting is specified in the constructor call when you create a new package, or in the call when you open an existing package. ]]> diff --git a/xml/System.IO.Packaging/PackageDigitalSignature.xml b/xml/System.IO.Packaging/PackageDigitalSignature.xml index 7e856d2871e..5232d3c3b62 100644 --- a/xml/System.IO.Packaging/PackageDigitalSignature.xml +++ b/xml/System.IO.Packaging/PackageDigitalSignature.xml @@ -78,8 +78,8 @@ | Embedding option | Location | |-|-| -||In its own certificate in the package.

The X.509 certificate can be obtained through the property.| -||Within the content of the in the package.

The X.509 certificate can be obtained through the property.| +||In its own certificate in the package.

The X.509 certificate can be obtained through the property.| +||Within the content of the in the package.

The X.509 certificate can be obtained through the property.| ||External to the package in a location known by both the application that creates the signature and the application that later uses the signature for validation.| ]]>
@@ -389,7 +389,7 @@ property specifies the format of the date. The format of the string is based on the property in effect when the signature was created. + The property specifies the format of the date. The format of the string is based on the property in effect when the signature was created. is based on the system time of the computer where the signing took place. diff --git a/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml b/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml index 771e12ac22d..b7ca59ddc77 100644 --- a/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml +++ b/xml/System.IO.Packaging/PackageDigitalSignatureManager.xml @@ -165,7 +165,7 @@ This property specifies where the signer's X.509 certificate will be stored when ## Remarks If no X.509 certificate is specified in the call, this method opens a certificate selection dialog box that prompts the user to choose a certificate to use for signing. - Set the window handle in the property before calling to make the Certificate Selection Dialog modal to the given window. + Set the window handle in the property before calling to make the Certificate Selection Dialog modal to the given window. ]]> @@ -282,9 +282,9 @@ This property specifies where the signer's X.509 certificate will be stored when ## Remarks The default hash algorithm for the standard class is (Secure Hash Algorithm version 1.0, or SHA-1). - The property gets or sets the actual hash algorithm this is used to create and verify signatures. + The property gets or sets the actual hash algorithm this is used to create and verify signatures. - The property is typically used to reset the property back to default after a temporary change. + The property is typically used to reset the property back to default after a temporary change. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. @@ -367,7 +367,7 @@ This property specifies where the signer's X.509 certificate will be stored when Unless explicitly set otherwise, this property gets the same value as . - The property is typically not changed from its default. This property must be changed only if a signature that uses a different known and accessible is encountered. When finished with the signature that uses a different hash algorithm, call to reset the property back to default. + The property is typically not changed from its default. This property must be changed only if a signature that uses a different known and accessible is encountered. When finished with the signature that uses a different hash algorithm, call to reset the property back to default. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. @@ -441,11 +441,11 @@ This property specifies where the signer's X.509 certificate will be stored when ## Remarks -The property does not perform signature validations. If signatures are present and is `true`, one or more of the signatures might not be valid. Call to confirm that the signatures are valid and have not changed. +The property does not perform signature validations. If signatures are present and is `true`, one or more of the signatures might not be valid. Call to confirm that the signatures are valid and have not changed. ## Examples -The following example shows how to use the property to determine if a package contains digital signatures. +The following example shows how to use the property to determine if a package contains digital signatures. :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/CertificateEmbeddingOption/Overview/PackageDigitalSignature.cs" id="Snippetpackagedigsigvalidate"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PackageDigitalSignature/visualbasic/packagedigitalsignature.vb" id="Snippetpackagedigsigvalidate"::: @@ -638,7 +638,7 @@ The following example shows the steps to digitally sign a list of parts within a ## Remarks -To make the certificate selection dialog modal to a particular window, set the property before calling . +To make the certificate selection dialog modal to a particular window, set the property before calling . will not prompt for certificates if there are none in the default certificate store. @@ -874,7 +874,7 @@ The following example shows how to digitally sign a list of package parts. This and other method overloads use the current dictionary that defines a `Transform` to apply based on the package part . The Microsoft Open Packaging Conventions (OPC) specification currently allows only two valid `Transform` algorithms: C14 and C14N. The W3C XML-Signature Syntax and Processing standard does not allow empty `Manifest` tags. Also the Open Packaging Conventions specification requires a -specific `Object` tag that contains both `Manifest` and `SignatureProperties` tags. Each `Manifest` tag additionally also include at least one `Reference` tag. These tags require that each signature sign at least one (non-empty parts tag) or (non-empty `relationshipSelectors`) even if the signature is needed only to sign `signatureObjects` or `objectReferences`. - This method ignores the property associated with each defined in `objectReferences`. + This method ignores the property associated with each defined in `objectReferences`. This overload provides support for generation of XML signatures that require custom `Object` tags. For any provided `Object` tag to be signed, a corresponding `Reference` tag must be provided with a uniform resource identifier (URI) that specifies the `Object` tag in local fragment syntax. For example if the `Object` tag has an ID of "myObject", the URI in the `Reference` tag would be "#myObject". For unsigned objects, no `Reference` is required. diff --git a/xml/System.IO.Packaging/PackagePart.xml b/xml/System.IO.Packaging/PackagePart.xml index f51d289caf8..de93e7ea231 100644 --- a/xml/System.IO.Packaging/PackagePart.xml +++ b/xml/System.IO.Packaging/PackagePart.xml @@ -132,7 +132,7 @@ Use this constructor when the of the part is not immediately known and will be set later when is called. - By default, the property of the part is initialized to . + By default, the property of the part is initialized to . ]]>
@@ -199,7 +199,7 @@ ## Remarks `partUri` must be valid URI formed in accordance with the [RFC 3986](https://tools.ietf.org/html/rfc3986) *Uniform Resource Identifier (URI) Generic Syntax* specification and the [Open Packaging Conventions](https://www.ecma-international.org/publications-and-standards/standards/ecma-376/) specification. - By default, the property of the part is initialized to . + By default, the property of the part is initialized to . `contentType` must be a MIME type formed in accordance with the [RFC 2616](https://www.w3.org/Protocols/rfc2616/rfc2616.html) *Hypertext Transfer Protocol - HTTP*, Section 3.7. The following table shows an example of the content MIME types used in XML Paper Specification (XPS) documents. @@ -340,7 +340,7 @@ ## Remarks is a read-only property that can be accessed only when the parent is open. - The property is automatically set by the constructor. After it is set by the constructor, the cannot be changed. + The property is automatically set by the constructor. After it is set by the constructor, the cannot be changed. ]]>
@@ -390,9 +390,9 @@ ## Remarks is a read-only property that can be accessed only when the parent is open. - The property is automatically set by the constructor. After it is set by the constructor, the cannot be changed. + The property is automatically set by the constructor. After it is set by the constructor, the cannot be changed. - The property is a MIME type formed in accordance with the [RFC 2616](https://www.w3.org/Protocols/rfc2616/rfc2616.html) *Hypertext Transfer Protocol - HTTP*, Section 3.7. The following table shows an example of the content MIME types used in XML Paper Specification (XPS) documents. + The property is a MIME type formed in accordance with the [RFC 2616](https://www.w3.org/Protocols/rfc2616/rfc2616.html) *Hypertext Transfer Protocol - HTTP*, Section 3.7. The following table shows an example of the content MIME types used in XML Paper Specification (XPS) documents. |Description|Content Type| |-----------------|------------------| @@ -780,7 +780,7 @@ A part-level relationship defines an association between this part and a target ## Remarks is a virtual method of the abstract base class. Implement this method only in derived types where the value for the content type cannot be provided at the time of construction, or if calculating the content type value is a nontrivial or costly operation. The return value must be a valid MIME content type. - Derived classes can call to initialize the property of the derived class to a default value. After the property has been set it cannot be changed. + Derived classes can call to initialize the property of the derived class to a default value. After the property has been set it cannot be changed. ]]>
@@ -1269,7 +1269,7 @@ A part-level relationship defines an association between this part and a target ## Remarks is a read-only property that can be accessed only when the parent is open. - The property is automatically set by the constructor. After it is set by the constructor, the parent for the part cannot be changed. + The property is automatically set by the constructor. After it is set by the constructor, the parent for the part cannot be changed. ]]>
@@ -1380,7 +1380,7 @@ A part-level relationship defines an association between this part and a target ## Remarks is a read-only property that can be accessed only when the parent is open. - The property is automatically set by the constructor. After it is set by the constructor, the of the part cannot be changed. + The property is automatically set by the constructor. After it is set by the constructor, the of the part cannot be changed. ]]>
diff --git a/xml/System.IO.Packaging/PackageProperties.xml b/xml/System.IO.Packaging/PackageProperties.xml index 6bffb213d88..9b661ca87dd 100644 --- a/xml/System.IO.Packaging/PackageProperties.xml +++ b/xml/System.IO.Packaging/PackageProperties.xml @@ -218,7 +218,7 @@ ## Remarks Example values include "Whitepaper", "Security Bulletin", and "Exam". - This property is distinct from Multipurpose Internet Mail Extensions (MIME) content types as defined in RFC 2616. + This property is distinct from Multipurpose Internet Mail Extensions (MIME) content types as defined in RFC 2616. ]]>
@@ -526,7 +526,7 @@ property typically contains a list of terms that are not available elsewhere in . + The property typically contains a list of terms that are not available elsewhere in . ]]> @@ -715,9 +715,9 @@ property indicates the number of changed saves or revisions. + The property indicates the number of changed saves or revisions. - The application is responsible for updating the property value after each revision. + The application is responsible for updating the property value after each revision. ]]> diff --git a/xml/System.IO.Packaging/PackageRelationship.xml b/xml/System.IO.Packaging/PackageRelationship.xml index f4b9c8a0fb2..d9297980e00 100644 --- a/xml/System.IO.Packaging/PackageRelationship.xml +++ b/xml/System.IO.Packaging/PackageRelationship.xml @@ -61,7 +61,7 @@ |.|Creates a "package-level" relationship-from a package to a specified part or external resource.| |.|Creates a "part-level" relationship-from one part to another part or external resource.| - The source package or part is identified by the property of the relationship. The target part or external resource is identified by the property of the relationship. + The source package or part is identified by the property of the relationship. The target part or external resource is identified by the property of the relationship. Creating or deleting a relationship does not affect the source or target objects in any way. @@ -117,11 +117,11 @@ property string is unique for all relationships owned by the package or part. + The property string is unique for all relationships owned by the package or part. The is specified in the call to the **Package**. or **PackagePart**. method that created the relationship. After the relationship is created, the cannot be changed. - The property string is a valid XML identifier. The type is xsd:ID and must follow the naming conventions prescribed in the *XML Schema Part 2: Datatypes* specification (see [https://www.w3.org/TR/xmlschema-2/#ID](https://www.w3.org/TR/xmlschema-2/#ID)). + The property string is a valid XML identifier. The type is xsd:ID and must follow the naming conventions prescribed in the *XML Schema Part 2: Datatypes* specification (see [https://www.w3.org/TR/xmlschema-2/#ID](https://www.w3.org/TR/xmlschema-2/#ID)). ]]> diff --git a/xml/System.IO.Packaging/PackageRelationshipSelector.xml b/xml/System.IO.Packaging/PackageRelationshipSelector.xml index 68261f190ef..af2456b6964 100644 --- a/xml/System.IO.Packaging/PackageRelationshipSelector.xml +++ b/xml/System.IO.Packaging/PackageRelationshipSelector.xml @@ -54,7 +54,7 @@ ## Remarks is used by the method of the class to specify a list of parts to be signed. - is used by the property of the class to obtain a list of parts that have been signed with the given digital signature. + is used by the property of the class to obtain a list of parts that have been signed with the given digital signature. ]]>
diff --git a/xml/System.IO.Packaging/RightsManagementInformation.xml b/xml/System.IO.Packaging/RightsManagementInformation.xml index ea167a7b323..fe143a7c163 100644 --- a/xml/System.IO.Packaging/RightsManagementInformation.xml +++ b/xml/System.IO.Packaging/RightsManagementInformation.xml @@ -24,24 +24,24 @@ Represents Digital Rights Management (DRM) information that is stored in an . - provides access to the and data stored in a rights managed protected . - - - -## Examples - The following example shows how to initialize a object for encryption. - + provides access to the and data stored in a rights managed protected . + + + +## Examples + The following example shows how to initialize a object for encryption. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - - The following example shows how to initialize a object for decryption. - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + + The following example shows how to initialize a object for decryption. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewopenpkg"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewopenpkg"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewopenpkg"::: + ]]> @@ -74,19 +74,19 @@ Gets or sets the for accessing the package's encrypted rights management data stream. The for accessing the rights management information. - property. - + property. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewbind"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewbind"::: - - The following example shows how to access the property. - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewbind"::: + + The following example shows how to access the property. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewdecrypt"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewdecrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewdecrypt"::: + ]]> @@ -154,11 +154,11 @@ Returns a dictionary collection of user and key/value pairs from the encrypted rights management data stream. A collection of user and key/value pairs that are contained in the rights managed protected package. - only returns those use licenses that are currently embedded in the package. It does not include any other use licenses that the application might have acquired separately from a rights management server but that are not yet embedded in the package. - + only returns those use licenses that are currently embedded in the package. It does not include any other use licenses that the application might have acquired separately from a rights management server but that are not yet embedded in the package. + ]]> @@ -193,14 +193,14 @@ Returns the embedded from the encrypted rights management data stream. The embedded ; or , if the package does not contain a . - method. - + method. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewopenpkg"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewopenpkg"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewopenpkg"::: + ]]> The rights management information in this package cannot be read by the current version of this class. @@ -239,14 +239,14 @@ Returns a specified user's embedded from the encrypted rights management data stream. The for the specified user; or , if the package does not contain a that matches the given . - method. - + method. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewopenpkg"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewopenpkg"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewopenpkg"::: + ]]> The parameter is . @@ -287,11 +287,11 @@ The publish license to store and embed in the package. Saves a given to the encrypted rights management data stream. - can contain only one . Each call to will overwrite any prior contained in the . - + can contain only one . Each call to will overwrite any prior contained in the . + ]]> The parameter is . @@ -332,21 +332,21 @@ The use license to store and embed in the package. Saves a given for a specified user to the encrypted rights management data stream. - for the specified user has been saved, it can be retrieved through the method and from the collection returned by . - - A can store the rights information for multiple content users. Each ContentUser can have at most one . If is called to store a new for a that already has a , the previous license will be overwritten with the new license. - - - -## Examples - The following example shows how to use of the method. - + for the specified user has been saved, it can be retrieved through the method and from the collection returned by . + + A can store the rights information for multiple content users. Each ContentUser can have at most one . If is called to store a new for a that already has a , the previous license will be overwritten with the new license. + + + +## Examples + The following example shows how to use of the method. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> Either the or parameter is . diff --git a/xml/System.IO.Packaging/StreamInfo.xml b/xml/System.IO.Packaging/StreamInfo.xml index db8b95e8242..e90c64cd6ee 100644 --- a/xml/System.IO.Packaging/StreamInfo.xml +++ b/xml/System.IO.Packaging/StreamInfo.xml @@ -58,11 +58,11 @@ Gets the setting for the stream. The compression option setting for the package stream. - has been called on the stream, the property returns CompressionOption.. - + has been called on the stream, the property returns CompressionOption.. + ]]> @@ -96,11 +96,11 @@ Gets the setting for the stream. The encryption option setting for the package stream. - has been called on the stream, the property returns EncryptionOption.. - + has been called on the stream, the property returns EncryptionOption.. + ]]> @@ -145,11 +145,11 @@ Returns a stream opened in a default and . The I/O stream opened in a default root and . - method (without parameters), opens the stream in file mode with the default storage root . - + method (without parameters), opens the stream in file mode with the default storage root . + ]]> @@ -186,11 +186,11 @@ Returns an I/O stream opened in a specified . The stream opened in the specified file . - method opens the stream with the default storage root . - + method opens the stream with the default storage root . + ]]> @@ -259,11 +259,11 @@ Gets the name of the stream. The name of this stream. - has been called on the stream, the property returns an empty string. - + has been called on the stream, the property returns an empty string. + ]]> diff --git a/xml/System.IO.Pipes/AnonymousPipeServerStream.xml b/xml/System.IO.Pipes/AnonymousPipeServerStream.xml index dc060e57345..5790376bf0a 100644 --- a/xml/System.IO.Pipes/AnonymousPipeServerStream.xml +++ b/xml/System.IO.Pipes/AnonymousPipeServerStream.xml @@ -884,7 +884,7 @@ Anonymous pipes do not support the read mode. ## Examples - The following example demonstrates a way to send a string from a parent process to a child process by using anonymous pipes. In this example, an object is created in a parent process and the property is displayed to the console. + The following example demonstrates a way to send a string from a parent process to a child process by using anonymous pipes. In this example, an object is created in a parent process and the property is displayed to the console. :::code language="csharp" source="~/snippets/csharp/System.IO.Pipes/AnonymousPipeServerStream/Overview/Program.cs"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Pipes/AnonymousPipeServerStream/Overview/program.vb"::: diff --git a/xml/System.IO.Pipes/PipeSecurity.xml b/xml/System.IO.Pipes/PipeSecurity.xml index 04332c26df3..65014e1253b 100644 --- a/xml/System.IO.Pipes/PipeSecurity.xml +++ b/xml/System.IO.Pipes/PipeSecurity.xml @@ -37,19 +37,19 @@ Represents the access control and audit security for a pipe. - class specifies the access rights for a pipe and how access attempts are audited. This class represents access and audit rights as a set of rules. Each access rule is represented by a object, while each audit rule is represented by a object. - - The class is an abstraction of the underlying Microsoft Windows file security system. In this system, each pipe has a discretionary access control list (DACL), which controls access to the pipe, and a system access control list (SACL), which specifies the access control attempts that are audited. The and classes are abstractions of the access control entries (ACEs) that comprise DACLs and SACLs. - - The class hides many of the details of DACLs and SACLs; you do not have to worry about ACE ordering or null DACLS. - - Use the class to retrieve, add, or change the access rules that represent the DACL and SACL of a pipe. - - To persist new or changed access or audit rules to a pipe, use the method. To retrieve access or audit rules from an existing file, use the method. - + class specifies the access rights for a pipe and how access attempts are audited. This class represents access and audit rights as a set of rules. Each access rule is represented by a object, while each audit rule is represented by a object. + + The class is an abstraction of the underlying Microsoft Windows file security system. In this system, each pipe has a discretionary access control list (DACL), which controls access to the pipe, and a system access control list (SACL), which specifies the access control attempts that are audited. The and classes are abstractions of the access control entries (ACEs) that comprise DACLs and SACLs. + + The class hides many of the details of DACLs and SACLs; you do not have to worry about ACE ordering or null DACLS. + + Use the class to retrieve, add, or change the access rules that represent the DACL and SACL of a pipe. + + To persist new or changed access or audit rules to a pipe, use the method. To retrieve access or audit rules from an existing file, use the method. + ]]> @@ -83,15 +83,15 @@ Initializes a new instance of the class. - object that is not based on an existing pipe. You can then populate the object with access control information and apply it to a pipe. - - You can add access or audit rules to the object using the method. You can remove access or audit rules using the method. - - To persist new or changed access or audit rules to a pipe, use the method. To retrieve access or audit rules from an existing file, use the method. - + object that is not based on an existing pipe. You can then populate the object with access control information and apply it to a pipe. + + You can add access or audit rules to the object using the method. You can remove access or audit rules using the method. + + To persist new or changed access or audit rules to a pipe, use the method. To retrieve access or audit rules from an existing file, use the method. + ]]> @@ -129,11 +129,11 @@ Gets the of the securable object that is associated with the current object. The type of the securable object that is associated with the current object. - class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. - + class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. + ]]> @@ -186,20 +186,20 @@ Initializes a new instance of the class with the specified values. The object that this method creates. - class. - + class. + ]]> , , , or specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type nor of a type, such as , that can be converted to type . @@ -238,11 +238,11 @@ Gets the of the object that is associated with the access rules of the current object. The type of the object that is associated with the access rules of the current object. - class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. - + class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. + ]]> @@ -283,11 +283,11 @@ The access rule to add. Adds an access rule to the Discretionary Access Control List (DACL) that is associated with the current object. - method adds a new rule to the list of rules that a object contains. If an access control list (ACL) already exists for the specified rule, the method will still add the rule, with one exception: a object that is created using the value supersedes an object that is created using the value. - + method adds a new rule to the list of rules that a object contains. If an access control list (ACL) already exists for the specified rule, the method will still add the rule, with one exception: a object that is created using the value supersedes an object that is created using the value. + ]]> The parameter is . @@ -329,13 +329,13 @@ The audit rule to add. Adds an audit rule to the System Access Control List (SACL) that is associated with the current object. - method adds a new audit rule to the list of rules that a object contains. - - If an audit rule already exists for the specified rule, the method will still add the rule. - + method adds a new audit rule to the list of rules that a object contains. + + If an audit rule already exists for the specified rule, the method will still add the rule. + ]]> The parameter is . @@ -389,18 +389,18 @@ Initializes a new instance of the class with the specified values. The object that this method creates. - class. - + class. + ]]> The , , , or properties specify an invalid value. - The property is . - - -or- - + The property is . + + -or- + The property is zero. The property is neither of type nor of a type, such as , that can be converted to type . @@ -438,11 +438,11 @@ Gets the object associated with the audit rules of the current object. The type of the object that is associated with the audit rules of the current object. - class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. - + class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. + ]]> @@ -582,11 +582,11 @@ if the operation is successful; otherwise, . - method removes either all matching access rules or all matching access rules from the current object. For example, you can use this method to remove all access rules for a user by passing a object created using the value, the value, and a user account. The method removes any deny rules that specify the value or the value. - + method removes either all matching access rules or all matching access rules from the current object. For example, you can use this method to remove all access rules for a user by passing a object created using the value, the value, and a user account. The method removes any deny rules that specify the value or the value. + ]]> The parameter is . @@ -628,11 +628,11 @@ The access rule to remove. Removes the specified access rule from the Discretionary Access Control List (DACL) that is associated with the current object. - method removes either all matching access rules or all matching access rules from the current object. For example, you can use this method to remove all access rules for a user by passing a object created using the value, the value, and a user account. The method removes any deny rules that specify the value or the value. - + method removes either all matching access rules or all matching access rules from the current object. For example, you can use this method to remove all access rules for a user by passing a object created using the value, the value, and a user account. The method removes any deny rules that specify the value or the value. + ]]> The parameter is . @@ -676,11 +676,11 @@ if the audit rule was removed; otherwise, . - method removes either all matching audit rules or all matching audit rules from the current object. For example, you can use this method to remove all audit rules for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes any deny rules that specify the value or the value. - + method removes either all matching audit rules or all matching audit rules from the current object. For example, you can use this method to remove all audit rules for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes any deny rules that specify the value or the value. + ]]> The parameter is . @@ -722,11 +722,11 @@ The audit rule to remove. Removes all audit rules that have the same security identifier as the specified audit rule from the System Access Control List (SACL) that is associated with the current object. - method removes all audit rules for the specified user. It ignores all values in the object except the user account. - + method removes all audit rules for the specified user. It ignores all values in the object except the user account. + ]]> The parameter is . @@ -768,11 +768,11 @@ The audit rule to remove. Removes the specified audit rule from the System Access Control List (SACL) that is associated with the current object. - method removes the specified matching audit rule or the specified matching audit rule from the current object. For example, you can use this method to remove a specified audit rule for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes only a deny rule that specifies the value. It does not remove any deny rules that specify the value. - + method removes the specified matching audit rule or the specified matching audit rule from the current object. For example, you can use this method to remove a specified audit rule for a user by passing a object created using the value, the value, and a user account. When you do this, the method removes only a deny rule that specifies the value. It does not remove any deny rules that specify the value. + ]]> The parameter is . @@ -814,11 +814,11 @@ The access rule to add. Removes all access rules in the Discretionary Access Control List (DACL) that is associated with the current object and then adds the specified access rule. - method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will also be overwritten. - + method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will also be overwritten. + ]]> The parameter is . @@ -860,11 +860,11 @@ The rule to set. Sets an access rule in the Discretionary Access Control List (DACL) that is associated with the current object. - method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will not be overwritten. - + method adds the specified access control list (ACL) rule or overwrites any identical ACL rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical ACL rule that specifies the value, the identical rule will be overwritten. If the method finds an identical ACL rule that specifies the value, the identical rule will not be overwritten. + ]]> The parameter is . @@ -906,11 +906,11 @@ The rule to set. Sets an audit rule in the System Access Control List (SACL) that is associated with the current object. - method adds the specified audit rule or overwrites any identical audit rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical audit rule that specifies the value, the identical rule will be overwritten. If the method finds an identical audit rule that specifies the value, the identical rule will not be overwritten. - + method adds the specified audit rule or overwrites any identical audit rules that match the value of the `rule` parameter. For example, if the `rule` parameter specifies a value and the method finds an identical audit rule that specifies the value, the identical rule will be overwritten. If the method finds an identical audit rule that specifies the value, the identical rule will not be overwritten. + ]]> The parameter is . diff --git a/xml/System.IO.Pipes/PipeStream.xml b/xml/System.IO.Pipes/PipeStream.xml index 4bee2665e7f..9a1f1cd5212 100644 --- a/xml/System.IO.Pipes/PipeStream.xml +++ b/xml/System.IO.Pipes/PipeStream.xml @@ -264,7 +264,7 @@ ## Remarks Pass the returned object to the method to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . - Use the property to determine whether the current object supports read operations. + Use the property to determine whether the current object supports read operations. If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous read request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. @@ -363,7 +363,7 @@ ## Remarks must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . - Use the property to determine whether the current object supports write operations. + Use the property to determine whether the current object supports write operations. If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous write request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. @@ -812,7 +812,7 @@ When the disposing parameter is `true`, this method releases all resources held Pass the returned object to the method to determine how many bytes were read and to release operating system resources used for reading. must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . - Use the property to determine whether the current object supports read operations. + Use the property to determine whether the current object supports read operations. If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous read request occur on the thread pool thread that is performing the request. The exceptions are raised when the code calls the method. @@ -878,7 +878,7 @@ When the disposing parameter is `true`, this method releases all resources held ## Remarks must be called once for every call to . This can be done either in the same code that called or in a callback that is passed to . - Use the property to determine whether the current object supports write operations. + Use the property to determine whether the current object supports write operations. If the pipe is closed or an invalid argument is passed to , the appropriate exceptions are raised immediately. Errors that occur during an asynchronous write request occur on the thread pool thread that is performing the request. The exceptions are raised when the code the calls method. @@ -1146,7 +1146,7 @@ When the disposing parameter is `true`, this method releases all resources held property to `true`. + If the pipe is in a connected state, this method also sets the property to `true`. ]]> @@ -1203,7 +1203,7 @@ When the disposing parameter is `true`, this method releases all resources held property correctly. + This property enables your code to use the property correctly. ]]> @@ -1253,7 +1253,7 @@ When the disposing parameter is `true`, this method releases all resources held property returns `true` only if the object is connected. If this property returns `false`, the pipe may be waiting to connect, or may be disconnected, closed, or broken. + The property returns `true` only if the object is connected. If this property returns `false`, the pipe may be waiting to connect, or may be disconnected, closed, or broken. ]]> @@ -1364,7 +1364,7 @@ When the disposing parameter is `true`, this method releases all resources held property was set to by the most recent call to or . + This property is relevant if the pipe's property was set to by the most recent call to or . ]]> @@ -1423,7 +1423,7 @@ When the disposing parameter is `true`, this method releases all resources held class does not support the property. + The class does not support the property. ]]> @@ -1531,7 +1531,7 @@ When the disposing parameter is `true`, this method releases all resources held class does not support the property. + The class does not support the property. ]]> @@ -1577,7 +1577,7 @@ When the disposing parameter is `true`, this method releases all resources held ## Remarks -Use the property to determine whether the current object supports read operations. +Use the property to determine whether the current object supports read operations. Use the method to read asynchronously from the current stream. @@ -1666,7 +1666,7 @@ The pipe handle has not been set. (Did your property to determine whether the current object supports read operations. + Use the property to determine whether the current object supports read operations. Calling the method blocks until `count` bytes are read or the end of the stream is reached. For asynchronous read operations, see and . @@ -1738,7 +1738,7 @@ The pipe handle has not been set. (Did your method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in applications where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -Use the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. -If the operation is canceled before it completes, the returned task contains the value for the property. +If the operation is canceled before it completes, the returned task contains the value for 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 . @@ -1881,7 +1881,7 @@ The pipe handle has not been set. (Did your property to determine whether the current object supports read operations. + Use the property to determine whether the current object supports read operations. ]]>
@@ -2329,7 +2329,7 @@ The pipe handle has not been set. (Did your property to determine whether the current object supports write operations. + Use the property to determine whether the current object supports write operations. For asynchronous write operations, see and . @@ -2469,9 +2469,9 @@ The pipe handle has not been set. (Did your method enables you to perform resource-intensive I/O operations without blocking the main thread. This performance consideration is particularly important in applications where a time-consuming stream operation can block the UI thread and make your app appear as if it is not working. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -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 operation is canceled before it completes, the returned task contains the value for 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 . @@ -2626,7 +2626,7 @@ The pipe handle has not been set. (Did your property to determine whether the current object supports write operations. + Use the property to determine whether the current object supports write operations. ]]>
diff --git a/xml/System.IO.Ports/Handshake.xml b/xml/System.IO.Ports/Handshake.xml index 64fdeb6b281..6c464d3866f 100644 --- a/xml/System.IO.Ports/Handshake.xml +++ b/xml/System.IO.Ports/Handshake.xml @@ -34,13 +34,13 @@ property. + This enumeration is used with the property. ## Examples The following code example displays the possible values of the enumeration to the console, then prompts the user to choose one. This code example is part of a larger code example provided for the class. - + :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet05"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Ports/Handshake/Overview/SerialPort.vb" id="Snippet05"::: diff --git a/xml/System.IO.Ports/Parity.xml b/xml/System.IO.Ports/Parity.xml index eba200ebc40..7c0adaa7e0d 100644 --- a/xml/System.IO.Ports/Parity.xml +++ b/xml/System.IO.Ports/Parity.xml @@ -34,7 +34,7 @@ property for a serial port connection. + Use this enumeration when setting the property for a serial port connection. Parity is an error-checking procedure in which the number of 1s must always be the same - either even or odd - for each group of bits that is transmitted without error. In modem-to-modem communications, parity is often one of the parameters that must be agreed upon by sending parties and receiving parties before transmission can take place. @@ -42,7 +42,7 @@ ## Examples The following code example displays the possible values of the enumeration to the console, then prompts the user to choose one. This code example is part of a larger code example provided for the class. - + :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/SerialPort.cs" id="Snippet03"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Ports/Handshake/Overview/SerialPort.vb" id="Snippet03"::: diff --git a/xml/System.IO.Ports/SerialData.xml b/xml/System.IO.Ports/SerialData.xml index 827395a8bb7..81f131cbf2c 100644 --- a/xml/System.IO.Ports/SerialData.xml +++ b/xml/System.IO.Ports/SerialData.xml @@ -31,11 +31,11 @@ Specifies the type of character that was received on the serial port of the object. - event. You examine the type of character that was received by retrieving the value of the property. The property contains one of the values from the `SerialData` enumeration. - + event. You examine the type of character that was received by retrieving the value of the property. The property contains one of the values from the `SerialData` enumeration. + ]]> diff --git a/xml/System.IO.Ports/SerialError.xml b/xml/System.IO.Ports/SerialError.xml index 8970456186f..0eeccf494b9 100644 --- a/xml/System.IO.Ports/SerialError.xml +++ b/xml/System.IO.Ports/SerialError.xml @@ -31,11 +31,11 @@ Specifies errors that occur on the object. - event to detect and respond to errors when communicating data through a . You examine the type of error by retrieving the property. The property contains one of the values from the `SerialError` enumeration. - + event to detect and respond to errors when communicating data through a . You examine the type of error by retrieving the property. The property contains one of the values from the `SerialError` enumeration. + ]]> diff --git a/xml/System.IO.Ports/SerialPort.xml b/xml/System.IO.Ports/SerialPort.xml index c3976401338..3139a1e1c18 100644 --- a/xml/System.IO.Ports/SerialPort.xml +++ b/xml/System.IO.Ports/SerialPort.xml @@ -41,7 +41,7 @@ object, accessible through the property, and passed to classes that wrap or use streams. + Use this class to control a serial port file resource. This class provides synchronous and event-driven I/O, access to pin and break states, and access to serial driver properties. Additionally, the functionality of this class can be wrapped in an internal object, accessible through the property, and passed to classes that wrap or use streams. The class supports the following encodings: , , , , and any encoding defined in mscorlib.dll where the code page is less than 50000 or the code page is 54936. You can use alternate encodings, but you must use the or method and perform the encoding yourself. @@ -93,7 +93,7 @@ property defaults to 8, the property defaults to the `None` enumeration value, the property defaults to 1, and a default port name of COM1. + This constructor uses default property values when none are specified. For example, the property defaults to 8, the property defaults to the `None` enumeration value, the property defaults to 1, and a default port name of COM1. @@ -134,7 +134,7 @@ property defaults to 8, the property defaults to the `None` enumeration value, the property defaults to 1, and a default port name of COM1. + This constructor uses default property values when none are specified. For example, the property defaults to 8, the property defaults to the `None` enumeration value, the property defaults to 1, and a default port name of COM1. ]]> @@ -394,7 +394,7 @@ ## Remarks Use this property for explicit asynchronous I/O operations or to pass the object to a wrapper class such as . - Any open serial port's property returns an object that derives from the abstract class, and implements read and write methods using the prototypes inherited from the class: , , , , , and . These methods can be useful when passing a wrapped serial resource to a wrapper class. + Any open serial port's property returns an object that derives from the abstract class, and implements read and write methods using the prototypes inherited from the class: , , , , , and . These methods can be useful when passing a wrapped serial resource to a wrapper class. Due to the inaccessibility of the wrapped file handle, the and properties are not supported, and the and methods are not supported. @@ -458,7 +458,7 @@ ## Examples - The following example shows how to set the property to `9600`. + The following example shows how to set the property to `9600`. :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/datareceived.cs" id="Snippet20"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Ports/Handshake/Overview/datareceived.vb" id="Snippet20"::: @@ -567,7 +567,7 @@ ## Remarks The receive buffer includes the serial driver's receive buffer as well as internal buffering in the object itself. - Because the property represents both the buffer and the Windows-created buffer, it can return a greater value than the property, which represents only the Windows-created buffer. + Because the property represents both the buffer and the Windows-created buffer, it can return a greater value than the property, which represents only the Windows-created buffer. ]]> @@ -867,11 +867,11 @@ ## Remarks Data events can be caused by any of the items in the enumeration. Because the operating system determines whether to raise this event or not, not all parity errors may be reported. - The event is also raised if an Eof character is received, regardless of the number of bytes in the internal input buffer and the value of the property. + The event is also raised if an Eof character is received, regardless of the number of bytes in the internal input buffer and the value of the property. , , and events may be called out of order, and there may be a slight delay between when the underlying stream reports the error and when the event handler is executed. Only one event handler can execute at a time. - The event is not guaranteed to be raised for every byte received. Use the property to determine how much data is left to be read in the buffer. + The event is not guaranteed to be raised for every byte received. Use the property to determine how much data is left to be read in the buffer. The event is raised on a secondary thread when data is received from the object. Because this event is raised on a secondary thread, and not the main thread, attempting to modify some elements in the main thread, such as UI elements, could raise a threading exception. If it is necessary to modify elements in the main or , post change requests back using , which will do the work on the proper thread. @@ -1060,7 +1060,7 @@ 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. - This method flushes and closes the stream object in the property. + This method flushes and closes the stream object in the property. ]]> @@ -1367,7 +1367,7 @@ ## Remarks When handshaking is used, the device connected to the object is instructed to stop sending data when there is at least (-1024) bytes in the buffer. The device is instructed to start sending data again when there are 1024 or fewer bytes in the buffer. If the device is sending data in blocks that are larger than 1024 bytes, this may cause the buffer to overflow. - If the property is set to and is set to `false`, the XOff character will not be sent. If is then set to `true`, more data must be sent before the XOff character will be sent. + If the property is set to and is set to `false`, the XOff character will not be sent. If is then set to `true`, more data must be sent before the XOff character will be sent. @@ -1454,7 +1454,7 @@ property tracks whether the port is open for use by the caller, not whether the port is open by any application on the machine. + The property tracks whether the port is open for use by the caller, not whether the port is open by any application on the machine. ]]> @@ -1859,7 +1859,7 @@ ## Remarks If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. - Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. + Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. The method does not block other operations when the number of bytes read equals `count` but there are still unread bytes available on the serial port. @@ -1912,7 +1912,7 @@ If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. - Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many characters are available to read. The property can indicate that there are characters to read, but these characters might not be accessible to the stream contained in the property because they have been buffered to the class. + Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many characters are available to read. The property can indicate that there are characters to read, but these characters might not be accessible to the stream contained in the property because they have been buffered to the class. The method does not block other operations when the number of bytes read equals `count` but there are still unread bytes available on the serial port. @@ -1975,9 +1975,9 @@ property ignores any value smaller than 4096. + The property ignores any value smaller than 4096. - Because the property represents only the Windows-created buffer, it can return a smaller value than the property, which represents both the buffer and the Windows-created buffer. + Because the property represents only the Windows-created buffer, it can return a smaller value than the property, which represents both the buffer and the Windows-created buffer. ]]> @@ -2019,7 +2019,7 @@ Use caution when using and together. Switching between reading bytes and reading characters can cause extra data to be read and/or other unintended behavior. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. > [!NOTE] -> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. +> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. ]]> @@ -2064,7 +2064,7 @@ Use caution when using and together. Switching between reading bytes and reading characters can cause extra data to be read and/or other unintended behavior. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. > [!NOTE] -> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. +> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. ]]> @@ -2109,7 +2109,7 @@ If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. > [!NOTE] -> The class buffers data, but the stream object contained in the property does not. Therefore, the object and the stream object might differ on the number of bytes that are available to read. When bytes are buffered to the object, the property includes these bytes in its value; however, these bytes might not be accessible to the stream contained in the property. +> The class buffers data, but the stream object contained in the property does not. Therefore, the object and the stream object might differ on the number of bytes that are available to read. When bytes are buffered to the object, the property includes these bytes in its value; however, these bytes might not be accessible to the stream contained in the property. ]]>
@@ -2146,12 +2146,12 @@ ## Remarks Note that while this method does not return the value, the value is removed from the input buffer. - By default, the method will block until a line is received. If this behavior is undesirable, set the property to any non-zero value to force the method to throw a if a line is not available on the port. + By default, the method will block until a line is received. If this behavior is undesirable, set the property to any non-zero value to force the method to throw a if a line is not available on the port. If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. > [!NOTE] -> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. +> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. @@ -2219,9 +2219,9 @@ The read time-out value was originally set at 500 milliseconds in the Win32 Communications API. This property allows you to set this value. The time-out can be set to any value greater than zero, or set to , in which case no time-out occurs. is the default. > [!NOTE] -> Users of the unmanaged `COMMTIMEOUTS` structure might expect to set the time-out value to zero to suppress time-outs. To suppress time-outs with the property, however, you must specify . +> Users of the unmanaged `COMMTIMEOUTS` structure might expect to set the time-out value to zero to suppress time-outs. To suppress time-outs with the property, however, you must specify . - This property does not affect the method of the stream returned by the property. + This property does not affect the method of the stream returned by the property. @@ -2277,7 +2277,7 @@ If it is necessary to switch between reading text and reading binary data from the stream, select a protocol that carefully defines the boundary between text and binary data, such as manually reading bytes and decoding the data. > [!NOTE] -> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. +> Because the class buffers data, and the stream contained in the property does not, the two might conflict about how many bytes are available to read. The property can indicate that there are bytes to read, but these bytes might not be accessible to the stream contained in the property because they have been buffered to the class. ]]>
@@ -2332,7 +2332,7 @@ event is also raised if an character is received, regardless of the number of bytes in the internal input buffer and the value of the property. + The event is also raised if an character is received, regardless of the number of bytes in the internal input buffer and the value of the property. ]]> @@ -2445,7 +2445,7 @@ ## Examples - The following example shows how to set the property to `One`. + The following example shows how to set the property to `One`. :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/datareceived.cs" id="Snippet20"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Ports/Handshake/Overview/datareceived.vb" id="Snippet20"::: @@ -2660,7 +2660,7 @@ property ignores any value smaller than 2048. + The property ignores any value smaller than 2048. ]]> @@ -2766,9 +2766,9 @@ The write time-out value was originally set at 500 milliseconds in the Win32 Communications API. This property allows you to set this value. The time-out can be set to any value greater than zero, or set to , in which case no time-out occurs. is the default. > [!NOTE] -> Users of the unmanaged `COMMTIMEOUTS` structure might expect to set the time-out value to zero to suppress time-outs. To suppress time-outs with the property, however, you must specify . +> Users of the unmanaged `COMMTIMEOUTS` structure might expect to set the time-out value to zero to suppress time-outs. To suppress time-outs with the property, however, you must specify . - This property does not affect the method of the stream returned by the property. + This property does not affect the method of the stream returned by the property. diff --git a/xml/System.IO.Ports/StopBits.xml b/xml/System.IO.Ports/StopBits.xml index bfff8e77e3f..72393b27eb2 100644 --- a/xml/System.IO.Ports/StopBits.xml +++ b/xml/System.IO.Ports/StopBits.xml @@ -34,12 +34,12 @@ property on the class. Stop bits separate each unit of data on an asynchronous serial connection. They are also sent continuously when no data is available for transmission. + You use this enumeration when setting the value of the property on the class. Stop bits separate each unit of data on an asynchronous serial connection. They are also sent continuously when no data is available for transmission. - The class throws an exception when you set the property to None. + The class throws an exception when you set the property to None. ## Examples - The following example shows how to set the property to `One`. + The following example shows how to set the property to `One`. :::code language="csharp" source="~/snippets/csharp/System.IO.Ports/Handshake/Overview/datareceived.cs" id="Snippet20"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Ports/Handshake/Overview/datareceived.vb" id="Snippet20"::: diff --git a/xml/System.IO/BufferedStream.xml b/xml/System.IO/BufferedStream.xml index e632cfdee11..d81f02f02fc 100644 --- a/xml/System.IO/BufferedStream.xml +++ b/xml/System.IO/BufferedStream.xml @@ -343,7 +343,7 @@ must be called exactly once for every call to . Failing to end a read process before beginning another read can cause undesirable behavior such as deadlock. > [!NOTE] -> Use the property to determine whether the current instance supports reading. +> Use the property to determine whether the current instance supports reading. must be called with this to find out how many bytes were read. @@ -858,7 +858,7 @@ Attempting to manipulate a stream after it has been closed might throw an value for the property. +If the operation is canceled before it completes, the returned task contains the value for the property. Copying begins at the current position in the current stream. @@ -1404,7 +1404,7 @@ Calling `DisposeAsync` allows the resources used by the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. +Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. Implementations of this method read a maximum of `buffer.Length` bytes from the current stream and store them in `buffer`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. Implementations return the number of bytes read. The implementation will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. @@ -1564,7 +1564,7 @@ Use for reading primitive data types. The `ReadAsync` method enables you to perform resource-intensive I/O 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -Use the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. If the operation is canceled before it completes, the returned task contains the value for the property. @@ -1631,7 +1631,7 @@ If the operation is canceled before it completes, the returned task contains the class and passing the property as the `cancellationToken` parameter. + You can create a cancellation token by creating an instance of the class and passing the property as the `cancellationToken` parameter. 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 . @@ -1941,7 +1941,7 @@ If the operation is canceled before it completes, the returned task contains the ## Remarks -Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current buffered stream. +Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current buffered stream. If the write operation is successful, the position within the buffered stream advances by the number of bytes written. If an exception occurs, the position within the buffered stream remains unchanged. @@ -2089,9 +2089,9 @@ If the write operation is successful, the position within the buffered stream ad The `WriteAsync` method enables you to perform resource-intensive I/O 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -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 operation is canceled before it completes, the returned task contains the value for the property. ]]> @@ -2156,7 +2156,7 @@ If the operation is canceled before it completes, the returned task contains the class and passing the property as the `cancellationToken` parameter. + You can create a cancellation token by creating an instance of the class and passing the property as the `cancellationToken` parameter. 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 . @@ -2227,7 +2227,7 @@ If the operation is canceled before it completes, the returned task contains the ## Remarks -Use the property to determine whether the current instance supports writing. +Use the property to determine whether the current instance supports writing. ]]> diff --git a/xml/System.IO/Directory.xml b/xml/System.IO/Directory.xml index 4ab5f2669dd..802fa2d22f3 100644 --- a/xml/System.IO/Directory.xml +++ b/xml/System.IO/Directory.xml @@ -4724,7 +4724,7 @@ There are too many levels of symbolic links.
The case-sensitivity of the `path` parameter corresponds to that of the file system on which the code is running. For example, it's case-insensitive on NTFS (the default Windows file system) and case-sensitive on Linux file systems. - If you are setting the directory to a drive with removable media (for example, "E:" for a USB flash drive), you can determine whether the drive is ready by using the property. + If you are setting the directory to a drive with removable media (for example, "E:" for a USB flash drive), you can determine whether the drive is ready by using the property. diff --git a/xml/System.IO/DirectoryInfo.xml b/xml/System.IO/DirectoryInfo.xml index dc044e45365..99534639a11 100644 --- a/xml/System.IO/DirectoryInfo.xml +++ b/xml/System.IO/DirectoryInfo.xml @@ -818,7 +818,7 @@ namespace ConsoleApp ## Examples - The following example enumerates the subdirectories under the C:\Program Files directory and uses a LINQ query to return the names of all directories that were created before 2009 by checking the value of the property. + The following example enumerates the subdirectories under the C:\Program Files directory and uses a LINQ query to return the names of all directories that were created before 2009 by checking the value of the property. If you only need the names of the subdirectories, use the static class for better performance. For an example, see the method. @@ -1226,7 +1226,7 @@ namespace ConsoleApp ## Examples - The following example enumerates the files under a specified directory and uses a LINQ query to return the names of all files that were created before 2009 by checking the value of the property. + The following example enumerates the files under a specified directory and uses a LINQ query to return the names of all files that were created before 2009 by checking the value of the property. If you only need the names of the files, use the static class for better performance. For an example, see the method. @@ -2005,7 +2005,7 @@ namespace ConsoleApp property returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. + The property returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. @@ -3137,7 +3137,7 @@ namespace ConsoleApp ## Remarks If there are no files or directories in the , this method returns an empty array. This method is not recursive. - For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. This method pre-populates the values of the following properties: @@ -3243,7 +3243,7 @@ namespace ConsoleApp This method is not recursive. - For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. Wild cards are permitted. For example, the `searchPattern` string "\*t" searches for all directory names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all directory names in `path` beginning with the letter "s". @@ -3345,7 +3345,7 @@ namespace ConsoleApp This method is not recursive. - For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. Wild cards are permitted. For example, the `searchPattern` string "\*t" searches for all directory names in `path` ending with the letter "t". The `searchPattern` string "s\*" searches for all directory names in `path` beginning with the letter "s". @@ -3443,7 +3443,7 @@ namespace ConsoleApp Characters other than the wildcard are literal characters. For example, the string "\*t" searches for all names in ending with the letter "t". ". The `searchPattern` string "s\*" searches for all names in `path` beginning with the letter "s". - For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. + For subdirectories, the objects returned by this method can be cast to the derived class . Use the value returned by the property to determine whether the represents a file or a directory. This method pre-populates the values of the following properties: @@ -3619,9 +3619,9 @@ namespace ConsoleApp property returns only the name of the directory, such as "Bin". To get the full path, such as "c:\public\Bin", use the property. + This property returns only the name of the directory, such as "Bin". To get the full path, such as "c:\public\Bin", use the property. - The property of a requires no permission (beyond the read permission to the directory necessary to construct the ) but can give out the directory name. If it is necessary to hand out a to a protected directory with a cryptographically secure name, create a dummy directory for the untrusted code's use. + The property of a requires no permission (beyond the read permission to the directory necessary to construct the ) but can give out the directory name. If it is necessary to hand out a to a protected directory with a cryptographically secure name, create a dummy directory for the untrusted code's use. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). diff --git a/xml/System.IO/DirectoryNotFoundException.xml b/xml/System.IO/DirectoryNotFoundException.xml index 6b2f84d3037..bd7b8f028fc 100644 --- a/xml/System.IO/DirectoryNotFoundException.xml +++ b/xml/System.IO/DirectoryNotFoundException.xml @@ -136,9 +136,9 @@ property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified directory." This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified directory." This message takes into account the current system culture. - The property of the new instance is initialized to `null`. + The property of the new instance is initialized to `null`. @@ -201,9 +201,9 @@ property of the new instance using `message`. + This constructor initializes the property of the new instance using `message`. - The property of the new instance is initialized to `null`. + The property of the new instance is initialized to `null`. ]]> @@ -321,7 +321,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.IO/DriveInfo.xml b/xml/System.IO/DriveInfo.xml index c3f5a209a69..a010af481c1 100644 --- a/xml/System.IO/DriveInfo.xml +++ b/xml/System.IO/DriveInfo.xml @@ -70,19 +70,19 @@ Provides access to information on a drive. - to determine what drives are available, and what type of drives they are. You can also query to determine the capacity and available free space on the drive. - - - -## Examples - The following code example demonstrates the use of the class to display information about all of the drives on the current system. - + to determine what drives are available, and what type of drives they are. You can also query to determine the capacity and available free space on the drive. + + + +## Examples + The following code example demonstrates the use of the class to display information about all of the drives on the current system. + :::code language="csharp" source="~/snippets/csharp/System.IO/DriveInfo/Overview/DriveInfo.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: + ]]> @@ -133,13 +133,13 @@ A valid drive letter or fully qualified path. Creates a new instance of the class. - The drive letter cannot be . @@ -193,19 +193,19 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o Indicates the amount of available free space on a drive, in bytes. The amount of free space available on the drive, in bytes. - number because this property takes into account disk quotas. - - - -## Examples - The following code example demonstrates the use of the class to display information about all of the drives on the current system. - + number because this property takes into account disk quotas. + + + +## Examples + The following code example demonstrates the use of the class to display information about all of the drives on the current system. + :::code language="csharp" source="~/snippets/csharp/System.IO/DriveInfo/Overview/DriveInfo.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: + ]]> Access to the drive information is denied. @@ -258,19 +258,19 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o Gets the name of the file system, such as NTFS or FAT32. The name of the file system on the specified drive. - to determine what formatting a drive uses. - - - -## Examples - The following code example demonstrates the use of the class to display information about all of the drives on the current system. - + to determine what formatting a drive uses. + + + +## Examples + The following code example demonstrates the use of the class to display information about all of the drives on the current system. + :::code language="csharp" source="~/snippets/csharp/System.IO/DriveInfo/Overview/DriveInfo.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: + ]]> Access to the drive information is denied. @@ -324,19 +324,19 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o Gets the drive type, such as CD-ROM, removable, network, or fixed. One of the enumeration values that specifies a drive type. - property indicates whether a drive is one of the following: `CDRom`, `Fixed`, `Network`, `NoRootDirectory`, `Ram`, `Removable`, or `Unknown`. These values are described in the enumeration. - - - -## Examples - The following code example demonstrates the use of the class to display information about all the drives on the current system. - + property indicates whether a drive is one of the following: `CDRom`, `Fixed`, `Network`, `NoRootDirectory`, `Ram`, `Removable`, or `Unknown`. These values are described in the enumeration. + + + +## Examples + The following code example demonstrates the use of the class to display information about all the drives on the current system. + :::code language="csharp" source="~/snippets/csharp/System.IO/DriveInfo/Overview/DriveInfo.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: + ]]> @@ -388,19 +388,19 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o Retrieves the drive names of all logical drives on a computer. An array of type that represents the logical drives on a computer. - methods and properties. Use the property to test whether a drive is ready because using this method on a drive that is not ready will throw a . - - - -## Examples - The following code example demonstrates the use of the class to display information about all of the drives on the current system. - + methods and properties. Use the property to test whether a drive is ready because using this method on a drive that is not ready will throw a . + + + +## Examples + The following code example demonstrates the use of the class to display information about all of the drives on the current system. + :::code language="csharp" source="~/snippets/csharp/System.IO/DriveInfo/Overview/DriveInfo.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: + ]]> An I/O error occurred (for example, a disk error or a drive was not ready). @@ -455,21 +455,21 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o if the drive is ready; if the drive is not ready. - indicates whether a drive is ready. For example, it indicates whether a CD is in a CD drive or whether a removable storage device is ready for read/write operations. If you do not test whether a drive is ready, and it is not ready, querying the drive using will raise an . - - Do not rely on to avoid catching exceptions from other members such as , , and . Between the time that your code checks and then accesses one of the other properties (even if the access occurs immediately after the check), a drive may have been disconnected or a disk may have been removed. - - - -## Examples - The following code example demonstrates the use of the class to display information about all of the drives on the current system. - + indicates whether a drive is ready. For example, it indicates whether a CD is in a CD drive or whether a removable storage device is ready for read/write operations. If you do not test whether a drive is ready, and it is not ready, querying the drive using will raise an . + + Do not rely on to avoid catching exceptions from other members such as , , and . Between the time that your code checks and then accesses one of the other properties (even if the access occurs immediately after the check), a drive may have been disconnected or a disk may have been removed. + + + +## Examples + The following code example demonstrates the use of the class to display information about all of the drives on the current system. + :::code language="csharp" source="~/snippets/csharp/System.IO/DriveInfo/Overview/DriveInfo.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: + ]]> @@ -514,19 +514,19 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o Gets the name of a drive, such as C:\\. The name of the drive. - class to display information about all of the drives on the current system. - + class to display information about all of the drives on the current system. + :::code language="csharp" source="~/snippets/csharp/System.IO/DriveInfo/Overview/DriveInfo.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: + ]]> @@ -632,13 +632,13 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o The destination (see ) for this serialization. Populates a object with the data needed to serialize the target object. - object are automatically tracked and serialized by the formatter. - - This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. - + object are automatically tracked and serialized by the formatter. + + This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. + ]]> @@ -684,11 +684,11 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o Returns a drive name as a string. The name of the drive. - property. - + property. + ]]> @@ -739,19 +739,19 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o Gets the total amount of free space available on a drive, in bytes. The total free space available on a drive, in bytes. - class to display information about all of the drives on the current system. - + class to display information about all of the drives on the current system. + :::code language="csharp" source="~/snippets/csharp/System.IO/DriveInfo/Overview/DriveInfo.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: + ]]> Access to the drive information is denied. @@ -805,19 +805,19 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o Gets the total size of storage space on a drive, in bytes. The total size of the drive, in bytes. - class to display information about all of the drives on the current system. - + class to display information about all of the drives on the current system. + :::code language="csharp" source="~/snippets/csharp/System.IO/DriveInfo/Overview/DriveInfo.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: + ]]> Access to the drive information is denied. @@ -879,28 +879,28 @@ On Windows, passing a mounted directory (for example, C:\\NetworkMountedDrive) o Gets or sets the volume label of a drive. The volume label. - . - - - -## Examples - The following example demonstrates the use of the class to display information about all the drives on the current system. - + . + + + +## Examples + The following example demonstrates the use of the class to display information about all the drives on the current system. + :::code language="csharp" source="~/snippets/csharp/System.IO/DriveInfo/Overview/DriveInfo.cs" id="Snippet00"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/DriveInfo/Overview/DriveInfo.vb" id="Snippet00"::: + ]]> An I/O error occurred (for example, a disk error or a drive was not ready). The drive is not mapped or does not exist. The caller does not have the required permission. - The volume label is being set on a network or CD-ROM drive. - - -or- - + The volume label is being set on a network or CD-ROM drive. + + -or- + Access to the drive information is denied. diff --git a/xml/System.IO/DriveNotFoundException.xml b/xml/System.IO/DriveNotFoundException.xml index 7a000f4c4b1..5300edd1663 100644 --- a/xml/System.IO/DriveNotFoundException.xml +++ b/xml/System.IO/DriveNotFoundException.xml @@ -61,11 +61,11 @@ The exception that is thrown when trying to access a drive or share that is not available. - class uses the HRESULT COR_E_DIRECTORYNOTFOUND. This exception can be thrown when a Win32 ERROR_PATH_NOT_FOUND HRESULT error is encountered. - + class uses the HRESULT COR_E_DIRECTORYNOTFOUND. This exception can be thrown when a Win32 ERROR_PATH_NOT_FOUND HRESULT error is encountered. + ]]> @@ -126,13 +126,13 @@ Initializes a new instance of the class with its message string set to a system-supplied message and its HRESULT set to COR_E_DIRECTORYNOTFOUND. - property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified directory." This message is localized based on the current system culture. - - The property of the new instance is initialized to `null`. - + property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified directory." This message is localized based on the current system culture. + + The property of the new instance is initialized to `null`. + ]]> @@ -183,13 +183,13 @@ A object that describes the error. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with the specified message string and the HRESULT set to COR_E_DIRECTORYNOTFOUND. - property of the new instance using the `message` parameter. - - The property of the new instance is initialized to `null`. - + property of the new instance using the `message` parameter. + + The property of the new instance is initialized to `null`. + ]]> @@ -304,18 +304,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 the 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.IO/EndOfStreamException.xml b/xml/System.IO/EndOfStreamException.xml index 9ade0685a32..d0c7f338136 100644 --- a/xml/System.IO/EndOfStreamException.xml +++ b/xml/System.IO/EndOfStreamException.xml @@ -346,7 +346,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml index fcd64c21b40..db9967bc278 100644 --- a/xml/System.IO/File.xml +++ b/xml/System.IO/File.xml @@ -5225,7 +5225,7 @@ The following example moves a file. The file handle is guaranteed to be closed by this method, even if exceptions are raised. - To use the encoding settings as configured for your operating system, specify the property for the `encoding` parameter. + To use the encoding settings as configured for your operating system, specify the property for the `encoding` parameter. diff --git a/xml/System.IO/FileFormatException.xml b/xml/System.IO/FileFormatException.xml index 42df5c788cc..64c410c1d2b 100644 --- a/xml/System.IO/FileFormatException.xml +++ b/xml/System.IO/FileFormatException.xml @@ -104,11 +104,11 @@ Creates a new instance of the class. - @@ -189,13 +189,13 @@ The value of the file that caused this error. Creates a new instance of the class with a source URI value. - property of the new instance to a system-supplied message that describes the error and includes the file name, such as "The file '`sourceUri`' does not conform to the expected file format specification." This message takes into account the current system culture. - - The property is initialized using the `sourceUri` parameter. - + property of the new instance to a system-supplied message that describes the error and includes the file name, such as "The file '`sourceUri`' does not conform to the expected file format specification." This message takes into account the current system culture. + + The property is initialized using the `sourceUri` parameter. + ]]> @@ -288,11 +288,11 @@ The value of the property, which represents the cause of the current exception. Creates a new instance of the class with a specified error message and exception type. - property of the new instance with the specified error message represented by `message`. - + property of the new instance with the specified error message represented by `message`. + ]]> @@ -333,13 +333,13 @@ The value of the property, which represents the cause of the current exception. Creates a new instance of the class with a source URI value and an exception type. - property is initialized using the `sourceUri` parameter. - + property is initialized using the `sourceUri` parameter. + ]]> @@ -386,13 +386,13 @@ A value that represents the error message. Creates a new instance of the class with a source URI value and a specified error message. - property of the new instance with the specified error message represented by `message`. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - The property is initialized using the `sourceUri` parameter. - + property of the new instance with the specified error message represented by `message`. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + The property is initialized using the `sourceUri` parameter. + ]]> @@ -441,13 +441,13 @@ The value of the property, which represents the cause of the current exception. Creates a new instance of the class with a source URI value, a specified error message, and an exception type. - property is initialized using the `sourceUri` parameter. - + property is initialized using the `sourceUri` parameter. + ]]> @@ -548,11 +548,11 @@ Gets the name of a file that caused the . A that represents the name the file that caused the exception. - returns an empty string. - + returns an empty string. + ]]> diff --git a/xml/System.IO/FileInfo.xml b/xml/System.IO/FileInfo.xml index df11494ad69..9e3907e8922 100644 --- a/xml/System.IO/FileInfo.xml +++ b/xml/System.IO/FileInfo.xml @@ -107,13 +107,13 @@ The class provides the following properties that enable you to retrieve information about a file. For an example of how to use each property, see the property pages. -- The property retrieves an object that represents the parent directory of a file. +- The property retrieves an object that represents the parent directory of a file. -- The property retrieves the full path of the parent directory of a file. +- The property retrieves the full path of the parent directory of a file. -- The property checks for the presence of a file before operating on it. +- The property checks for the presence of a file before operating on it. -- The property retrieves or sets a value that specifies whether a file can be modified. +- The property retrieves or sets a value that specifies whether a file can be modified. - The retrieves the size of a file. @@ -910,7 +910,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. property. + To get the parent directory as a string, use the property. @@ -988,7 +988,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. object, use the property. + To get the parent directory as a object, use the property. When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. @@ -1152,12 +1152,12 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. ## Remarks When first called, calls and caches information about the file. On subsequent calls, you must call to get the latest copy of the information. - The property returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. + The property returns `false` if any error occurs while trying to determine if the specified file exists. This can occur in situations that raise exceptions such as passing a file name with invalid characters or too many characters, a failing or missing disk, or if the caller does not have permission to read the file. ## Examples - The following code example uses the property ensure a file exists before opening it. You can use this technique to throw a custom exception when the file is not found. + The following code example uses the property ensure a file exists before opening it. You can use this technique to throw a custom exception when the file is not found. :::code language="csharp" source="~/snippets/csharp/System.IO/FileInfo/Exists/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileInfo/Exists/sample.vb" id="Snippet1"::: @@ -1345,7 +1345,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. property to quickly determine or change whether the current file is read only. + Use the property to quickly determine or change whether the current file is read only. If the current file does not exist, getting this property will always return `true`, but attempts to set will throw a . @@ -1425,7 +1425,7 @@ C:\Users\userName\AppData\Local\Temp\tmp70CB.tmp was successfully deleted. property is pre-cached if the current instance of the object was returned from any of the following methods: + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - diff --git a/xml/System.IO/FileLoadException.xml b/xml/System.IO/FileLoadException.xml index 7544692a758..14a27b3433c 100644 --- a/xml/System.IO/FileLoadException.xml +++ b/xml/System.IO/FileLoadException.xml @@ -153,7 +153,7 @@ The exact timing of when static assembly references are loaded is unspecified. T property and property of the new instance are initialized to `null`. + The property and property of the new instance are initialized to `null`. ]]> @@ -208,7 +208,7 @@ The exact timing of when static assembly references are loaded is unspecified. T property of the new instance using `message`. The property and property of the new instance are initialized to `null`. + This constructor initializes the property of the new instance using `message`. The property and property of the new instance are initialized to `null`. ]]> @@ -326,7 +326,7 @@ The exact timing of when static assembly references are loaded is unspecified. T property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. The following table shows the initial property values for an instance of . @@ -394,7 +394,7 @@ The exact timing of when static assembly references are loaded is unspecified. T property of the new instance using `message` and the property using `fileName`. The property of the new instance is initialized to `null`. + This constructor initializes the property of the new instance using `message` and the property using `fileName`. The property of the new instance is initialized to `null`. is not required to be a file stored on disk; it can be any part of a system that supports access to streams. For example, depending on the system, this class might be able to access a physical device. @@ -455,7 +455,7 @@ The exact timing of when static assembly references are loaded is unspecified. T property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. is not required to be a file stored on disk; it can be any part of a system that supports access to streams. For example, depending on the system, this class might be able to access a physical device. @@ -706,7 +706,7 @@ The exact timing of when static assembly references are loaded is unspecified. T ## Remarks This property overrides . - If no message was supplied to the constructor for the current exception, this property returns a system-supplied error message. If the property is not a null reference, the message includes the file name, for example, "Unable to load file a `FileName`." (a `FileName` represents the value returned by .) If is `null`, this is indicated in the system-supplied message as "(null)". The system-supplied message takes into account the current system culture. + If no message was supplied to the constructor for the current exception, this property returns a system-supplied error message. If the property is not a null reference, the message includes the file name, for example, "Unable to load file a `FileName`." (a `FileName` represents the value returned by .) If is `null`, this is indicated in the system-supplied message as "(null)". The system-supplied message takes into account the current system culture. This property is read-only. @@ -771,7 +771,7 @@ The exact timing of when static assembly references are loaded is unspecified. T ## Remarks This method overrides . - The string representation returned by this method includes the name of the exception, the value of the the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. + The string representation returned by this method includes the name of the exception, the value of the the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. ]]> diff --git a/xml/System.IO/FileNotFoundException.xml b/xml/System.IO/FileNotFoundException.xml index cebee09e49f..835db1ca4e0 100644 --- a/xml/System.IO/FileNotFoundException.xml +++ b/xml/System.IO/FileNotFoundException.xml @@ -150,7 +150,7 @@ property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified file." This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "Could not find the specified file." This message takes into account the current system culture. ]]> @@ -209,7 +209,7 @@ property of the new instance using `message`. + This constructor initializes the property of the new instance using `message`. ]]> @@ -334,7 +334,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . @@ -406,7 +406,7 @@ property of the new instance using `message` and the property using `fileName`. + The constructor initializes the property of the new instance using `message` and the property using `fileName`. ]]> @@ -469,7 +469,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . @@ -726,7 +726,7 @@ property is not `null`, the message includes the file name. + If no message was supplied to the constructor for the current exception, this property returns a system-supplied error message. If the property is not `null`, the message includes the file name. This property is read-only. @@ -795,7 +795,7 @@ ## Remarks This method overrides . - The string representation returned by this method includes the name of the exception, the value of the property, the result of calling ToString on the inner exception, the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. + The string representation returned by this method includes the name of the exception, the value of the property, the result of calling ToString on the inner exception, the value of the property, and the result of calling . If any of these members is a null reference, its value is not included in the returned string. ]]> diff --git a/xml/System.IO/FileStream.xml b/xml/System.IO/FileStream.xml index d6346d792d7..9b2093567ee 100644 --- a/xml/System.IO/FileStream.xml +++ b/xml/System.IO/FileStream.xml @@ -354,7 +354,7 @@ > [!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 . + 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. @@ -735,7 +735,7 @@ The file was too large (when [!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 . + 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. @@ -1253,7 +1253,7 @@ The file was too large (when [!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 . + 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. @@ -1486,7 +1486,7 @@ The file was too large (when [!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 . + 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. @@ -1702,7 +1702,7 @@ The file was too large (when 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`. + The `IsAsync` property detects whether the `FileStream` handle was opened asynchronously, enabling your code to use the 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. + 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. @@ -3497,7 +3497,7 @@ If the absolute path is not known, this property returns a string similar to "[U ## Remarks -Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. +Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. This method reads a maximum of `buffer.Length` bytes from the current file stream and stores them in `buffer`. The current position within the file stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the file stream remains unchanged. The method will block until at least one byte of data can be read, in the event that no data is available. `Read` returns 0 only when there is no more data in the file stream and no more is expected (such as a closed socket or end of file). The method is free to return fewer bytes than requested even if the end of the file stream has not been reached. @@ -3662,7 +3662,7 @@ Use for reading primitive data types. The `ReadAsync` method enables you 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -Use the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. 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. @@ -3748,7 +3748,7 @@ The following example shows how to read from a file asynchronously. The `ReadAsync` method enables you 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. -Use the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. 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. @@ -3834,7 +3834,7 @@ The following example shows how to read from a file asynchronously. This method overrides . > [!NOTE] -> Use the property to determine whether the current instance supports reading. For additional information, see . +> Use the property to determine whether the current instance supports reading. For additional information, see . @@ -3912,7 +3912,7 @@ The following example shows how to read from a file asynchronously. 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. + The 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. ]]> @@ -3984,7 +3984,7 @@ The following example shows how to read from a file asynchronously. This method overrides . > [!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. @@ -4136,7 +4136,7 @@ The following example shows how to read from a file asynchronously. 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 . +> 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). @@ -4287,7 +4287,7 @@ The following example shows how to read from a file asynchronously. ## Remarks -Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. +Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. If the write operation is successful, the position within the file stream advances by the number of bytes written. If an exception occurs, the position within the file stream remains unchanged. @@ -4370,7 +4370,7 @@ 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 . +> 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. @@ -4455,7 +4455,7 @@ Another thread may have caused an unexpected change in the position of the opera The `WriteAsync` method lets you perform resource-intensive I/O 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. @@ -4532,9 +4532,9 @@ If the operation is canceled before it completes, the returned task contains the ## Remarks The 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. + 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 . @@ -4620,7 +4620,7 @@ This method stores in the task it returns all non-usage exceptions that the meth 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 . +> 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. diff --git a/xml/System.IO/FileSystemEventArgs.xml b/xml/System.IO/FileSystemEventArgs.xml index efdb605f10a..6ea5c7c05ef 100644 --- a/xml/System.IO/FileSystemEventArgs.xml +++ b/xml/System.IO/FileSystemEventArgs.xml @@ -196,7 +196,7 @@ The class is passed as a parameter to event property. This code example is part of a larger example provided for the class. + The following example demonstrates the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.IO/ErrorEventArgs/Overview/filesystemwatcher.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/ErrorEventArgs/Overview/FileSystemWatcher.vb" id="Snippet7"::: @@ -261,7 +261,7 @@ This property returns the same path that `FileSystemWatcher` is initialized with ## Examples -The following example demonstrates the property. This code example is part of a larger example provided for the class. +The following example demonstrates the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.IO/ErrorEventArgs/Overview/filesystemwatcher.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/ErrorEventArgs/Overview/FileSystemWatcher.vb" id="Snippet7"::: @@ -325,9 +325,9 @@ The following example demonstrates the property is the relative path of the affected file or directory, with respect to the directory being watched. For example, if a object is watching the directory "C:\temp" and the file at "C:\temp\test\file.txt" changes, the property will return "test\file.txt". + The name returned by the property is the relative path of the affected file or directory, with respect to the directory being watched. For example, if a object is watching the directory "C:\temp" and the file at "C:\temp\test\file.txt" changes, the property will return "test\file.txt". - The property may be null for renamed events if the does not get matching old and new name events from the OS. + The property may be null for renamed events if the does not get matching old and new name events from the OS. ]]> diff --git a/xml/System.IO/FileSystemInfo.xml b/xml/System.IO/FileSystemInfo.xml index bcd1e7e57e1..4a7cd09b2a5 100644 --- a/xml/System.IO/FileSystemInfo.xml +++ b/xml/System.IO/FileSystemInfo.xml @@ -312,7 +312,7 @@ property is pre-cached if the current instance of the object was returned from any of the following methods: + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - @@ -332,14 +332,14 @@ The value of this property is a combination of the archive, compressed, directory, hidden, offline, read-only, system, and temporary file attribute flags. - When you set this value, use the bitwise OR operator (`|` in C# or `Or` in Visual Basic) to apply more than one value. To retain any existing values in the property, include the value of the property in your assignment. For example: + When you set this value, use the bitwise OR operator (`|` in C# or `Or` in Visual Basic) to apply more than one value. To retain any existing values in the property, include the value of the property in your assignment. For example: `exampleFile.Attributes = exampleFile.Attributes | FileAttributes.ReadOnly;` ## Examples - The following example demonstrates the property. This code example is part of a larger example provided for the class. + The following example demonstrates the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileSystemInfo/Overview/FileSystemInfo.vb" id="Snippet2"::: @@ -475,7 +475,7 @@ An I/O error occurred. > [!NOTE] > This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - @@ -498,7 +498,7 @@ On Unix platforms that do not support creation or birth time, this property retu NTFS-formatted drives may cache file meta-info, such as file creation time, for a short period of time. This process is known as file tunneling. As a result, it may be necessary to explicitly set the creation time of a file if you are overwriting or replacing an existing file. ## Examples - The following example demonstrates the property. This code example is part of a larger example provided for the class. + The following example demonstrates the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileSystemInfo/Overview/FileSystemInfo.vb" id="Snippet2"::: @@ -578,7 +578,7 @@ On Unix platforms that do not support creation or birth time, this property retu > [!NOTE] > This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - @@ -862,7 +862,7 @@ The `Extension` property returns the extension, ## Examples - The following example demonstrates the property. This code example is part of a larger example provided for the class. + The following example demonstrates the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileSystemInfo/Overview/FileSystemInfo.vb" id="Snippet2"::: @@ -1075,7 +1075,7 @@ The `Extension` property returns the extension, If the file described in the object does not exist, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - @@ -1094,7 +1094,7 @@ The `Extension` property returns the extension, ## Examples - The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. + The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/LastAccessTime/touch.cs" id="Snippet00"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileSystemInfo/LastAccessTime/touch.vb" id="Snippet00"::: @@ -1173,7 +1173,7 @@ The `Extension` property returns the extension, > [!NOTE] > This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - @@ -1263,7 +1263,7 @@ The `Extension` property returns the extension, > [!NOTE] > This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - @@ -1282,7 +1282,7 @@ The `Extension` property returns the extension, If the file or directory described in the object does not exist, or if the file system that contains this file or directory does not support this information, this property returns 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC), adjusted to local time. ## Examples - The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. + The following code example demonstrates the updating of the property through a "touch" operation. In this example, the file is "touched", updating the , and properties to the current date and time. :::code language="csharp" source="~/snippets/csharp/System.IO/FileSystemInfo/LastAccessTime/touch.cs" id="Snippet00"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/FileSystemInfo/LastAccessTime/touch.vb" id="Snippet00"::: @@ -1361,7 +1361,7 @@ The `Extension` property returns the extension, > [!NOTE] > This method may return an inaccurate value because it uses native functions whose values may not be continuously updated by the operating system. - The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: + The value of the property is pre-cached if the current instance of the object was returned from any of the following methods: - diff --git a/xml/System.IO/FileSystemWatcher.xml b/xml/System.IO/FileSystemWatcher.xml index a7bc643d8f1..6e60068bd5b 100644 --- a/xml/System.IO/FileSystemWatcher.xml +++ b/xml/System.IO/FileSystemWatcher.xml @@ -242,7 +242,7 @@ 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. + 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. ]]> @@ -460,7 +460,7 @@ > 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`. +> The order in which the event is raised in relation to the other events may change when the property is not `null`. @@ -535,7 +535,7 @@ > 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 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. @@ -613,7 +613,7 @@ > 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 order in which the event is raised in relation to the other events may change when the property is not `null`. @@ -793,7 +793,7 @@ The component will not raise events unless you set to `true`. > [!NOTE] -> The component will not watch the specified directory until the property has been set and is `true`. +> 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`. @@ -1016,9 +1016,9 @@ 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. + To watch changes in all files, set the 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. + The property can be changed after the object has started receiving events. For more information about filtering out unwanted notifications, see the , , and properties. @@ -1145,9 +1145,9 @@ 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. + Set 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. + 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. @@ -1223,7 +1223,7 @@ 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. + You can set the buffer to 4 KB or larger, but it must not exceed 64 KB. If you try to set the 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. @@ -1365,7 +1365,7 @@ ## Remarks 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. + 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. @@ -1729,14 +1729,14 @@ 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. + This is a fully qualified path to a directory. If the 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. + 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. + 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. @@ -1962,7 +1962,7 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) 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. + 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. ]]> @@ -2036,7 +2036,7 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) This method waits indefinitely until the first change occurs and then returns. This is the same as using 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`. +> 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". @@ -2098,7 +2098,7 @@ Public Delegate Sub RenamedEventHandler(sender As Object, e As RenamedEventArgs) This method waits until a change occurs or it has timed out. A value of -1 for the `timeout` parameter means wait indefinitely. > [!NOTE] -> This method allows an event handler to be invoked to respond to file changes even if the property is set to `false`. +> 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.IO/IOException.xml b/xml/System.IO/IOException.xml index 222b5187281..95d89229e9d 100644 --- a/xml/System.IO/IOException.xml +++ b/xml/System.IO/IOException.xml @@ -174,7 +174,7 @@ property of the new instance to a system-supplied message that describes the error, such as "An I/O error occurred while performing the requested operation." This message takes into account the current system culture. + The constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "An I/O error occurred while performing the requested operation." This message takes into account the current system culture. ]]> @@ -233,7 +233,7 @@ property of the new instance using `message`. + The constructor initializes the property of the new instance using `message`. ]]> @@ -358,7 +358,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.IO/InternalBufferOverflowException.xml b/xml/System.IO/InternalBufferOverflowException.xml index fd7cfc74c61..e049e12a142 100644 --- a/xml/System.IO/InternalBufferOverflowException.xml +++ b/xml/System.IO/InternalBufferOverflowException.xml @@ -57,19 +57,19 @@ The exception thrown when the internal buffer overflows. - , when you are notified of file changes, the system stores those changes in a buffer the component creates and passes to the Application Programming Interfaces (APIs). If there are many changes in a short time, the buffer can easily overflow, resulting in an exception being thrown, which essentially loses all changes. To keep the buffer from overflowing, use the and properties to filter out your unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. - - - -## Examples - The following example shows how to create a FileSystemWatcher to monitor file changes (creates, deletes, renames, changes) occurring on a disk drive. The example also shows how to properly receive error notifications. - + , when you are notified of file changes, the system stores those changes in a buffer the component creates and passes to the Application Programming Interfaces (APIs). If there are many changes in a short time, the buffer can easily overflow, resulting in an exception being thrown, which essentially loses all changes. To keep the buffer from overflowing, use the and properties to filter out your unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + + + +## Examples + The following example shows how to create a FileSystemWatcher to monitor file changes (creates, deletes, renames, changes) occurring on a disk drive. The example also shows how to properly receive error notifications. + :::code language="csharp" source="~/snippets/csharp/System.IO/ErrorEventArgs/Overview/filesystemwatcher.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO/ErrorEventArgs/Overview/FileSystemWatcher.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO/ErrorEventArgs/Overview/FileSystemWatcher.vb" id="Snippet1"::: + ]]> @@ -131,11 +131,11 @@ Initializes a new default instance of the class. - and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. - + and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + ]]> @@ -185,11 +185,11 @@ The message to be given for the exception. Initializes a new instance of the class with the error message to be displayed specified. - and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. - + and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + ]]> @@ -297,11 +297,11 @@ The inner exception. Initializes a new instance of the class with the message to be displayed and the generated inner exception specified. - and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. - + and properties to filter out unwanted change notifications. You can also increase the size of the internal buffer through the property. However, increasing the size of the buffer is expensive, so keep the buffer as small as possible. + ]]> diff --git a/xml/System.IO/InvalidDataException.xml b/xml/System.IO/InvalidDataException.xml index 46d48c9686e..c80fdc67cd4 100644 --- a/xml/System.IO/InvalidDataException.xml +++ b/xml/System.IO/InvalidDataException.xml @@ -170,7 +170,7 @@ property of the new instance to a system-supplied message that describes the error, such as "An invalid argument was specified." This message is localized based on the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "An invalid argument was specified." This message is localized based on the current system culture. ]]> @@ -234,7 +234,7 @@ property of the new instance to a system-supplied message that describes the error, such as "An invalid argument was specified." This message is localized based on the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "An invalid argument was specified." This message is localized based on the current system culture. ]]> @@ -300,9 +300,9 @@ property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + This constructor initializes the property of the new instance using the value of the `message` parameter. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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. ]]> diff --git a/xml/System.IO/PathTooLongException.xml b/xml/System.IO/PathTooLongException.xml index ee44e1ea47a..d33c375c1a2 100644 --- a/xml/System.IO/PathTooLongException.xml +++ b/xml/System.IO/PathTooLongException.xml @@ -139,7 +139,7 @@ property of the new instance to a system-supplied message that describes the error, such as "The supplied path is too long." This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "The supplied path is too long." This message takes into account the current system culture. ]]> @@ -194,7 +194,7 @@ property of the new instance using `message`. + This constructor initializes the property of the new instance using `message`. ]]> @@ -312,7 +312,7 @@ property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the property. The `InnerException` property returns the same value that is passed into the constructor, or `null` if the `InnerException` property does not supply the inner exception value to the constructor. The following table shows the initial property values for an instance of . diff --git a/xml/System.IO/RenamedEventArgs.xml b/xml/System.IO/RenamedEventArgs.xml index e9022f45e42..54f7a3f8b6c 100644 --- a/xml/System.IO/RenamedEventArgs.xml +++ b/xml/System.IO/RenamedEventArgs.xml @@ -192,7 +192,7 @@ This property returns the same path that `FileSystemWatcher` is initialized with ## Examples -The following example demonstrates the property. This code example is part of a larger example provided for the class. +The following example demonstrates the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.IO/ErrorEventArgs/Overview/filesystemwatcher.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/ErrorEventArgs/Overview/FileSystemWatcher.vb" id="Snippet8"::: diff --git a/xml/System.IO/Stream.xml b/xml/System.IO/Stream.xml index c83d6bfc8b1..004c939c6e2 100644 --- a/xml/System.IO/Stream.xml +++ b/xml/System.IO/Stream.xml @@ -286,7 +286,7 @@ Multiple simultaneous asynchronous requests render the request completion order uncertain. - Use the property to determine whether the current instance supports reading. + Use the property to determine whether the current instance supports reading. If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from `BeginRead`. Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling `EndRead`. @@ -386,7 +386,7 @@ The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. - Use the property to determine whether the current instance supports writing. + Use the property to determine whether the current instance supports writing. If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from `BeginWrite`. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling `EndWrite`. @@ -584,7 +584,7 @@ property always returns `false`. Some stream implementations require different behavior, such as , which times out if network connectivity is interrupted or lost. If you are implementing a stream that must be able to time out, this property should be overridden to return `true`. + The property always returns `false`. Some stream implementations require different behavior, such as , which times out if network connectivity is interrupted or lost. If you are implementing a stream that must be able to time out, this property should be overridden to return `true`. ]]> @@ -1092,7 +1092,7 @@ ## Remarks The method enables you to perform resource-intensive I/O 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - If the operation is canceled before it completes, the returned task contains the value for the property. + If the operation is canceled before it completes, the returned task contains the value for the property. Copying begins at the current position in the current stream. @@ -1168,7 +1168,7 @@ ## Remarks The method enables you to perform resource-intensive I/O 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - If the operation is canceled before it completes, the returned task contains the value for the property. + If the operation is canceled before it completes, the returned task contains the value for the property. Copying begins at the current position in the current stream. @@ -1802,7 +1802,7 @@ value for the property. + If the operation is canceled before it completes, the returned task contains the value for the property. If a derived class, such as or , does not flush the buffer in its implementation of the method, the method will not flush the buffer. @@ -2023,7 +2023,7 @@ property to determine whether the stream supports seeking. + The stream must support seeking to get or set the position. Use the property to determine whether the stream supports seeking. Seeking to any location beyond the length of the stream is supported. @@ -2081,7 +2081,7 @@ property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. + Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. Implementations of this method read a maximum of `buffer.Length` bytes from the current stream and store them in `buffer`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. Implementations return the number of bytes read. If more than zero bytes are requested, the implementation will not complete the operation until at least one byte of data can be read (if zero bytes were requested, some implementations may similarly not complete until at least one byte is available, but no data will be consumed from the stream in such a case). returns 0 only if zero bytes were requested or when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. @@ -2149,7 +2149,7 @@ property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. + Use the property to determine whether the current instance supports reading. Use the method to read asynchronously from the current stream. Implementations of this method read a maximum of `count` bytes from the current stream and store them in `buffer` beginning at `offset`. The current position within the stream is advanced by the number of bytes read; however, if an exception occurs, the current position within the stream remains unchanged. Implementations return the number of bytes read. If more than zero bytes are requested, the implementation will not complete the operation until at least one byte of data can be read (some implementations may similarly not complete until at least one byte is available even if zero bytes were requested, but no data will be consumed from the stream in such a case). returns 0 only if zero bytes were requested or when there is no more data in the stream and no more is expected (such as a closed socket or end of file). An implementation is free to return fewer bytes than requested even if the end of the stream has not been reached. @@ -2236,7 +2236,7 @@ ## Remarks The method enables you to perform resource-intensive I/O 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - Use the property to determine whether the current instance supports reading. + Use the property to determine whether the current instance supports reading. If the operation is canceled before it completes, the returned task contains the value for the property. @@ -2310,7 +2310,7 @@ ## Remarks The method enables you to perform resource-intensive I/O 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - Use the property to determine whether the current instance supports reading. + Use the property to determine whether the current instance supports reading. 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 . @@ -2397,9 +2397,9 @@ ## Remarks The method enables you to perform resource-intensive I/O 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - Use the property to determine whether the current instance supports reading. + Use the property to determine whether the current instance supports reading. - If the operation is canceled before it completes, the returned task contains the value for the property. + If the operation is canceled before it completes, the returned task contains the value for the property. For an example, see the overload. @@ -2590,7 +2590,7 @@ When `minimumBytes` is 0 (zero), this read operation will be completed without w property to determine whether the current instance supports reading. + Use the property to determine whether the current instance supports reading. Attempts to manipulate the stream after the stream has been closed could throw an . @@ -2944,7 +2944,7 @@ The range specified by the combination of and property to determine whether the current instance supports seeking. + Use the property to determine whether the current instance supports seeking. If `offset` is negative, the new position is required to precede the position specified by `origin` by the number of bytes specified by `offset`. If `offset` is zero (0), the new position is required to be the position specified by `origin`. If `offset` is positive, the new position is required to follow the position specified by `origin` by the number of bytes specified by `offset`. @@ -3018,7 +3018,7 @@ The range specified by the combination of and property to determine whether the current instance supports writing, and the property to determine whether seeking is supported. + Use the property to determine whether the current instance supports writing, and the property to determine whether seeking is supported. ]]> @@ -3264,7 +3264,7 @@ This member is an explicit interface member implementation. It can be used only property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. + Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged. @@ -3328,7 +3328,7 @@ This member is an explicit interface member implementation. It can be used only property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. + Use the property to determine whether the current instance supports writing. Use the method to write asynchronously to the current stream. If the write operation is successful, the position within the stream advances by the number of bytes written. If an exception occurs, the position within the stream remains unchanged. @@ -3406,9 +3406,9 @@ This member is an explicit interface member implementation. It can be used only ## Remarks The method enables you to perform resource-intensive I/O 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - 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 operation is canceled before it completes, the returned task contains the value for the property. For an example, see the overload. @@ -3480,7 +3480,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks The method enables you to perform resource-intensive I/O 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - Use the property to determine whether the current instance supports writing. + Use the property to determine whether the current instance supports writing. 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 . @@ -3567,9 +3567,9 @@ This member is an explicit interface member implementation. It can be used only ## Remarks The method enables you to perform resource-intensive I/O 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. The async methods are used in conjunction with the `async` and `await` keywords in Visual Basic and C#. - 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 operation is canceled before it completes, the returned task contains the value for the property. For an example, see the overload. @@ -3641,7 +3641,7 @@ This member is an explicit interface member implementation. It can be used only property to determine whether the current instance supports writing. + Use the property to determine whether the current instance supports writing. ]]> diff --git a/xml/System.IO/StreamReader.xml b/xml/System.IO/StreamReader.xml index 263d86e71f6..9bf8eabaacc 100644 --- a/xml/System.IO/StreamReader.xml +++ b/xml/System.IO/StreamReader.xml @@ -96,7 +96,7 @@ > [!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. - defaults to UTF-8 encoding unless specified otherwise, instead of defaulting to the ANSI code page for the current system. UTF-8 handles Unicode characters correctly and provides consistent results on localized versions of the operating system. If you get the current character encoding using the property, the value is not reliable until after the first method, since encoding auto detection is not done until the first call to a method. + defaults to UTF-8 encoding unless specified otherwise, instead of defaulting to the ANSI code page for the current system. UTF-8 handles Unicode characters correctly and provides consistent results on localized versions of the operating system. If you get the current character encoding using the property, the value is not reliable until after the first method, since encoding auto detection is not done until the first call to a method. By default, a is not thread safe. See for a thread-safe wrapper. @@ -194,7 +194,7 @@ , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. + This constructor initializes the encoding to , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. The object calls on the provided object when is called. @@ -364,7 +364,7 @@ , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. + This constructor initializes the encoding to , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. See the method for more information. @@ -539,7 +539,7 @@ , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. + This constructor initializes the encoding to , the property using the `stream` parameter, and the internal buffer size to 1024 bytes. The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -792,7 +792,7 @@ property using the `stream` parameter, and the internal buffer size to 1024 bytes. + This constructor initializes the encoding as specified by the `encoding` parameter, the property using the `stream` parameter, and the internal buffer size to 1024 bytes. The `detectEncodingFromByteOrderMarks` parameter detects the encoding by looking at the first four bytes of the stream. It automatically recognizes UTF-8, little-endian UTF-16, big-endian UTF-16, little-endian UTF-32, and big-endian UTF-32 text if the file starts with the appropriate byte order marks. Otherwise, the user-provided encoding is used. See the method for more information. diff --git a/xml/System.IO/StreamWriter.xml b/xml/System.IO/StreamWriter.xml index ba4e156b0f9..a212ca58ba7 100644 --- a/xml/System.IO/StreamWriter.xml +++ b/xml/System.IO/StreamWriter.xml @@ -96,7 +96,7 @@ > [!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. - defaults to using an instance of unless specified otherwise. This instance of `UTF8Encoding` is constructed without a byte order mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as or . + defaults to using an instance of unless specified otherwise. This instance of `UTF8Encoding` is constructed without a byte order mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as or . By default, a is not thread safe. See for a thread-safe wrapper. @@ -191,7 +191,7 @@ with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The property is initialized using the `stream` parameter. The position of the stream is not reset. + This constructor creates a with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The property is initialized using the `stream` parameter. The position of the stream is not reset. The object calls on the provided object when is called. @@ -274,7 +274,7 @@ with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . + This constructor creates a with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. If the file exists, it is overwritten; otherwise, a new file is created. @@ -382,7 +382,7 @@ property using the encoding parameter, and the property using the stream parameter. The position of the stream is not reset. For additional information, see . + This constructor initializes the property using the encoding parameter, and the property using the stream parameter. The position of the stream is not reset. For additional information, see . The object calls on the provided object when is called. @@ -469,7 +469,7 @@ with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . + This constructor creates a with UTF-8 encoding without a Byte-Order Mark (BOM), so its method returns an empty byte array. The default UTF-8 encoding for this constructor throws an exception on invalid bytes. This behavior is different from the behavior provided by the encoding object in the property. To specify a BOM and determine whether an exception is thrown on invalid bytes, use a constructor that accepts an encoding object as a parameter, such as . The `path` parameter can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -627,7 +627,7 @@ property using the `encoding` parameter, and the property using the `stream` parameter. The position of the stream is not reset. For additional information, see . + This constructor initializes the property using the `encoding` parameter, and the property using the `stream` parameter. The position of the stream is not reset. For additional information, see . The object calls on the provided object when is called. @@ -726,7 +726,7 @@ property using the encoding parameter. For additional information, see . + This constructor initializes the property using the encoding parameter. For additional information, see . `path` can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -893,7 +893,7 @@ ## Remarks Unless you set the `leaveOpen` parameter to `true`, the object calls on the provided object when is called. - This constructor initializes the property by using the `encoding` parameter, and initializes the property by using the `stream` parameter. The position of the stream is not reset. For additional information, see the property. + This constructor initializes the property by using the `encoding` parameter, and initializes the property by using the `stream` parameter. The position of the stream is not reset. For additional information, see the property. > [!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. @@ -986,7 +986,7 @@ property using the encoding parameter. For additional information, see . + This constructor initializes the property using the encoding parameter. For additional information, see . `path` can be a file name, including a file on a Universal Naming Convention (UNC) share. @@ -3264,7 +3264,7 @@ See property. + The line terminator is defined by the property. ]]> @@ -3332,7 +3332,7 @@ See property. + The line terminator is defined by the property. @@ -3416,7 +3416,7 @@ See property. + The line terminator is defined by 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 . @@ -3558,7 +3558,7 @@ The line terminator is defined by the fi property. + The line terminator is defined by the property. diff --git a/xml/System.IO/StringWriter.xml b/xml/System.IO/StringWriter.xml index 3ac3181f17a..ee1ded5af89 100644 --- a/xml/System.IO/StringWriter.xml +++ b/xml/System.IO/StringWriter.xml @@ -114,7 +114,7 @@ ## Examples The following code example demonstrates the creation of a continuous paragraph from a group of double-spaced sentences, and then the conversion of the paragraph back to the original text. - + :::code language="csharp" source="~/snippets/csharp/System.IO/StringReader/.ctor/stringrw.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.IO/StringReader/.ctor/stringrw.vb" id="Snippet1"::: @@ -1857,7 +1857,7 @@ This method stores in the task it returns all non-usage exceptions that the meth ## Remarks -The line terminator is defined by the property. +The line terminator is defined by the property. ## Examples @@ -1941,7 +1941,7 @@ The following example shows how to write characters by using the property. +The line terminator is defined by the property. ## Examples @@ -2128,7 +2128,7 @@ The following example shows how to write a string by using the property. +The line terminator is defined by the property. ## Examples diff --git a/xml/System.IO/TextReader.xml b/xml/System.IO/TextReader.xml index 4c079e56b53..ddec35f6903 100644 --- a/xml/System.IO/TextReader.xml +++ b/xml/System.IO/TextReader.xml @@ -1276,7 +1276,7 @@ ## Remarks The class is an abstract class. Therefore, you do not instantiate it in your code. For an example of using the method, see the method. - If the current represents the standard input stream returned by the property, the method executes synchronously rather than asynchronously. + If the current represents the standard input stream returned by the property, the method executes synchronously rather than asynchronously. 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 . diff --git a/xml/System.IO/TextWriter.xml b/xml/System.IO/TextWriter.xml index 0a1a3272b58..b71307a1658 100644 --- a/xml/System.IO/TextWriter.xml +++ b/xml/System.IO/TextWriter.xml @@ -198,7 +198,7 @@ property. When the property is `null`, the culture of the current thread is used for formatting. + Use this constructor overload when you do not want to provide a value for the property. When the property is `null`, the culture of the current thread is used for formatting. Use this constructor for derived classes. @@ -267,7 +267,7 @@ property. The value of the property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property is `null`, the culture of the current thread is used for formatting. + Use this constructor overload to provide a value for the property. The value of the property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property is `null`, the culture of the current thread is used for formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -332,7 +332,7 @@ ## Remarks This implementation of `Close` calls the method and passes it a `true` value. - Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting the property 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 be encoded only after the encoder receives the adjacent character or characters. + Flushing the stream will not flush its underlying encoder unless you explicitly call or `Close`. Setting the property 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 be encoded only after the encoder receives the adjacent character or characters. > [!NOTE] > In derived classes, do not override the method. Instead, override the method to add code for releasing resources. @@ -937,7 +937,7 @@ property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property contains `null`, the culture of the current thread is used for formatting. + The value of the property specifies the culture-specific formatting that is used when you call the and methods. If you do not want to provide a format provider, you create an instance by using the constructor, which sets the property to `null`. When the property contains `null`, the culture of the current thread is used for formatting. For an example of creating a file and writing text to a file, see [How to: Write Text to a File](/dotnet/standard/io/how-to-write-text-to-a-file). For an example of reading text from a file, see [How to: Read Text from a File](/dotnet/standard/io/how-to-read-text-from-a-file). For an example of reading from and writing to a binary file, see [How to: Read and Write to a Newly Created Data File](/dotnet/standard/io/how-to-read-and-write-to-a-newly-created-data-file). @@ -1491,7 +1491,7 @@ This member is an explicit interface member implementation. It can be used only property, if not `null`, specifies the culture-specific formatting. + The property, if not `null`, specifies the culture-specific formatting. ]]> @@ -1560,7 +1560,7 @@ This member is an explicit interface member implementation. It can be used only method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1631,7 +1631,7 @@ This member is an explicit interface member implementation. It can be used only method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1702,7 +1702,7 @@ This member is an explicit interface member implementation. It can be used only method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1775,7 +1775,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This overload is equivalent to the overload. - If the specified object is `null`, no action is taken and no exception is thrown. Otherwise, the object's `ToString` method is called to produce the string representation, and the resulting string is then written to the output stream. The property, if not `null`, specifies the culture-specific formatting. + If the specified object is `null`, no action is taken and no exception is thrown. Otherwise, the object's `ToString` method is called to produce the string representation, and the resulting string is then written to the output stream. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -1901,7 +1901,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2141,7 +2141,7 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -2218,7 +2218,7 @@ This method is equivalent to `Write(stringBuilder.ToString())`, but it uses the method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). @@ -3752,7 +3752,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). The line terminator is defined by the field. @@ -3823,7 +3823,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). The line terminator is defined by the field. @@ -3894,7 +3894,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -3967,7 +3967,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -4042,7 +4042,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks -This overload is equivalent to the overload. The property, if not `null`, specifies the culture-specific formatting. +This overload is equivalent to the overload. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -4173,7 +4173,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo ## Remarks - The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). + The property, if not `null`, specifies the culture-specific formatting. For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/common-i-o-tasks). The line terminator is defined by the field. @@ -4424,7 +4424,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. @@ -4503,7 +4503,7 @@ For a list of common I/O tasks, see [Common I/O Tasks](/dotnet/standard/io/commo method. The property, if not `null`, specifies the culture-specific formatting. + The text representation of the specified value is produced by calling the method. The property, if not `null`, specifies the culture-specific formatting. The line terminator is defined by the field. diff --git a/xml/System.IO/UnmanagedMemoryStream.xml b/xml/System.IO/UnmanagedMemoryStream.xml index b2f0fe70fa5..7d4ec2e0718 100644 --- a/xml/System.IO/UnmanagedMemoryStream.xml +++ b/xml/System.IO/UnmanagedMemoryStream.xml @@ -214,7 +214,7 @@ class, and by default sets the property to `false` and the property to `true`. The property is set to the value of the `length` parameter and cannot be changed. + This constructor creates a new instance of the class, and by default sets the property to `false` and the property to `true`. The property is set to the value of the `length` parameter and cannot be changed. @@ -507,7 +507,7 @@ ## Examples - The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to display the contents to the console. + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to display the contents to the console. :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: @@ -640,7 +640,7 @@ ## Examples - The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to write the data to the stream. + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to write the data to the stream. :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: @@ -1265,7 +1265,7 @@ This method is equivalent to the property to zero, and then call this property. + To return a pointer to the entire stream, set the property to zero, and then call this property. ]]> @@ -1605,7 +1605,7 @@ This method is equivalent to the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to read and display the contents to the console. + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to read and display the contents to the console. :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: @@ -2100,7 +2100,7 @@ If an exception occurs during the write operation, it will be set as the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to write the data to the stream. + The following code example demonstrates how to read from and write to unmanaged memory using the class. A block of unmanaged memory is allocated and de-allocated using the class. In this example, an object is passed to a method that checks the property before attempting to write the data to the stream. :::code language="csharp" source="~/snippets/csharp/System.IO/UnmanagedMemoryStream/.ctor/program.cs" id="Snippet00"::: diff --git a/xml/System.IO/WaitForChangedResult.xml b/xml/System.IO/WaitForChangedResult.xml index 67f7f604eb1..966da2f479e 100644 --- a/xml/System.IO/WaitForChangedResult.xml +++ b/xml/System.IO/WaitForChangedResult.xml @@ -53,13 +53,13 @@ Contains information on the change that occurred. - synchronously by having it wait for a specific file change notification to occur. - - :::code language="vb" source="~/snippets/visualbasic/System.IO/WaitForChangedResult/Overview/WaitforChangedResult.vb" id="Snippet1"::: - + synchronously by having it wait for a specific file change notification to occur. + + :::code language="vb" source="~/snippets/visualbasic/System.IO/WaitForChangedResult/Overview/WaitforChangedResult.vb" id="Snippet1"::: + ]]> @@ -187,13 +187,13 @@ Gets or sets the name of the file or directory that changed. The name of the file or directory that changed. - property. This code example is part of a larger example provided for the structure. - - :::code language="vb" source="~/snippets/visualbasic/System.IO/WaitForChangedResult/Overview/WaitforChangedResult.vb" id="Snippet2"::: - + property. This code example is part of a larger example provided for the structure. + + :::code language="vb" source="~/snippets/visualbasic/System.IO/WaitForChangedResult/Overview/WaitforChangedResult.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.Linq.Expressions/BinaryExpression.xml b/xml/System.Linq.Expressions/BinaryExpression.xml index e094a3af617..165f93fdfc1 100644 --- a/xml/System.Linq.Expressions/BinaryExpression.xml +++ b/xml/System.Linq.Expressions/BinaryExpression.xml @@ -227,7 +227,7 @@ property is `null` for any whose property is not . + The property is `null` for any whose property is not . ]]> @@ -443,7 +443,7 @@ represents an operation that uses a predefined operator, the property is `null`. + If a represents an operation that uses a predefined operator, the property is `null`. ]]> diff --git a/xml/System.Linq.Expressions/DynamicExpression.xml b/xml/System.Linq.Expressions/DynamicExpression.xml index 84cfd45eb75..106f6267d91 100644 --- a/xml/System.Linq.Expressions/DynamicExpression.xml +++ b/xml/System.Linq.Expressions/DynamicExpression.xml @@ -134,11 +134,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 . + ]]> @@ -361,11 +361,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to , and has the and set to the specified values. - property of the result is inferred from the types of the arguments and the specified return type. - + property of the result is inferred from the types of the arguments and the specified return type. + ]]> @@ -426,11 +426,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to , and has the and set to the specified values. - property of the result is inferred from the types of the arguments and the specified return type. - + property of the result is inferred from the types of the arguments and the specified return type. + ]]> @@ -498,11 +498,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to , and has the and set to the specified values. - property of the result is inferred from the types of the arguments and the specified return type. - + property of the result is inferred from the types of the arguments and the specified return type. + ]]> @@ -565,11 +565,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to , and has the and set to the specified values. - property of the result is inferred from the types of the arguments and the specified return type. - + property of the result is inferred from the types of the arguments and the specified return type. + ]]> @@ -634,11 +634,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to , and has the and set to the specified values. - property of the result is inferred from the types of the arguments and the specified return type. - + property of the result is inferred from the types of the arguments and the specified return type. + ]]> @@ -705,11 +705,11 @@ Creates a that represents a dynamic operation bound by the provided . A that has equal to , and has the and set to the specified values. - property of the result is inferred from the types of the arguments and the specified return type. - + property of the result is inferred from the types of the arguments and the specified return type. + ]]> diff --git a/xml/System.Linq.Expressions/Expression.xml b/xml/System.Linq.Expressions/Expression.xml index 9fa8bd30632..473ff427daf 100644 --- a/xml/System.Linq.Expressions/Expression.xml +++ b/xml/System.Linq.Expressions/Expression.xml @@ -862,14 +862,14 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the addition operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the addition operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -958,7 +958,7 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -967,7 +967,7 @@ The following code example shows how to create an expression that adds two integ - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the addition operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the addition operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -1067,14 +1067,14 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. @@ -1171,7 +1171,7 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -1180,7 +1180,7 @@ The following code example shows how to create an expression that adds two integ - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. @@ -1280,14 +1280,14 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. > [!NOTE] > The conditional `AND` operator cannot be overloaded in C# or Visual Basic. However, the conditional `AND` operator is evaluated by using the bitwise `AND` operator. Thus, a user-defined overload of the bitwise `AND` operator can be the implementing method for this node type. @@ -1393,7 +1393,7 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -1402,7 +1402,7 @@ The following code example shows how to create an expression that adds two integ - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `AND` operator, the that represents that method is the implementing method. > [!NOTE] > The conditional `AND` operator cannot be overloaded in C# or Visual Basic. However, the conditional `AND` operator is evaluated by using the bitwise `AND` operator. Thus, a user-defined overload of the bitwise `AND` operator can be the implementing method for this node type. @@ -1867,11 +1867,11 @@ The following code example shows how to create an expression that adds two integ equal to . The property of `array` must represent an array type whose rank matches the number of elements in `indexes`. + Each element of `indexes` must have equal to . The property of `array` must represent an array type whose rank matches the number of elements in `indexes`. - If the rank of `array`.Type is 1, this method returns a . The property is set to `array` and the property is set to the single element of `indexes`. The property of the represents the element type of `array`.Type. + If the rank of `array`.Type is 1, this method returns a . The property is set to `array` and the property is set to the single element of `indexes`. The property of the represents the element type of `array`.Type. - If the rank of `array`.Type is more than one, this method returns a . The property is set to the that describes the public instance method `Get` on the type represented by the property of `array`. + If the rank of `array`.Type is more than one, this method returns a . The property is set to the that describes the public instance method `Get` on the type represented by the property of `array`. @@ -1950,7 +1950,7 @@ The following code example shows how to create an expression that adds two integ ## Remarks `index` must represent an index of type . - The property of the resulting is `null`, and both and are set to `false`. The property is equal to the element type of `array`.Type. The property is `null`. + The property of the resulting is `null`, and both and are set to `false`. The property is equal to the element type of `array`.Type. The property is `null`. ]]> @@ -2026,11 +2026,11 @@ The following code example shows how to create an expression that adds two integ equal to . The property of `array` must represent an array type whose rank matches the number of elements in `indexes`. + Each element of `indexes` must have equal to . The property of `array` must represent an array type whose rank matches the number of elements in `indexes`. - If the rank of `array`.Type is 1, this method returns a . The property is set to `array` and the property is set to the single element of `indexes`. The property of the represents the element type of `array`.Type. + If the rank of `array`.Type is 1, this method returns a . The property is set to `array` and the property is set to the single element of `indexes`. The property of the represents the element type of `array`.Type. - If the rank of `array`.Type is more than one, this method returns a . The property is set to the that describes the public instance method `Get` on the type represented by the property of `array`. + If the rank of `array`.Type is more than one, this method returns a . The property is set to the that describes the public instance method `Get` on the type represented by the property of `array`. @@ -2105,9 +2105,9 @@ The following code example shows how to create an expression that adds two integ property of `array` must represent an array type. + The property of `array` must represent an array type. - The property of the resulting is equal to . The property is `null`, and both and are set to `false`. + The property of the resulting is equal to . The property is `null`, and both and are set to `false`. ]]> @@ -2244,7 +2244,7 @@ The following code example shows how to create an expression that adds two integ property of `expression` must be assignable to the type represented by the or property of `member`. + The property of `expression` must be assignable to the type represented by the or property of `member`. ]]> @@ -2319,7 +2319,7 @@ The following code example shows how to create an expression that adds two integ property of `expression` must be assignable to the type represented by the property of the property accessed in `propertyAccessor`. + The property of `expression` must be assignable to the type represented by the property of the property accessed in `propertyAccessor`. ]]> @@ -3400,9 +3400,9 @@ The following code example shows how to create an expression that adds two integ ## Remarks To represent a call to a `static` (`Shared` in Visual Basic) method, pass in `null` for the `instance` parameter when you call this method. - If `method` represents an instance method, the property of `instance` must be assignable to the declaring type of the method represented by `method`. + If `method` represents an instance method, the property of `instance` must be assignable to the declaring type of the method represented by `method`. - The property of the resulting is empty. The property is equal to the return type of the method represented by `method`. + The property of the resulting is empty. The property is equal to the return type of the method represented by `method`. @@ -3620,11 +3620,11 @@ The following code example shows how to create an expression that adds two integ If `arguments` is not `null`, it must have the same number of elements as the number of parameters for the method represented by `method`. Each element in `arguments` must not be `null` and must be assignable to the corresponding parameter of `method`, possibly after *quoting*. > [!NOTE] -> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. +> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. - The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. + The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. - The property of the resulting is equal to the return type of the method represented by `method`. The property is `null`. + The property of the resulting is equal to the return type of the method represented by `method`. The property is `null`. ]]> @@ -3707,16 +3707,16 @@ The following code example shows how to create an expression that adds two integ ## Remarks To represent a call to a `static` (`Shared` in Visual Basic) method, pass in `null` for the `instance` parameter when you call this method, or call instead. - If `method` represents an instance method, the property of `instance` must be assignable to the declaring type of the method represented by `method`. + If `method` represents an instance method, the property of `instance` must be assignable to the declaring type of the method represented by `method`. If `arguments` is not `null`, it must have the same number of elements as the number of parameters for the method represented by `method`. Each element in `arguments` must not be `null` and must be assignable to the corresponding parameter of `method`, possibly after *quoting*. > [!NOTE] -> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. +> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. - The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. + The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. - The property of the resulting is equal to the return type of the method represented by `method`. + The property of the resulting is equal to the return type of the method represented by `method`. ]]> @@ -3812,16 +3812,16 @@ The following code example shows how to create an expression that adds two integ ## Remarks To represent a call to a `static` (`Shared` in Visual Basic) method, pass in `null` for the `instance` parameter when you call this method, or call instead. - If `method` represents an instance method, the property of `instance` must be assignable to the declaring type of the method represented by `method`. + If `method` represents an instance method, the property of `instance` must be assignable to the declaring type of the method represented by `method`. If `arguments` is not `null`, it must have the same number of elements as the number of parameters for the method represented by `method`. Each element in `arguments` must not be `null` and must be assignable to the corresponding parameter of `method`, possibly after *quoting*. > [!NOTE] -> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. +> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. - The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. + The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments`, some of which may be quoted. - The property of the resulting is equal to the return type of the method represented by `method`. + The property of the resulting is equal to the return type of the method represented by `method`. ]]> @@ -4055,7 +4055,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is equal to the return type of the method denoted by `methodName`. + The property of the resulting is equal to the return type of the method denoted by `methodName`. ]]> @@ -4214,7 +4214,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is equal to the return type of the method denoted by `methodName`. The property is `null`. + The property of the resulting is equal to the return type of the method denoted by `methodName`. The property is `null`. ]]> @@ -4813,7 +4813,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is `null` and both and are set to `false`. The property is equal to the result type of the coalescing operation. The property is `null`. + The property of the resulting is `null` and both and are set to `false`. The property is equal to the result type of the coalescing operation. The property is `null`. #### Result Type The following rules determine the result type: @@ -4895,9 +4895,9 @@ The following code example shows how to create an expression that adds two integ property of the resulting is `null` and both and are set to `false`. + The property of the resulting is `null` and both and are set to `false`. - The property of the resulting is equal to the result type of the coalescing operation. + The property of the resulting is equal to the result type of the coalescing operation. The following rules determine the result type: @@ -4993,7 +4993,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is equal to the property of `ifTrue`. + The property of the resulting is equal to the property of `ifTrue`. @@ -5146,7 +5146,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is equal to the type of `value`. If `value` is `null`, is equal to . + The property of the resulting is equal to the type of `value`. If `value` is `null`, is equal to . To represent `null`, you can also use the method, with which you can explicitly specify the type. @@ -5432,7 +5432,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. + The property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. #### Implementing Method The following rules determine the implementing method for the operation: @@ -5534,7 +5534,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. + The property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. #### Implementing Method The following rules determine the implementing method for the operation: @@ -5653,7 +5653,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. + The property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. #### Implementing Method The following rules determine the implementing method for the operation: @@ -5747,7 +5747,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. + The property of the resulting is set to the implementing method. The property is `false`. If the node is lifted, is `true`. Otherwise, it is `false`. #### Implementing Method The following rules determine the implementing method for the operation: @@ -6122,14 +6122,14 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the division operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the division operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -6226,7 +6226,7 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -6235,7 +6235,7 @@ The following code example shows how to create an expression that adds two integ - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the division operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the division operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -6531,7 +6531,7 @@ The following code example shows how to create an expression that adds two integ property of the result will be inferred from the types of the arguments and the specified return type. + The property of the result will be inferred from the types of the arguments and the specified return type. ]]> @@ -6592,7 +6592,7 @@ The following code example shows how to create an expression that adds two integ property of the result will be inferred from the types of the arguments and the specified return type. + The property of the result will be inferred from the types of the arguments and the specified return type. ]]> @@ -6660,7 +6660,7 @@ The following code example shows how to create an expression that adds two integ property of the result will be inferred from the types of the arguments and the specified return type. + The property of the result will be inferred from the types of the arguments and the specified return type. ]]> @@ -6723,7 +6723,7 @@ The following code example shows how to create an expression that adds two integ property of the result will be inferred from the types of the arguments and the specified return type. + The property of the result will be inferred from the types of the arguments and the specified return type. ]]> @@ -6788,7 +6788,7 @@ The following code example shows how to create an expression that adds two integ property of the result will be inferred from the types of the arguments and the specified return type. + The property of the result will be inferred from the types of the arguments and the specified return type. ]]> @@ -6855,7 +6855,7 @@ The following code example shows how to create an expression that adds two integ property of the result will be inferred from the types of the arguments and the specified return type. + The property of the result will be inferred from the types of the arguments and the specified return type. ]]> @@ -6924,10 +6924,10 @@ The following code example shows how to create an expression that adds two integ property of each element in `arguments` must be assignable to the type of the corresponding parameter of the add method, possibly after *quoting*. + The `addMethod` parameter must represent an instance method named "Add" (case insensitive). The add method must have the same number of parameters as the number of elements in `arguments`. The property of each element in `arguments` must be assignable to the type of the corresponding parameter of the add method, possibly after *quoting*. > [!NOTE] -> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. +> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. @@ -7020,10 +7020,10 @@ The following code example shows how to create an expression that adds two integ property of each element in `arguments` must be assignable to the type of the corresponding parameter of the add method, possibly after *quoting*. + The `addMethod` parameter must represent an instance method named "Add" (case insensitive). The add method must have the same number of parameters as the number of elements in `arguments`. The property of each element in `arguments` must be assignable to the type of the corresponding parameter of the add method, possibly after *quoting*. > [!NOTE] -> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. +> An element will be quoted only if the corresponding method parameter is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. @@ -7180,12 +7180,12 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The following information describes the implementing method, the node type, and whether a node is lifted. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the equality operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the equality operator, the that represents that method is the implementing method. - Otherwise, the implementing method is `null`. @@ -7285,14 +7285,14 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The following information describes the implementing method, the node type, and whether a node is lifted. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the equality operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the equality operator, the that represents that method is the implementing method. - Otherwise, the implementing method is `null`. @@ -7392,14 +7392,14 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the `XOR` operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the `XOR` operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. @@ -7496,7 +7496,7 @@ The following code example shows how to create an expression that adds two integ has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -7505,7 +7505,7 @@ The following code example shows how to create an expression that adds two integ - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the `XOR` operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the `XOR` operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. @@ -7807,7 +7807,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is equal to the property of `field`. + The property of the resulting is equal to the property of `field`. ]]> @@ -7878,7 +7878,7 @@ The following code example shows how to create an expression that adds two integ property of the resulting is equal to the property of the that represents the field denoted by `fieldName`. + The property of the resulting is equal to the property of the that represents the field denoted by `fieldName`. This method searches `expression`.Type and its base types for a field that has the name `fieldName`. Public fields are given preference over non-public fields. If a matching field is found, this method passes `expression` and the that represents that field to . @@ -8505,14 +8505,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the "greater than" operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the "greater than" operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -8612,7 +8612,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -8621,7 +8621,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "greater than" operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "greater than" operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -8721,14 +8721,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the "greater than or equal" operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the "greater than or equal" operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -8828,7 +8828,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -8837,7 +8837,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "greater than or equal" operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "greater than or equal" operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -9203,12 +9203,12 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting represents the return type of the delegate that is represented by `expression`.Type. + The property of the resulting represents the return type of the delegate that is represented by `expression`.Type. - The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments` except that some of these objects may be *quoted*. + The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments` except that some of these objects may be *quoted*. > [!NOTE] -> An element will be quoted only if the corresponding parameter of the delegate represented by `expression` is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. +> An element will be quoted only if the corresponding parameter of the delegate represented by `expression` is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. @@ -9295,12 +9295,12 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting represents the return type of the delegate that is represented by `expression`.Type. + The property of the resulting represents the return type of the delegate that is represented by `expression`.Type. - The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments` except that some of these objects may be *quoted*. + The property of the resulting is empty if `arguments` is `null`. Otherwise, it contains the same elements as `arguments` except that some of these objects may be *quoted*. > [!NOTE] -> An element will be quoted only if the corresponding parameter of the delegate represented by `expression` is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. +> An element will be quoted only if the corresponding parameter of the delegate represented by `expression` is of type . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `arguments`. @@ -10372,7 +10372,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V The elements of `parameters` must be reference equal to the parameter expressions in `body`. - The property of the resulting object is equal to `delegateType`. If `parameters` is `null`, the property of the resulting object is an empty collection. + The property of the resulting object is equal to `delegateType`. If `parameters` is `null`, the property of the resulting object is an empty collection. @@ -10483,7 +10483,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V The elements of `parameters` must be reference equal to the parameter expressions in `body`. - The property of the resulting object is equal to `delegateType`. If `parameters` is `null`, the property of the resulting object is an empty collection. + The property of the resulting object is equal to `delegateType`. If `parameters` is `null`, the property of the resulting object is an empty collection. ]]> @@ -10939,7 +10939,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V The elements of `parameters` must be reference equal to the parameter expressions in `body`. - The property of the resulting object represents the type `TDelegate`. If `parameters` is `null`, the property of the resulting object is an empty collection. + The property of the resulting object represents the type `TDelegate`. If `parameters` is `null`, the property of the resulting object is an empty collection. ]]> @@ -11043,7 +11043,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V The elements of `parameters` must be reference equal to the parameter expressions in`body`. - The property of the resulting object represents the type `TDelegate`. If `parameters` is `null`, the property of the resulting object is an empty collection. + The property of the resulting object represents the type `TDelegate`. If `parameters` is `null`, the property of the resulting object is an empty collection. ]]> @@ -11450,14 +11450,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the selected implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the left-shift operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the left-shift operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. @@ -11546,7 +11546,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -11555,7 +11555,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the left-shift operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the left-shift operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. @@ -11855,14 +11855,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The implementing method for the operation is chosen based on the following rules: -- If the property of either `left` or `right` represents a user-defined type that overloads the "less than" operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the "less than" operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -11962,7 +11962,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -11971,7 +11971,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "less than" operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "less than" operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -12071,14 +12071,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the "less than or equal" operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the "less than or equal" operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -12178,7 +12178,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -12187,7 +12187,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "less than or equal" operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the "less than or equal" operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -12567,9 +12567,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of `newExpression` must represent a type that implements . + The property of `newExpression` must represent a type that implements . - The property of the resulting is equal to `newExpression`.Type. + The property of the resulting is equal to `newExpression`.Type. @@ -12652,13 +12652,13 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of `newExpression` must represent a type that implements . + The property of `newExpression` must represent a type that implements . - In order to use this overload of , `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. The type of the argument must be assignable from the type represented by the property of the first element of `initializers`. + In order to use this overload of , `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. The type of the argument must be assignable from the type represented by the property of the first element of `initializers`. - The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of represents the add method that was discovered on `newExpression`.Type or its base type. + The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of represents the add method that was discovered on `newExpression`.Type or its base type. - The property of the resulting is equal to `newExpression`.Type. + The property of the resulting is equal to `newExpression`.Type. ]]> @@ -12743,9 +12743,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of `newExpression` must represent a type that implements . + The property of `newExpression` must represent a type that implements . - The property of the resulting is equal to `newExpression`.Type. + The property of the resulting is equal to `newExpression`.Type. @@ -12835,13 +12835,13 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of `newExpression` must represent a type that implements . + The property of `newExpression` must represent a type that implements . - In order to use this overload of , `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. The type of the argument must be assignable from the type represented by the property of the first element of `initializers`. + In order to use this overload of , `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. The type of the argument must be assignable from the type represented by the property of the first element of `initializers`. - The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of represents the add method that was discovered on `newExpression`.Type or its base type. + The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of represents the add method that was discovered on `newExpression`.Type or its base type. - The property of the resulting is equal to `newExpression`.Type. + The property of the resulting is equal to `newExpression`.Type. ]]> @@ -12939,13 +12939,13 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of `newExpression` must represent a type that implements . + The property of `newExpression` must represent a type that implements . - If `addMethod` is `null`, `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. If `addMethod` is not `null`, it must represent an instance method named "Add" (case insensitive) that has exactly one parameter. The type represented by the property of each element of `initializers` must be assignable to the argument type of the add method. + If `addMethod` is `null`, `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. If `addMethod` is not `null`, it must represent an instance method named "Add" (case insensitive) that has exactly one parameter. The type represented by the property of each element of `initializers` must be assignable to the argument type of the add method. - The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of is equal to `addMethod`. + The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of is equal to `addMethod`. - The property of the resulting is equal to `newExpression`.Type. + The property of the resulting is equal to `newExpression`.Type. ]]> @@ -13047,13 +13047,13 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of `newExpression` must represent a type that implements . + The property of `newExpression` must represent a type that implements . - If `addMethod` is `null`, `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. If `addMethod` is not `null`, it must represent an instance method named "Add" (case insensitive) that has exactly one parameter. The type represented by the property of each element of `initializers` must be assignable to the argument type of the add method. + If `addMethod` is `null`, `newExpression`.Type or its base type must declare a single method named "Add" (case insensitive) that takes exactly one argument. If `addMethod` is not `null`, it must represent an instance method named "Add" (case insensitive) that has exactly one parameter. The type represented by the property of each element of `initializers` must be assignable to the argument type of the add method. - The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of is equal to `addMethod`. + The property of the returned contains one element of type for each element of `initializers`. The property of each element of is a singleton collection that contains the corresponding element of `initializers`. The property of each element of is equal to `addMethod`. - The property of the resulting is equal to `newExpression`.Type. + The property of the resulting is equal to `newExpression`.Type. ]]> @@ -14745,7 +14745,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is equal to the property of `newExpression`. + The property of the resulting is equal to the property of `newExpression`. @@ -14820,7 +14820,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is equal to the property of `newExpression`. + The property of the resulting is equal to the property of `newExpression`. @@ -14906,14 +14906,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the selected implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the modulus operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the modulus operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -15002,7 +15002,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -15011,7 +15011,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the modulus operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the modulus operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -15311,14 +15311,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the selected implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -15415,7 +15415,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -15424,7 +15424,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -15924,14 +15924,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the selected implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -16020,7 +16020,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -16029,7 +16029,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the multiplication operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -16127,7 +16127,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + The property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. #### Implementing Method The following rules determine the implementing method for the operation: @@ -16223,7 +16223,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + The property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. #### Implementing Method The following rules determine the implementing method for the operation: @@ -16328,7 +16328,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + The property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. #### Implementing Method The following rules determine the implementing method for the operation: @@ -16416,7 +16416,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + The property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. #### Implementing Method The following rules determine the implementing method for the operation: @@ -16521,7 +16521,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V and properties of the resulting are empty collections. The property represents the declaring type of the constructor represented by `constructor`. + The and properties of the resulting are empty collections. The property represents the declaring type of the constructor represented by `constructor`. ]]> @@ -16588,7 +16588,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V ## Remarks The `type` parameter must represent a type that has a constructor without parameters. - The and properties of the resulting are empty collections. The property is equal to `type`. + The and properties of the resulting are empty collections. The property is equal to `type`. @@ -16664,9 +16664,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is an empty collection. + The `arguments` parameter must contain the same number of elements as the number of parameters for the constructor represented by `constructor`. If `arguments` is `null`, it is considered empty, and the property of the resulting is an empty collection. - The property of the resulting represents the declaring type of the constructor represented by `constructor`. The property is an empty collection. + The property of the resulting represents the declaring type of the constructor represented by `constructor`. The property is an empty collection. ]]> @@ -16746,9 +16746,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is an empty collection. + The `arguments` parameter must contain the same number of elements as the number of parameters for the constructor represented by `constructor`. If `arguments` is `null`, it is considered empty, and the property of the resulting is an empty collection. - The property of the resulting represents the declaring type of the constructor represented by `constructor`. The property is an empty collection. + The property of the resulting represents the declaring type of the constructor represented by `constructor`. The property is an empty collection. ]]> @@ -16839,11 +16839,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is an empty collection. + The `arguments` parameter must contain the same number of elements as the number of parameters for the constructor represented by `constructor`. If `arguments` is `null`, it is considered empty, and the property of the resulting is an empty collection. - If `members` is `null`, the property of the resulting is an empty collection. If `members` is not `null`, it must have the same number of elements as `arguments` and each element must not be `null`. Each element of `members` must be a , or that represents an instance member on the declaring type of the constructor represented by `constructor`. If it represents a property, the property must have a `get` accessor. The corresponding element of `arguments` for each element of `members` must have a property that represents a type that is assignable to the type of the member that the `members` element represents. + If `members` is `null`, the property of the resulting is an empty collection. If `members` is not `null`, it must have the same number of elements as `arguments` and each element must not be `null`. Each element of `members` must be a , or that represents an instance member on the declaring type of the constructor represented by `constructor`. If it represents a property, the property must have a `get` accessor. The corresponding element of `arguments` for each element of `members` must have a property that represents a type that is assignable to the type of the member that the `members` element represents. - The property of the resulting represents the declaring type of the constructor that `constructor` represents. + The property of the resulting represents the declaring type of the constructor that `constructor` represents. ]]> @@ -16950,11 +16950,11 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is an empty collection. + The `arguments` parameter must contain the same number of elements as the number of parameters for the constructor represented by `constructor`. If `arguments` is `null`, it is considered empty, and the property of the resulting is an empty collection. - If `members` is `null`, the property of the resulting is an empty collection. If `members` is not `null`, it must have the same number of elements as `arguments` and each element must not be `null`. Each element of `members` must be a , or that represents an instance member on the declaring type of the constructor represented by `constructor`. If it represents a property, the property must be able to retrieve the value of the associated field. The corresponding element of `arguments` for each element of `members` must have a property that represents a type that is assignable to the type of the member that the `members` element represents. + If `members` is `null`, the property of the resulting is an empty collection. If `members` is not `null`, it must have the same number of elements as `arguments` and each element must not be `null`. Each element of `members` must be a , or that represents an instance member on the declaring type of the constructor represented by `constructor`. If it represents a property, the property must be able to retrieve the value of the associated field. The corresponding element of `arguments` for each element of `members` must have a property that represents a type that is assignable to the type of the member that the `members` element represents. - The property of the resulting represents the declaring type of the constructor that `constructor` represents. + The property of the resulting represents the declaring type of the constructor that `constructor` represents. ]]> @@ -17052,9 +17052,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting represents an array type whose rank is equal to the length of `bounds` and whose element type is `type`. + The property of the resulting represents an array type whose rank is equal to the length of `bounds` and whose element type is `type`. - The property of each element of `bounds` must represent an integral type. + The property of each element of `bounds` must represent an integral type. @@ -17139,9 +17139,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting represents an array type whose rank is equal to the length of `bounds` and whose element type is `type`. + The property of the resulting represents an array type whose rank is equal to the length of `bounds` and whose element type is `type`. - The property of each element of `bounds` must represent an integral type. + The property of each element of `bounds` must represent an integral type. @@ -17231,12 +17231,12 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of each element of `initializers` must represent a type that is assignable to the type represented by `type`, possibly after it is *quoted*. + The property of each element of `initializers` must represent a type that is assignable to the type represented by `type`, possibly after it is *quoted*. > [!NOTE] -> An element will be quoted only if `type` is . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `initializers`. +> An element will be quoted only if `type` is . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `initializers`. - The property of the resulting represents an array type whose rank is 1 and whose element type is `type`. + The property of the resulting represents an array type whose rank is 1 and whose element type is `type`. @@ -17321,12 +17321,12 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of each element of `initializers` must represent a type that is assignable to the type represented by `type`, possibly after it is *quoted*. + The property of each element of `initializers` must represent a type that is assignable to the type represented by `type`, possibly after it is *quoted*. > [!NOTE] -> An element will be quoted only if `type` is . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `initializers`. +> An element will be quoted only if `type` is . Quoting means the element is wrapped in a node. The resulting node is a whose property is the element of `initializers`. - The property of the resulting represents an array type whose rank is 1 and whose element type is `type`. + The property of the resulting represents an array type whose rank is 1 and whose element type is `type`. @@ -17395,9 +17395,9 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property provides a more specialized description of an than just its derived type. For example, a can be used to represent many different kinds of binary expressions, such as a division operation or a "greater than" operation. The property would describe these binary expressions as and , respectively. + The property provides a more specialized description of an than just its derived type. For example, a can be used to represent many different kinds of binary expressions, such as a division operation or a "greater than" operation. The property would describe these binary expressions as and , respectively. - The static CLR type of the expression that the object represents is represented by the property. + The static CLR type of the expression that the object represents is represented by the property. ]]> @@ -17470,7 +17470,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. + The property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. #### Implementing Method The following rules determine the implementing method for the operation: @@ -17566,7 +17566,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. + The property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. #### Implementing Method The following rules determine the implementing method for the operation: @@ -17673,14 +17673,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true`. Otherwise, it is `false`. The property is always `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the inequality operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the inequality operator, the that represents that method is the implementing method. - Otherwise, the implementing method is `null`. @@ -17772,7 +17772,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the property is `true` and the property is equal to `liftToNull`. Otherwise, they are both `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -17781,7 +17781,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the inequality operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the inequality operator, the that represents that method is the implementing method. - Otherwise, the implementing method is `null`. @@ -18003,14 +18003,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. @@ -18107,7 +18107,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -18116,7 +18116,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are integral or Boolean types, the implementing method is `null`. @@ -18416,14 +18416,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. > [!NOTE] > The conditional `OR` operator cannot be overloaded in C# or Visual Basic. However, the conditional `OR` operator is evaluated by using the bitwise `OR` operator. Thus, a user-defined overload of the bitwise `OR` operator can be the implementing method for this node type. @@ -18529,7 +18529,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -18538,7 +18538,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the bitwise `OR` operator, the that represents that method is the implementing method. > [!NOTE] > The conditional `OR` operator cannot be overloaded in C# or Visual Basic. However, the conditional `OR` operator is evaluated by using the bitwise `OR` operator. Thus, a user-defined overload of the bitwise `OR` operator can be the implementing method for this node type. @@ -19038,14 +19038,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the exponentiation operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the exponentiation operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are both , the implementing method is . @@ -19131,7 +19131,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -19140,7 +19140,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the exponentiation operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the exponentiation operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are both , the implementing method is . @@ -19701,7 +19701,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is equal to the property of . + The property of the resulting is equal to the property of . If the method represented by `propertyAccessor` is `static` (`Shared` in Visual Basic), `expression` can be `null`. @@ -19780,7 +19780,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is equal to the property of . + The property of the resulting is equal to the property of . If the property represented by `property` is `static` (`Shared` in Visual Basic), `expression` can be `null`. @@ -19853,7 +19853,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is equal to the property of the that represents the property denoted by `propertyName`. + The property of the resulting is equal to the property of the that represents the property denoted by `propertyName`. This method searches `expression`.Type and its base types for a property that has the name `propertyName`. Public properties are given preference over non-public properties. If a matching property is found, this method passes `expression` and the that represents that property to . @@ -20200,7 +20200,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is equal to the or properties of the or , respectively, that represents the property or field denoted by `propertyOrFieldName`. + The property of the resulting is equal to the or properties of the or , respectively, that represents the property or field denoted by `propertyOrFieldName`. This method searches `expression`.Type and its base types for an instance property or field that has the name `propertyOrFieldName`. Static properties or fields are not supported. Public properties and fields are given preference over non-public properties and fields. Also, properties are given preference over fields. If a matching property or field is found, this method passes `expression` and the or that represents that property or field to or , respectively. @@ -20268,7 +20268,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting represents the constructed type , where the type argument is the type represented by `expression`.Type. The property is `null`. Both and are `false`. + The property of the resulting represents the constructed type , where the type argument is the type represented by `expression`.Type. The property is `null`. Both and are `false`. ]]> @@ -20943,14 +20943,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the selected implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the right-shift operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the right-shift operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. @@ -21039,7 +21039,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -21048,7 +21048,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the right-shift operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the right-shift operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type is an integral type (one of , , , , , , , , or the corresponding nullable types) and `right`.Type is , the implementing method is `null`. @@ -21461,14 +21461,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the selected implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -21565,7 +21565,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -21574,7 +21574,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -22074,14 +22074,14 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. #### Implementing Method The following rules determine the selected implementing method for the operation: -- If the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. +- If the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -22170,7 +22170,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. + The resulting has the property set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are `false`. The property is `null`. The following information describes the implementing method, the node type, and whether a node is lifted. @@ -22179,7 +22179,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V - If `method` is not `null` and it represents a non-void, `static` (`Shared` in Visual Basic) method that takes two arguments, it is the implementing method for the node. -- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. +- Otherwise, if the property of either `left` or `right` represents a user-defined type that overloads the subtraction operator, the that represents that method is the implementing method. - Otherwise, if `left`.Type and `right`.Type are numeric types, the implementing method is `null`. @@ -23753,7 +23753,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is `null`. The and properties are both `false`. + The property of the resulting is `null`. The and properties are both `false`. @@ -23869,7 +23869,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting represents . + The property of the resulting represents . @@ -23952,7 +23952,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + The property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. #### Implementing Method The following rules determine the implementing method for the operation: @@ -24040,7 +24040,7 @@ As with `Func`, the last argument is the return type. It can be set to `System.V property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. + The property of the resulting is set to the implementing method. The property is set to the type of the node. If the node is lifted, the and properties are both `true`. Otherwise, they are false. #### Implementing Method The following rules determine the implementing method for the operation: diff --git a/xml/System.Linq.Expressions/LambdaExpression.xml b/xml/System.Linq.Expressions/LambdaExpression.xml index 6339cca9985..d3994a47eba 100644 --- a/xml/System.Linq.Expressions/LambdaExpression.xml +++ b/xml/System.Linq.Expressions/LambdaExpression.xml @@ -68,7 +68,7 @@ ## Remarks The type represents a lambda expression in the form of an expression tree. The type, which derives from and captures the type of the lambda expression more explicitly, can also be used to represent a lambda expression. At runtime, an expression tree node that represents a lambda expression is always of type . - The value of the property of a is . + The value of the property of a is . Use the factory methods to create a object. diff --git a/xml/System.Linq.Expressions/ListInitExpression.xml b/xml/System.Linq.Expressions/ListInitExpression.xml index fede94001b3..6db829e98d2 100644 --- a/xml/System.Linq.Expressions/ListInitExpression.xml +++ b/xml/System.Linq.Expressions/ListInitExpression.xml @@ -64,7 +64,7 @@ ## Remarks Use the factory methods to create a . - The value of the property of a is . + The value of the property of a is . diff --git a/xml/System.Linq.Expressions/MemberAssignment.xml b/xml/System.Linq.Expressions/MemberAssignment.xml index d9c187fb4ad..b805ca93122 100644 --- a/xml/System.Linq.Expressions/MemberAssignment.xml +++ b/xml/System.Linq.Expressions/MemberAssignment.xml @@ -55,13 +55,13 @@ Represents assignment operation for a field or property of an object. - factory methods to create a . - - A has the property equal to . - + factory methods to create a . + + A has the property equal to . + ]]> diff --git a/xml/System.Linq.Expressions/MemberExpression.xml b/xml/System.Linq.Expressions/MemberExpression.xml index 0a073eb9381..e9a27ff1846 100644 --- a/xml/System.Linq.Expressions/MemberExpression.xml +++ b/xml/System.Linq.Expressions/MemberExpression.xml @@ -63,21 +63,21 @@ Represents accessing a field or property. - , or factory methods to create a . - - The value of the property of a is . - - - -## Examples - The following example creates a that represents getting the value of a field member. - + , or factory methods to create a . + + The value of the property of a is . + + + +## Examples + The following example creates a that represents getting the value of a field member. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq.Expressions/BinaryExpression/Overview/Expression.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Linq.Expressions/BinaryExpression/Overview/Expression.vb" id="Snippet5"::: + ]]> @@ -127,11 +127,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 . + ]]> diff --git a/xml/System.Linq.Expressions/MemberInitExpression.xml b/xml/System.Linq.Expressions/MemberInitExpression.xml index bd53c06de30..be52dce92de 100644 --- a/xml/System.Linq.Expressions/MemberInitExpression.xml +++ b/xml/System.Linq.Expressions/MemberInitExpression.xml @@ -64,7 +64,7 @@ ## Remarks Use the factory methods to create a . - The value of the property of a is . + The value of the property of a is . diff --git a/xml/System.Linq.Expressions/MemberListBinding.xml b/xml/System.Linq.Expressions/MemberListBinding.xml index 834ddd11f71..35b36bdceb4 100644 --- a/xml/System.Linq.Expressions/MemberListBinding.xml +++ b/xml/System.Linq.Expressions/MemberListBinding.xml @@ -55,13 +55,13 @@ Represents initializing the elements of a collection member of a newly created object. - factory methods to create a . - - A has the property equal to . - + factory methods to create a . + + A has the property equal to . + ]]> diff --git a/xml/System.Linq.Expressions/MemberMemberBinding.xml b/xml/System.Linq.Expressions/MemberMemberBinding.xml index 32e78cb3814..bf25533b4c1 100644 --- a/xml/System.Linq.Expressions/MemberMemberBinding.xml +++ b/xml/System.Linq.Expressions/MemberMemberBinding.xml @@ -55,13 +55,13 @@ Represents initializing members of a member of a newly created object. - factory methods to create a . - - The value of the property of a object is . - + factory methods to create a . + + The value of the property of a object is . + ]]> diff --git a/xml/System.Linq.Expressions/MethodCallExpression.xml b/xml/System.Linq.Expressions/MethodCallExpression.xml index 1173dc6cae6..1ff0340775b 100644 --- a/xml/System.Linq.Expressions/MethodCallExpression.xml +++ b/xml/System.Linq.Expressions/MethodCallExpression.xml @@ -72,21 +72,21 @@ Represents a call to either static or an instance method. - , , or factory method to create a . - - The value of the property of a object is . - - - -## Examples - The following example creates a object that represents indexing into a two-dimensional array. - + , , or factory method to create a . + + The value of the property of a object is . + + + +## Examples + The following example creates a object that represents indexing into a two-dimensional array. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq.Expressions/BinaryExpression/Overview/Expression.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Linq.Expressions/BinaryExpression/Overview/Expression.vb" id="Snippet3"::: + ]]> @@ -136,11 +136,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 . + ]]> @@ -341,11 +341,11 @@ Gets the that represents the instance for instance method calls or null for static method calls. An that represents the receiving object of the method. - object's property represents a `static` (`Shared` in Visual Basic) method, the property is `null`. - + object's property represents a `static` (`Shared` in Visual Basic) method, the property is `null`. + ]]> diff --git a/xml/System.Linq.Expressions/NewExpression.xml b/xml/System.Linq.Expressions/NewExpression.xml index 7cc18b61e6c..a32e7246aa5 100644 --- a/xml/System.Linq.Expressions/NewExpression.xml +++ b/xml/System.Linq.Expressions/NewExpression.xml @@ -72,21 +72,21 @@ Represents a constructor call. - factory methods to create a . - - The value of the property of a object is . - - - -## Examples - The following example creates a that represents the construction of a new instance of a dictionary object. - + factory methods to create a . + + The value of the property of a object is . + + + +## Examples + The following example creates a that represents the construction of a new instance of a dictionary object. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq.Expressions/BinaryExpression/Overview/Expression.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Linq.Expressions/BinaryExpression/Overview/Expression.vb" id="Snippet10"::: + ]]> @@ -136,11 +136,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 . + ]]> @@ -187,11 +187,11 @@ Gets the arguments to the constructor. A collection of objects that represent the arguments to the constructor. - property is an empty collection if the constructor takes no arguments. - + property is an empty collection if the constructor takes no arguments. + ]]> @@ -304,11 +304,11 @@ Gets the members that can retrieve the values of the fields that were initialized with constructor arguments. A collection of objects that represent the members that can retrieve the values of the fields that were initialized with constructor arguments. - property provides a mapping between the constructor arguments and the type members that correspond to those values. In the case of the construction of an anonymous type, this property maps the constructor arguments to the properties that are exposed by the anonymous type. This mapping information is important because the fields that are initialized by the construction of an anonymous type, or the properties that access those fields, are not discoverable through the or properties of a node. - + property provides a mapping between the constructor arguments and the type members that correspond to those values. In the case of the construction of an anonymous type, this property maps the constructor arguments to the properties that are exposed by the anonymous type. This mapping information is important because the fields that are initialized by the construction of an anonymous type, or the properties that access those fields, are not discoverable through the or properties of a node. + ]]> diff --git a/xml/System.Linq.Expressions/ParameterExpression.xml b/xml/System.Linq.Expressions/ParameterExpression.xml index f00d43ef6c1..568ef97d2ce 100644 --- a/xml/System.Linq.Expressions/ParameterExpression.xml +++ b/xml/System.Linq.Expressions/ParameterExpression.xml @@ -63,21 +63,21 @@ Represents a named parameter expression. - factory method to create a . - - The value of the property of a object is . - - - -## Examples - The following example demonstrates how to create a object that prints the value of a object by using the method. - + factory method to create a . + + The value of the property of a object is . + + + +## Examples + The following example demonstrates how to create a object that prints the value of a object by using the method. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BlockExpression/Overview/program.cs" id="Snippet49"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq.Expressions/BlockExpression/Overview/module1.vb" id="Snippet49"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Linq.Expressions/BlockExpression/Overview/module1.vb" id="Snippet49"::: + ]]> @@ -127,11 +127,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 . + ]]> diff --git a/xml/System.Linq.Expressions/TypeBinaryExpression.xml b/xml/System.Linq.Expressions/TypeBinaryExpression.xml index bed1af5b2d8..0bb4a36b9f5 100644 --- a/xml/System.Linq.Expressions/TypeBinaryExpression.xml +++ b/xml/System.Linq.Expressions/TypeBinaryExpression.xml @@ -59,23 +59,23 @@ Represents an operation between an expression and a type. - factory method to create a . - - The value of the property of a object is . - - - -## Examples - The following example creates a object that represents a type test of a string value against the type. - + factory method to create a . + + The value of the property of a object is . + + + +## Examples + The following example creates a object that represents a type test of a string value against the type. + :::code language="csharp" source="~/snippets/csharp/System.Linq.Expressions/BinaryExpression/Overview/Expression.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq.Expressions/BinaryExpression/Overview/Expression.vb" id="Snippet12"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Linq.Expressions/BinaryExpression/Overview/Expression.vb" id="Snippet12"::: + ]]> diff --git a/xml/System.Linq/Enumerable.xml b/xml/System.Linq/Enumerable.xml index bd6b9fdfba8..724effb2ced 100644 --- a/xml/System.Linq/Enumerable.xml +++ b/xml/System.Linq/Enumerable.xml @@ -3955,7 +3955,7 @@ Only unique elements are returned. This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in C# or `For Each` in Visual Basic. The default equality comparer, , is used to compare values of the types. - To compare a custom data type, you need to override the and the methods, and optionally implement the generic interface in the custom type. For more information, see the property. + To compare a custom data type, you need to override the and the methods, and optionally implement the generic interface in the custom type. For more information, see the property. ## Examples The following code example demonstrates how to use the `Except(IEnumerable, IEnumerable)` method to compare two sequences of numbers and return elements that appear only in the first sequence. @@ -5938,7 +5938,7 @@ Only unique elements are returned. When the object returned by this method is enumerated, `Intersect` yields distinct elements occurring in both sequences in the order in which they appear in `first`. The default equality comparer, , is used to compare values of the types. - To compare a custom data type, you need to override the and the methods, and optionally implement the generic interface in the custom type. For more information, see the property. + To compare a custom data type, you need to override the and the methods, and optionally implement the generic interface in the custom type. For more information, see the property. ## Examples The following code example demonstrates how to use `Intersect(IEnumerable, IEnumerable)` to return the elements that appear in each of two sequences of integers. @@ -13065,7 +13065,7 @@ If comparer is `null`, the default comparer The type of the values in the . Represents a collection of objects that have a common key. - is an that additionally has a key. The key represents the attribute that is common to each value in the . - - The values of an are accessed much as the elements of an are accessed. For example, you can access the values by using a `foreach` in Visual C# or `For Each` in Visual Basic loop to iterate through the object. The Example section contains a code example that shows you how to access both the key and the values of an object. - - The type is used by the standard query operator methods, which return a sequence of elements of type . - - - -## Examples - The following example demonstrates how to work with an object. - - In this example, is called on the array of objects returned by . groups the objects based on the value of their property. Each unique value for in the array of objects becomes a key for a new object, and the objects that have that key form the object's sequence of values. - - Finally, the method is called on the sequence of objects to obtain just the first object. - - The example then outputs the key of the object and the property of each value in the object's sequence of values. Notice that to access an object's sequence of values, you simply use the variable itself. - - :::code language="csharp" source="~/snippets/csharp/System.Linq/IGroupingTKey,TElement/Overview/igrouping.cs" interactive="try-dotnet-method" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq/IGroupingTKey,TElement/Overview/IGrouping.vb" id="Snippet1"::: + is an that additionally has a key. The key represents the attribute that is common to each value in the . + + The values of an are accessed much as the elements of an are accessed. For example, you can access the values by using a `foreach` in Visual C# or `For Each` in Visual Basic loop to iterate through the object. The Example section contains a code example that shows you how to access both the key and the values of an object. + + The type is used by the standard query operator methods, which return a sequence of elements of type . + + + +## Examples + The following example demonstrates how to work with an object. + + In this example, is called on the array of objects returned by . groups the objects based on the value of their property. Each unique value for in the array of objects becomes a key for a new object, and the objects that have that key form the object's sequence of values. + + Finally, the method is called on the sequence of objects to obtain just the first object. + + The example then outputs the key of the object and the property of each value in the object's sequence of values. Notice that to access an object's sequence of values, you simply use the variable itself. + + :::code language="csharp" source="~/snippets/csharp/System.Linq/IGroupingTKey,TElement/Overview/igrouping.cs" interactive="try-dotnet-method" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/System.Linq/IGroupingTKey,TElement/Overview/IGrouping.vb" id="Snippet1"::: ]]> @@ -150,16 +150,16 @@ Gets the key of the . The key of the . - represents the attribute that is common to each value in the . - - - -## Examples - The following example demonstrates how to use the property to label each object in a sequence of objects. The method is used to obtain a sequence of objects. The `foreach` in Visual C# or `For Each` in Visual Basic loop then iterates through each object, outputting its key and the number of values it contains. - + represents the attribute that is common to each value in the . + + + +## Examples + The following example demonstrates how to use the property to label each object in a sequence of objects. The method is used to obtain a sequence of objects. The `foreach` in Visual C# or `For Each` in Visual Basic loop then iterates through each object, outputting its key and the number of values it contains. + :::code language="csharp" source="~/snippets/csharp/System.Linq/IGroupingTKey,TElement/Overview/igrouping.cs" interactive="try-dotnet-method" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Linq/IGroupingTKey,TElement/Overview/IGrouping.vb" id="Snippet2"::: diff --git a/xml/System.Linq/IQueryProvider.xml b/xml/System.Linq/IQueryProvider.xml index 9678790e0ff..c0b44cf1223 100644 --- a/xml/System.Linq/IQueryProvider.xml +++ b/xml/System.Linq/IQueryProvider.xml @@ -47,13 +47,13 @@ Defines methods to create and execute queries that are described by an object. - interface is intended for implementation by query providers. - - For more information about how to create your own LINQ provider, see [LINQ: Building an IQueryable Provider](https://learn.microsoft.com/archive/blogs/mattwar/linq-building-an-iqueryable-provider-part-i). - + interface is intended for implementation by query providers. + + For more information about how to create your own LINQ provider, see [LINQ: Building an IQueryable Provider](https://learn.microsoft.com/archive/blogs/mattwar/linq-building-an-iqueryable-provider-part-i). + ]]> @@ -106,17 +106,17 @@ Constructs an object that can evaluate the query represented by a specified expression tree. An that can evaluate the query represented by the specified expression tree. - [!NOTE] -> The property of the returned object is equal to `expression`. - - The method is used to create new objects, given an expression tree. The query that is represented by the returned object is associated with a specific LINQ provider. - - Several of the standard query operator methods defined in , such as and , call this method. They pass it a that represents a LINQ query. - +> The property of the returned object is equal to `expression`. + + The method is used to create new objects, given an expression tree. The query that is represented by the returned object is associated with a specific LINQ provider. + + Several of the standard query operator methods defined in , such as and , call this method. They pass it a that represents a LINQ query. + ]]> @@ -178,17 +178,17 @@ Constructs an object that can evaluate the query represented by a specified expression tree. An that can evaluate the query represented by the specified expression tree. - [!NOTE] -> The property of the returned object is equal to `expression`. - - The method is used to create new objects, given an expression tree. The query that is represented by the returned object is associated with a specific LINQ provider. - - Most of the standard query operator methods that return enumerable results call this method. They pass it a that represents a LINQ query. - +> The property of the returned object is equal to `expression`. + + The method is used to create new objects, given an expression tree. The query that is represented by the returned object is associated with a specific LINQ provider. + + Most of the standard query operator methods that return enumerable results call this method. They pass it a that represents a LINQ query. + ]]> @@ -240,11 +240,11 @@ Executes the query represented by a specified expression tree. The value that results from executing the specified query. - method executes queries that return a single value (instead of an enumerable sequence of values). Expression trees that represent queries that return enumerable results are executed when their associated object is enumerated. - + method executes queries that return a single value (instead of an enumerable sequence of values). Expression trees that represent queries that return enumerable results are executed when their associated object is enumerated. + ]]> @@ -306,13 +306,13 @@ Executes the strongly-typed query represented by a specified expression tree. The value that results from executing the specified query. - method executes queries that return a single value (instead of an enumerable sequence of values). Expression trees that represent queries that return enumerable results are executed when the object that contains the expression tree is enumerated. - - The standard query operator methods that return singleton results call . They pass it a that represents a LINQ query. - + method executes queries that return a single value (instead of an enumerable sequence of values). Expression trees that represent queries that return enumerable results are executed when the object that contains the expression tree is enumerated. + + The standard query operator methods that return singleton results call . They pass it a that represents a LINQ query. + ]]> diff --git a/xml/System.Linq/IQueryable.xml b/xml/System.Linq/IQueryable.xml index 5c674f507d0..7bccc13a41e 100644 --- a/xml/System.Linq/IQueryable.xml +++ b/xml/System.Linq/IQueryable.xml @@ -51,15 +51,15 @@ Provides functionality to evaluate queries against a specific data source wherein the type of the data is not specified. - interface is intended for implementation by query providers. It is only supposed to be implemented by providers that also implement . If the provider does not also implement , the standard query operators cannot be used on the provider's data source. - - The interface inherits the interface so that if it represents a query, the results of that query can be enumerated. Enumeration causes the expression tree associated with an object to be executed. The definition of "executing an expression tree" is specific to a query provider. For example, it may involve translating the expression tree to an appropriate query language for the underlying data source. Queries that do not return enumerable results are executed when the method is called. - + interface is intended for implementation by query providers. It is only supposed to be implemented by providers that also implement . If the provider does not also implement , the standard query operators cannot be used on the provider's data source. + + The interface inherits the interface so that if it represents a query, the results of that query can be enumerated. Enumeration causes the expression tree associated with an object to be executed. The definition of "executing an expression tree" is specific to a query provider. For example, it may involve translating the expression tree to an appropriate query language for the underlying data source. Queries that do not return enumerable results are executed when the method is called. + For more information about how to create your own LINQ provider, see [LINQ: Building an IQueryable Provider](https://learn.microsoft.com/archive/blogs/mattwar/linq-building-an-iqueryable-provider-part-i). - + ]]> @@ -108,11 +108,11 @@ Gets the type of the element(s) that are returned when the expression tree associated with this instance of is executed. A that represents the type of the element(s) that are returned when the expression tree associated with this object is executed. - property represents the "T" in `IQueryable` or `IQueryable(Of T)`. - + property represents the "T" in `IQueryable` or `IQueryable(Of T)`. + ]]> @@ -159,11 +159,11 @@ Gets the expression tree that is associated with the instance of . The that is associated with this instance of . - represents a LINQ query against a data source, the associated expression tree represents that query. - + represents a LINQ query against a data source, the associated expression tree represents that query. + ]]> @@ -210,11 +210,11 @@ Gets the query provider that is associated with this data source. The that is associated with this data source. - represents a LINQ query against a data source, the associated query provider is the provider that created the instance. - + represents a LINQ query against a data source, the associated query provider is the provider that created the instance. + ]]> diff --git a/xml/System.Linq/Lookup`2.xml b/xml/System.Linq/Lookup`2.xml index 86137355296..0b03098a5f6 100644 --- a/xml/System.Linq/Lookup`2.xml +++ b/xml/System.Linq/Lookup`2.xml @@ -85,24 +85,24 @@ The type of the elements of each value in the . Represents a collection of keys each mapped to one or more values. - resembles a . The difference is that a maps keys to single values, whereas a maps keys to collections of values. - - You can create an instance of a by calling on an object that implements . - + resembles a . The difference is that a maps keys to single values, whereas a maps keys to collections of values. + + You can create an instance of a by calling on an object that implements . + > [!NOTE] -> There is no public constructor to create a new instance of a . Additionally, objects are immutable, that is, you cannot add or remove elements or keys from a object after it has been created. - - - -## Examples - The following example creates a from a collection of objects. It then enumerates the and outputs each key and each value in the key's associated collection of values. It also demonstrates how to use the properties and and the methods and . - +> There is no public constructor to create a new instance of a . Additionally, objects are immutable, that is, you cannot add or remove elements or keys from a object after it has been created. + + + +## Examples + The following example creates a from a collection of objects. It then enumerates the and outputs each key and each value in the key's associated collection of values. It also demonstrates how to use the properties and and the methods and . + :::code language="csharp" source="~/snippets/csharp/System.Linq/LookupTKey,TElement/Overview/lookup.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq/LookupTKey,TElement/Overview/Lookup.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Linq/LookupTKey,TElement/Overview/Lookup.vb" id="Snippet1"::: + ]]> @@ -225,14 +225,14 @@ if is in the ; otherwise, . - to determine whether a contains a specified key. This code example is part of a larger example provided for the class. - + to determine whether a contains a specified key. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Linq/LookupTKey,TElement/Overview/lookup.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq/LookupTKey,TElement/Overview/Lookup.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Linq/LookupTKey,TElement/Overview/Lookup.vb" id="Snippet4"::: + ]]> @@ -287,19 +287,19 @@ Gets the number of key/value collection pairs in the . The number of key/value collection pairs in the . - property does not change because items cannot be added to or removed from a object after it has been created. - - - -## Examples - The following example demonstrates how to use to determine the number of key/value collection pairs in a . This code example is part of a larger example provided for the class. - + property does not change because items cannot be added to or removed from a object after it has been created. + + + +## Examples + The following example demonstrates how to use to determine the number of key/value collection pairs in a . This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Linq/LookupTKey,TElement/Overview/lookup.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq/LookupTKey,TElement/Overview/Lookup.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Linq/LookupTKey,TElement/Overview/Lookup.vb" id="Snippet2"::: + ]]> @@ -360,14 +360,14 @@ Returns a generic enumerator that iterates through the . An enumerator for the . - to iterate through the keys and values of a . This code example is part of a larger example provided for the class. - + to iterate through the keys and values of a . This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Linq/LookupTKey,TElement/Overview/lookup.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq/LookupTKey,TElement/Overview/Lookup.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Linq/LookupTKey,TElement/Overview/Lookup.vb" id="Snippet5"::: + ]]> @@ -420,19 +420,19 @@ Gets the collection of values indexed by the specified key. The collection of values indexed by the specified key. - by using the following syntax: `myLookup[key]` in Visual C# or `myLookup(key)` in Visual Basic. If the `key` is not found in the collection, an empty sequence is returned. - - - -## Examples - The following example demonstrates how to use to index directly into a . This code example is part of a larger example provided for the class. - + by using the following syntax: `myLookup[key]` in Visual C# or `myLookup(key)` in Visual Basic. If the `key` is not found in the collection, an empty sequence is returned. + + + +## Examples + The following example demonstrates how to use to index directly into a . This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Linq/LookupTKey,TElement/Overview/lookup.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Linq/LookupTKey,TElement/Overview/Lookup.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Linq/LookupTKey,TElement/Overview/Lookup.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Linq/Queryable.xml b/xml/System.Linq/Queryable.xml index fd771e89540..976c3b7e326 100644 --- a/xml/System.Linq/Queryable.xml +++ b/xml/System.Linq/Queryable.xml @@ -138,7 +138,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that the specified function, `func`, is applied to each value in the source sequence and the accumulated value is returned. The first value in `source` is used as the seed value for the accumulated value, which corresponds to the first parameter in `func`. @@ -238,7 +238,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that the specified function, `func`, is applied to each value in the source sequence and the accumulated value is returned. The `seed` parameter is used as the seed value for the accumulated value, which corresponds to the first parameter in `func`. @@ -347,7 +347,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that the specified function, `func`, is applied to each value in the source sequence and the accumulated value is returned. The `seed` parameter is used as the seed value for the accumulated value, which corresponds to the first parameter in `func`. The final accumulated value is passed to `selector` to obtain the result value. @@ -589,7 +589,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the `source` parameter's type. The expected behavior is that it determines if all the elements in `source` satisfy the condition in `predicate`. @@ -686,7 +686,7 @@ method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it determines if `source` contains any elements. @@ -777,7 +777,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it determines if any of the elements of `source` satisfy the condition specified by `predicate`. @@ -1071,7 +1071,7 @@ method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source`. @@ -1139,7 +1139,7 @@ method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source`. @@ -1207,7 +1207,7 @@ method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source`. @@ -1273,7 +1273,7 @@ method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source`. @@ -1341,7 +1341,7 @@ method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source`. @@ -1407,7 +1407,7 @@ method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source`. @@ -1473,7 +1473,7 @@ method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source`. @@ -1539,7 +1539,7 @@ method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source`. @@ -1603,7 +1603,7 @@ method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source`. @@ -1669,7 +1669,7 @@ method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source`. @@ -1758,7 +1758,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source` after invoking `selector` on each value. @@ -1847,7 +1847,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source` after invoking `selector` on each value. @@ -1936,7 +1936,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source` after invoking `selector` on each value. @@ -2023,7 +2023,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source` after invoking `selector` on each value. @@ -2112,7 +2112,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source` after invoking `selector` on each value. @@ -2199,7 +2199,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source` after invoking `selector` on each value. @@ -2286,7 +2286,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source` after invoking `selector` on each value. @@ -2373,7 +2373,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source` after invoking `selector` on each value. @@ -2460,7 +2460,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source` after invoking `selector` on each value. @@ -2547,7 +2547,7 @@ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it calculates the average of the values in `source` after invoking `selector` on each value. @@ -2632,7 +2632,7 @@ method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it converts the values in `source` to type `TResult`. @@ -2785,7 +2785,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source1` parameter. The expected behavior is that the elements in `source2` are concatenated to those of `source1` to create a new sequence. @@ -2879,7 +2879,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it determines if `source` contains `item`. @@ -2973,7 +2973,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it determines if `source` contains `item` by using `comparer` to compare values. @@ -3056,7 +3056,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it counts the number of items in `source`. @@ -3142,7 +3142,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it counts the number of items in `source` that satisfy the condition specified by `predicate`. @@ -3299,7 +3299,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns `source` if it is not empty. Otherwise, it returns an that contains `default(TSource)`. @@ -3382,7 +3382,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns `source` if it is not empty. Otherwise, it returns an that contains `defaultValue`. @@ -3473,7 +3473,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns an unordered sequence of the unique items in `source`. @@ -3564,7 +3564,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns an unordered sequence of the unique items in `source` by using `comparer` to compare values. @@ -3839,7 +3839,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the item at position `index` in `source`. @@ -3984,7 +3984,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the item at position `index` in `source`, or `default(TSource)` if `index` is outside the bounds of `source`. @@ -4077,7 +4077,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the`source1` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the`source1` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source1` parameter. The expected behavior is that all the elements in `source1` are returned except for those that are also in `source2`. @@ -4170,7 +4170,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the`source1` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the`source1` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source1` parameter. The expected behavior is that all the elements in `source1` are returned except for those that are also in `source2`, and `comparer` is used to compare values. @@ -4394,7 +4394,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the first element in `source`. @@ -4480,7 +4480,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the first element in `source` that satisfies the condition specified by `predicate`. @@ -4578,7 +4578,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the first element in `source`, or a default value if `source` is empty. @@ -4672,7 +4672,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the first element in `source` that satisfies the condition in `predicate`, or a default value if no element satisfies the condition. @@ -4894,7 +4894,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it groups the elements of `source` by a key value that is obtained by invoking `keySelector` on each element. @@ -4998,7 +4998,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it groups the elements of `source` by a key value. The key value is obtained by invoking `keySelector` on each element, and key values are compared by using `comparer`. @@ -5095,7 +5095,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it groups the elements of `source` by a key value that is obtained by invoking `keySelector` on each element. It invokes `elementSelector` on each element to obtain a result element. @@ -5210,7 +5210,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it groups the elements of `source` by a key value that is obtained by invoking `keySelector` on each element. Key values are compared by using `comparer`. The `elementSelector` parameter is invoked on each element to obtain a result element. @@ -5307,7 +5307,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it groups the elements of `source` by a key value that is obtained by invoking `keySelector` on each element. The `resultSelector` parameter is used to obtain a result value from each group and its key. @@ -5422,7 +5422,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it groups the elements of `source` by key values that are obtained by invoking `keySelector` on each element. The `comparer` parameter is used to compare keys and the `resultSelector` parameter is used to obtain a result value from each group and its key. @@ -5530,7 +5530,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it groups the elements of `source` by key values that are obtained by invoking `keySelector` on each element. The `elementSelector` parameter is used to project the elements of each group, and the `resultSelector` parameter is used to obtain a result value from each group and its key. @@ -5656,7 +5656,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it groups the elements of `source` by key values that are obtained by invoking `keySelector` on each element. The `comparer` parameter is used to compare key values. The `elementSelector` parameter is used to project the elements of each group, and the `resultSelector` parameter is used to obtain a result value from each group and its key. @@ -5776,7 +5776,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `outer` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `outer` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `outer` parameter. The expected behavior is that the `outerKeySelector` and `innerKeySelector` functions are used to extract keys from `outer` and `inner`, respectively. These keys are compared for equality to match each element in `outer` with zero or more elements from `inner`. Then the `resultSelector` function is invoked to project a result object from each group of correlated elements. @@ -5904,7 +5904,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `outer` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `outer` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `outer` parameter. The expected behavior is that the `outerKeySelector` and `innerKeySelector` functions are used to extract keys from `outer` and `inner`, respectively. These keys are compared for equality by using `comparer`. The outcome of the comparisons is used to match each element in `outer` with zero or more elements from `inner`. Then the `resultSelector` function is invoked to project a result object from each group of correlated elements. @@ -6045,7 +6045,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source1` parameter. The expected behavior is that all the elements in `source1` that are also in `source2` are returned. @@ -6138,7 +6138,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source1` parameter. The expected behavior is that all the elements in `source1` that are also in `source2` are returned. The `comparer` parameter is used to compare elements. @@ -6403,7 +6403,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `outer` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `outer` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `outer` parameter. The expected behavior is that of an inner join. The `outerKeySelector` and `innerKeySelector` functions are used to extract keys from `outer` and `inner`, respectively. These keys are compared for equality to match elements from each sequence. A pair of elements is stored for each element in `inner` that matches an element in `outer`. Then the `resultSelector` function is invoked to project a result object from each pair of matching elements. @@ -6531,7 +6531,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `outer` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `outer` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `outer` parameter. The expected behavior is that of an inner join. The `outerKeySelector` and `innerKeySelector` functions are used to extract keys from `outer` and `inner`, respectively. These keys are compared for equality by using `comparer`. The outcome of the comparisons is used to create a matching pair for each element in `inner` that matches an element in `outer`. Then the `resultSelector` function is invoked to project a result object from each pair of matching elements. @@ -6614,7 +6614,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the last element in `source`. @@ -6700,7 +6700,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the last element in `source` that satisfies the condition specified by `predicate`. @@ -6798,7 +6798,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the last element in `source`, or a default value if `source` is empty. @@ -6892,7 +6892,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the last element in `source` that satisfies the condition specified by `predicate`. It returns a default value if there is no such element in `source`. @@ -7306,7 +7306,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it counts the number of items in `source` and returns an . @@ -7392,7 +7392,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it counts the number of items in `source` that satisfy the condition specified by `predicate` and returns an . @@ -7475,7 +7475,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the maximum value in `source`. @@ -7636,7 +7636,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element in `source` and returns the maximum value. @@ -7941,7 +7941,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the minimum value in `source`. @@ -8103,7 +8103,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element in `source` and returns the minimum value. @@ -8407,7 +8407,7 @@ The last chunk will contain the remaining elements and may be of a smaller size. that represents calling `OfType` itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The `OfType` method generates a that represents calling `OfType` itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling `OfType` depends on the implementation of the type of the `source` parameter. The expected behavior is that it filters out any elements in `source` that are not of type `TResult`. @@ -8665,7 +8665,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it sorts the elements of `source` based on the key obtained by invoking `keySelector` on each element of `source`. @@ -8769,7 +8769,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it sorts the elements of `source` based on the key obtained by invoking `keySelector` on each element of `source`. The `comparer` parameter is used to compare keys. @@ -8865,7 +8865,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it sorts the elements of `source` in descending order, based on the key obtained by invoking `keySelector` on each element of `source`. @@ -8961,7 +8961,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it sorts the elements of `source` in descending order, based on the key obtained by invoking `keySelector` on each element of `source`. The `comparer` parameter is used to compare keys. @@ -9257,7 +9257,7 @@ The query behavior that occurs as a result of executing an expression tree method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it reverses the order of the elements in `source`. @@ -9566,7 +9566,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depend on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` to project it into a different form. @@ -9660,7 +9660,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` to project it into a different form. @@ -9764,7 +9764,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` to project it into an enumerable form. It then concatenates the enumerable results into a single, one-dimensional sequence. @@ -9858,7 +9858,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` to project it into an enumerable form. Each enumerable result incorporates the index of the source element. It then concatenates the enumerable results into a single, one-dimensional sequence. @@ -9963,7 +9963,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `collectionSelector` on each element of `source` to project it into an enumerable form. Then the function represented by `resultSelector` is invoked on each element in each intermediate sequence. The resulting values are concatenated into a single, one-dimensional sequence. @@ -10068,7 +10068,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `collectionSelector` on each element of `source` to project it into an enumerable form. Each enumerable result incorporates the source element's index. Then the function represented by `resultSelector` is invoked on each element in each intermediate sequence. The resulting values are concatenated into a single, one-dimensional sequence. @@ -10154,7 +10154,7 @@ The query behavior that occurs as a result of executing an expression tree method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source1` parameter. The expected behavior is that it determines if the two source sequences are equal. @@ -10253,7 +10253,7 @@ The query behavior that occurs as a result of executing an expression tree method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source1` parameter. The expected behavior is that it determines if the two source sequences are equal by using `comparer` to compare elements. @@ -10379,7 +10379,7 @@ The query behavior that occurs as a result of executing an expression tree method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the only element in `source`. @@ -10470,7 +10470,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the only element in `source` that satisfies the condition specified by `predicate`. @@ -10571,7 +10571,7 @@ The query behavior that occurs as a result of executing an expression tree method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the only element in `source`, or a default value if `source` is empty. @@ -10666,7 +10666,7 @@ The query behavior that occurs as a result of executing an expression tree ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the only element in `source` that satisfies the condition specified by `predicate`, or a default value if no such element exists. @@ -10868,7 +10868,7 @@ The query behavior that occurs as a result of executing an expression tree method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it skips the first `count` elements in `source` and returns the remaining elements. @@ -11032,7 +11032,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it applies `predicate` to each element in `source` until it finds an element for which `predicate` returns false. That element and all the remaining elements are returned. @@ -11117,7 +11117,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it applies `predicate` to each element in `source` until it finds an element for which `predicate` returns false. That element and all the remaining elements are returned. The index of each source element is provided as the second argument to `predicate`. @@ -11191,7 +11191,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the sum of the values in `source`. @@ -11248,7 +11248,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the sum of the values in `source`. @@ -11304,7 +11304,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the sum of the values in `source`. @@ -11361,7 +11361,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the sum of the values in `source`. @@ -11418,7 +11418,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the sum of the values in `source`. @@ -11475,7 +11475,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the sum of the values in `source`. @@ -11531,7 +11531,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the sum of the values in `source`. @@ -11588,7 +11588,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the sum of the values in `source`. @@ -11645,7 +11645,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the sum of the values in `source`. @@ -11709,7 +11709,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the sum of the values in `source`. @@ -11794,7 +11794,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` and returns the sum of the resulting values. @@ -11882,7 +11882,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` and returns the sum of the resulting values. @@ -11967,7 +11967,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` and returns the sum of the resulting values. @@ -12055,7 +12055,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` and returns the sum of the resulting values. @@ -12143,7 +12143,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` and returns the sum of the resulting values. @@ -12231,7 +12231,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` and returns the sum of the resulting values. @@ -12318,7 +12318,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` and returns the sum of the resulting values. @@ -12406,7 +12406,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` and returns the sum of the resulting values. @@ -12494,7 +12494,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` and returns the sum of the resulting values. @@ -12581,7 +12581,7 @@ If `count` is not a positive number, this method returns an identical copy of th ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it invokes `selector` on each element of `source` and returns the sum of the resulting values. @@ -12666,7 +12666,7 @@ If `count` is not a positive number, this method returns an identical copy of th method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it takes the first `count` elements from the start of `source`. @@ -12887,7 +12887,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it applies `predicate` to each element in `source` until it finds an element for which `predicate` returns `false`. It returns all the elements up until that point. @@ -12972,7 +12972,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it applies `predicate` to each element in `source` until it finds an element for which `predicate` returns `false`. It returns all the elements up until that point. The index of each source element is provided as the second argument to `predicate`. @@ -13076,7 +13076,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it performs a secondary sort of the elements of `source` based on the key obtained by invoking `keySelector` on each element of `source`. All previously established sort orders are preserved. @@ -13180,7 +13180,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it performs a secondary sort of the elements of `source` based on the key obtained by invoking `keySelector` on each element of `source`. All previously established sort orders are preserved. The `comparer` parameter is used to compare key values. @@ -13276,7 +13276,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it performs a secondary sort of the elements of `source` in descending order, based on the key obtained by invoking `keySelector` on each element of `source`. All previously established sort orders are preserved. @@ -13372,7 +13372,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The result of calling is cast to type and returned. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it performs a secondary sort of the elements of `source` in descending order, based on the key obtained by invoking `keySelector` on each element of `source`. All previously established sort orders are preserved. The `comparer` parameter is used to compare key values. @@ -13465,7 +13465,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source1` parameter. The expected behavior is that the set union of the elements in `source1` and `source2` is returned. @@ -13558,7 +13558,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source1` parameter. The expected behavior is that the set union of the elements in `source1` and `source2` is returned. The `comparer` parameter is used to compare values. @@ -13790,7 +13790,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the elements from `source` that satisfy the condition specified by `predicate`. @@ -13875,7 +13875,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ ## Remarks This method has at least one parameter of type whose type argument is one of the types. For these parameters, you can pass in a lambda expression and it will be compiled to an . - The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source` parameter. The query behavior that occurs as a result of executing an expression tree that represents calling depends on the implementation of the type of the `source` parameter. The expected behavior is that it returns the elements from `source` that satisfy the condition specified by `predicate`. The index of each source element is provided as the second argument to `predicate`. @@ -14054,7 +14054,7 @@ If `count` is not a positive number, this method returns an empty queryable sequ method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. + The method generates a that represents calling itself as a constructed generic method. It then passes the to the method of the represented by the property of the `source1` parameter. The method merges each element of the first sequence with an element that has the same index in the second sequence. If the sequences do not have the same number of elements, the method merges sequences until it reaches the end of one of them. For example, if one sequence has three elements and the other one has four, the resulting sequence will have only three elements. diff --git a/xml/System.Management/ConnectionOptions.xml b/xml/System.Management/ConnectionOptions.xml index 2c7f84f4535..fed33b57014 100644 --- a/xml/System.Management/ConnectionOptions.xml +++ b/xml/System.Management/ConnectionOptions.xml @@ -26,14 +26,14 @@ Specifies all settings required to make a WMI connection. - is created to connect to the remote computer with default connection options. - + is created to connect to the remote computer with default connection options. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ConnectionOptions/cs/ConnectionOptions.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Overview/ConnectionOptions.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Overview/ConnectionOptions.vb" id="Snippet1"::: + ]]> @@ -65,21 +65,21 @@ Initializes a new instance of the class for the connection operation, using default values. This is the parameterless constructor. - is created to connect to the remote computer with default connection options. - + is created to connect to the remote computer with default connection options. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ConnectionOptions/cs/ConnectionOptions.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Overview/ConnectionOptions.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Overview/ConnectionOptions.vb" id="Snippet1"::: + ]]> @@ -162,21 +162,21 @@ Reserved for future use. Initializes a new instance of the class to be used for a WMI connection, using the specified values. - is created to connect to the remote computer with the desired connection options. - + is created to connect to the remote computer with the desired connection options. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ConnectionOptions-9/cs/ConnectionOptions-9.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/.ctor/ConnectionOptions-9.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/.ctor/ConnectionOptions-9.vb" id="Snippet1"::: + ]]> @@ -203,25 +203,25 @@ Gets or sets the COM authentication level to be used for operations in this connection. Returns an enumeration value indicating the COM authentication level used for a connection to the local or a remote computer. - if the client requires all communication to be encrypted. - -## Property Value - The COM authentication level to be used for operations in this connection. The default value is , which indicates that the client will use the authentication level requested by the server, according to the standard DCOM negotiation process. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example connects to a remote computer and displays information about the operating system on the remote computer. A is created to connect to the remote computer with the desired connection options. - + if the client requires all communication to be encrypted. + +## Property Value + The COM authentication level to be used for operations in this connection. The default value is , which indicates that the client will use the authentication level requested by the server, according to the standard DCOM negotiation process. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example connects to a remote computer and displays information about the operating system on the remote computer. A is created to connect to the remote computer with the desired connection options. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ConnectionOptions_Authentication/cs/ConnectionOptions_Authentication.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Authentication/ConnectionOptions_Authentication.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Authentication/ConnectionOptions_Authentication.vb" id="Snippet1"::: + ]]> @@ -249,37 +249,37 @@ Gets or sets the authority to be used to authenticate the specified user. Returns a that defines the authority used to authenticate the specified user. - -``` - - If the property value begins with the string "NTLMDOMAIN:", NTLM authentication will be used and the property should contain a NTLM domain name. For example, - -``` -NTLMDOMAIN: -``` - - If the property is null, NTLM authentication will be used and the NTLM domain of the current user will be used. - -## Property Value - If not `null`, this property can contain the name of the Windows NT/Windows 2000 domain in which to obtain the user to authenticate. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example connects to a remote computer and displays information about the operating system on the remote computer. A is created to connect to the remote computer with the desired connection options. - + +``` + + If the property value begins with the string "NTLMDOMAIN:", NTLM authentication will be used and the property should contain a NTLM domain name. For example, + +``` +NTLMDOMAIN: +``` + + If the property is null, NTLM authentication will be used and the NTLM domain of the current user will be used. + +## Property Value + If not `null`, this property can contain the name of the Windows NT/Windows 2000 domain in which to obtain the user to authenticate. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example connects to a remote computer and displays information about the operating system on the remote computer. A is created to connect to the remote computer with the desired connection options. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ConnectionOptions_Authority/cs/ConnectionOptions_Authority.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Authority/ConnectionOptions_Authority.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Authority/ConnectionOptions_Authority.vb" id="Snippet1"::: + ]]> @@ -307,13 +307,13 @@ NTLMDOMAIN: Returns a copy of the object. The cloned object. - @@ -341,16 +341,16 @@ NTLMDOMAIN: Gets or sets a value indicating whether user privileges need to be enabled for the connection operation. This property should only be used when the operation performed requires a certain user privilege to be enabled (for example, a machine restart). Returns a value indicating whether user privileges need to be enabled for the connection operation. - @@ -377,25 +377,25 @@ NTLMDOMAIN: Gets or sets the COM impersonation level to be used for operations in this connection. Returns an enumeration value indicating the impersonation level used to connect to WMI. - setting is advantageous when the provider is a trusted application or service. It eliminates the need for the provider to perform client identity and access checks for the requested operations. However, if for some reason the provider cannot be trusted, allowing it to impersonate the client may constitute a security threat. In such cases, we recommend that this property be set by the client to a lower value, such as . Note that this may cause failure of the provider to perform the requested operations, for lack of sufficient permissions or inability to perform access checks. - -## Property Value - The COM impersonation level to be used for operations in this connection. The default value is , which indicates that the WMI provider can impersonate the client when performing the requested operations in this connection. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example connects to a remote computer and displays information about the operating system on the remote computer. A is created to connect to the remote computer with the desired connection options. - + setting is advantageous when the provider is a trusted application or service. It eliminates the need for the provider to perform client identity and access checks for the requested operations. However, if for some reason the provider cannot be trusted, allowing it to impersonate the client may constitute a security threat. In such cases, we recommend that this property be set by the client to a lower value, such as . Note that this may cause failure of the provider to perform the requested operations, for lack of sufficient permissions or inability to perform access checks. + +## Property Value + The COM impersonation level to be used for operations in this connection. The default value is , which indicates that the WMI provider can impersonate the client when performing the requested operations in this connection. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example connects to a remote computer and displays information about the operating system on the remote computer. A is created to connect to the remote computer with the desired connection options. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ConnectionOptions_Impersonation/cs/ConnectionOptions_Impersonation.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Impersonation/ConnectionOptions_Impersonation.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Impersonation/ConnectionOptions_Impersonation.vb" id="Snippet1"::: + ]]> @@ -422,25 +422,25 @@ NTLMDOMAIN: Gets or sets the locale to be used for the connection operation. Returns a value used for the locale in a connection to WMI. - is created to connect to the remote computer with the desired connection options. - + is created to connect to the remote computer with the desired connection options. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ConnectionOptions_Locale/cs/ConnectionOptions_Locale.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Locale/ConnectionOptions_Locale.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Locale/ConnectionOptions_Locale.vb" id="Snippet1"::: + ]]> @@ -467,19 +467,19 @@ NTLMDOMAIN: Sets the password for the specified user. Returns a value used for the password in a connection to WMI. - property. - -## Property Value - The default value is `null`. If the user name is also `null`, the credentials used will be those of the currently logged-on user. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - + property. + +## Property Value + The default value is `null`. If the user name is also `null`, the credentials used will be those of the currently logged-on user. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + ]]> @@ -506,7 +506,7 @@ NTLMDOMAIN: Returns a SecureString value used for the password in a connection to WMI. ("") specifies a valid zero-length password. ]]> @@ -535,25 +535,25 @@ A blank ("") specifies a valid zero-length p Gets or sets the user name to be used for the connection operation. Returns a value used as the user name in a connection to WMI. - is created to connect to the remote computer with the desired connection options. - + is created to connect to the remote computer with the desired connection options. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ConnectionOptions_UserName/cs/ConnectionOptions_Username.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Username/ConnectionOptions_Username.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ConnectionOptions/Username/ConnectionOptions_Username.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Management/ManagementBaseObject.xml b/xml/System.Management/ManagementBaseObject.xml index 5dcb7ee967e..e267d46a4e9 100644 --- a/xml/System.Management/ManagementBaseObject.xml +++ b/xml/System.Management/ManagementBaseObject.xml @@ -80,13 +80,13 @@ The destination (see ) for this serialization. Initializes a new instance of the class that is serializable. - @@ -113,26 +113,26 @@ Gets the path to the management object's class. The class path to the management object's class. - that represents the path to the management object's class. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example code lists all the classes with their class paths in the root\CIMV2 namespace. - - For the \\\MyBox\root\cimv2:Win32_LogicalDisk= 'C:' object, the class path is \\\MyBox\root\cimv2:Win32_LogicalDisk. - + that represents the path to the management object's class. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example code lists all the classes with their class paths in the root\CIMV2 namespace. + + For the \\\MyBox\root\cimv2:Win32_LogicalDisk= 'C:' object, the class path is \\\MyBox\root\cimv2:Win32_LogicalDisk. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementBaseObject_ClassPath/cs/ManagementBaseObject_ClassPath.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/ClassPath/ManagementBaseObject_ClassPath.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/ClassPath/ManagementBaseObject_ClassPath.vb" id="Snippet1"::: + ]]> @@ -163,13 +163,13 @@ Returns a copy of the object. The new cloned object. - @@ -204,13 +204,13 @@ if the objects compared are equal according to the given options; otherwise, . - @@ -265,13 +265,13 @@ if this is an instance of and represents the same object as this instance; otherwise, . - @@ -299,13 +299,13 @@ Serves as a hash function for a particular type, suitable for use in hashing algorithms and data structures like a hash table. A hash code for the current object. - @@ -336,13 +336,13 @@ The destination (see ) for this serialization. Populates a with the data necessary to deserialize the field represented by this instance. - @@ -375,21 +375,21 @@ Returns the value of the specified property qualifier. The value of the specified qualifier. - method to display the value of the **Description** qualifier for each of the properties in the **Win32_Process** class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + method to display the value of the **Description** qualifier for each of the properties in the **Win32_Process** class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementBaseObject_GetPropertyQualifierValue/cs/ManagementBaseObject_GetPropertyQualifierValue.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/GetPropertyQualifierValue/ManagementBaseObject_GetPropertyQualifierValue.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/GetPropertyQualifierValue/ManagementBaseObject_GetPropertyQualifierValue.vb" id="Snippet1"::: + ]]> @@ -420,21 +420,21 @@ Gets an equivalent accessor to a property's value. The value of the specified property. - method to get the process names. - + method to get the process names. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementBaseObject_GetPropertyValue/cs/ManagementBaseObject_GetPropertyValue.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/GetPropertyValue/ManagementBaseObject_GetPropertyValue.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/GetPropertyValue/ManagementBaseObject_GetPropertyValue.vb" id="Snippet1"::: + ]]> @@ -465,21 +465,21 @@ Gets the value of the specified qualifier. The value of the specified qualifier. - method. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + method. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementBaseObject_GetQualifierValue/cs/ManagementBaseObject_GetQualifierValue.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/GetQualifierValue/ManagementBaseObject_GetQualifierValue.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/GetQualifierValue/ManagementBaseObject_GetQualifierValue.vb" id="Snippet1"::: + ]]> @@ -510,22 +510,22 @@ Returns a textual representation of the object in the specified format. The textual representation of the object in the specified format. - method. For more information about the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + method. For more information about the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementBaseObject_GetText/cs/ManagementBaseObject_GetText.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/GetText/ManagementBaseObject_GetText.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/GetText/ManagementBaseObject_GetText.vb" id="Snippet1"::: + ]]> @@ -556,24 +556,24 @@ Gets access to property values through [] notation. This property is the indexer for the class. You can use the default indexed properties defined by a type, but you cannot explicitly define your own. However, specifying the **expando** attribute on a class automatically provides a default indexed property whose type is Object and whose index type is String. The management object for a specific class property. - variable with a constructor and then get all the instances of a WMI class. - + variable with a constructor and then get all the instances of a WMI class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementBaseObject_Item/cs/ManagementBaseObject_Item.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/Item/ManagementBaseObject_Item.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/Item/ManagementBaseObject_Item.vb" id="Snippet1"::: + ]]> @@ -604,14 +604,14 @@ Provides the internal WMI object represented by a . An representing the internal WMI object. - @@ -638,24 +638,24 @@ Gets a collection of objects describing the properties of the management object. A collection that holds the properties for the management object. - that represents the properties of the management object. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example uses the property to display the value of the **Description** qualifier for each of the properties in the **Win32_Process** class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + that represents the properties of the management object. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example uses the property to display the value of the **Description** qualifier for each of the properties in the **Win32_Process** class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementBaseObject_Properties/cs/ManagementBaseObject_Properties.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/Properties/ManagementBaseObject_Properties.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/Properties/ManagementBaseObject_Properties.vb" id="Snippet1"::: + ]]> @@ -683,24 +683,24 @@ Gets the collection of objects defined on the management object. Each element in the collection holds information such as the *qualifier* name, value, and *flavor*. A collection that holds the qualifiers for the management object. - that represents the qualifiers defined on the management object. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example uses the property to display the value of the **Description** qualifier for each of the properties in the **Win32_Process** class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + that represents the qualifiers defined on the management object. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example uses the property to display the value of the **Description** qualifier for each of the properties in the **Win32_Process** class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementBaseObject_Qualifiers/cs/ManagementBaseObject_Qualifiers.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/Qualifiers/ManagementBaseObject_Qualifiers.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/Qualifiers/ManagementBaseObject_Qualifiers.vb" id="Snippet1"::: + ]]> @@ -735,13 +735,13 @@ The new value for the qualifier. Sets the value of the specified property qualifier. - @@ -773,13 +773,13 @@ The new value for this property. Sets the value of the named property. - @@ -811,13 +811,13 @@ The value to set. Sets the value of the named qualifier. - @@ -878,24 +878,24 @@ Gets the collection of WMI system properties of the management object (for example, the class name, server, and namespace). WMI system property names begin with "__". A collection that contains the system properties for a management object. - that represents the system properties of the management object. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example uses the property to display the name and value of the system properties for the **Win32_Process** class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + that represents the system properties of the management object. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example uses the property to display the name and value of the system properties for the **Win32_Process** class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_ManagementBaseObject_SystemProperties/cs/ManagementBaseObject_SystemProperties.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/SystemProperties/ManagementBaseObject_SystemProperties.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/ManagementBaseObject/SystemProperties/ManagementBaseObject_SystemProperties.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Management/ManagementOptions.xml b/xml/System.Management/ManagementOptions.xml index 0777c91382d..6baff8c45e4 100644 --- a/xml/System.Management/ManagementOptions.xml +++ b/xml/System.Management/ManagementOptions.xml @@ -64,13 +64,13 @@ Returns a copy of the object. The cloned object. - @@ -98,16 +98,16 @@ Gets or sets a WMI context object. This is a name-value pairs list to be passed through to a WMI provider that supports context information for customized operation. Returns a that contains WMI context information. - @@ -133,11 +133,11 @@ Indicates that no timeout should occur. - property. - + property. + ]]> @@ -164,19 +164,19 @@ Gets or sets the time-out to apply to the operation. Note that for operations that return collections, this time-out applies to the enumeration through the resulting collection, not the operation itself (the property is used for the latter). This property is used to indicate that the operation should be performed semi-synchronously. Returns a that defines the time-out time to apply to the operation. - property is used in the corresponding semi-synchronous operation for the following classes: , , , , , and . - - This property has no effect on the method. - -## Property Value - The default value for this property is , which means the operation will block. The value specified must be positive. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - + property is used in the corresponding semi-synchronous operation for the following classes: , , , , , and . + + This property has no effect on the method. + +## Property Value + The default value for this property is , which means the operation will block. The value specified must be positive. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + ]]> diff --git a/xml/System.Management/MethodData.xml b/xml/System.Management/MethodData.xml index d9151860054..abf51a73a83 100644 --- a/xml/System.Management/MethodData.xml +++ b/xml/System.Management/MethodData.xml @@ -26,14 +26,14 @@ Contains information about a WMI method. - class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_MethodData/cs/MethodData.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/MethodData/Overview/MethodData.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/MethodData/Overview/MethodData.vb" id="Snippet1"::: + ]]> @@ -60,25 +60,25 @@ Gets the input parameters to the method. Each parameter is described as a property in the object. If a parameter is both in and out, it appears in both the and properties. Returns a containing the input parameters to the method. - containing all the input parameters to the method. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example lists information about the **Win32_Process.Create** method using the class. For more information about the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + containing all the input parameters to the method. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example lists information about the **Win32_Process.Create** method using the class. For more information about the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_MethodData_InParameters/cs/MethodData_InParameters.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/MethodData/InParameters/MethodData_InParameters.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/MethodData/InParameters/MethodData_InParameters.vb" id="Snippet1"::: + ]]> @@ -105,24 +105,24 @@ Gets the name of the method. Returns a value containing the name of the method. - class. For more information about the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + class. For more information about the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_MethodData_Name/cs/MethodData_Name.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/MethodData/Name/MethodData_Name.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/MethodData/Name/MethodData_Name.vb" id="Snippet1"::: + ]]> @@ -149,16 +149,16 @@ Gets the name of the management class in which the method was first introduced in the class inheritance hierarchy. Returns a value containing the name of the class in which the method was first introduced in the class inheritance hierarchy. - @@ -185,27 +185,27 @@ Gets the output parameters to the method. Each parameter is described as a property in the object. If a parameter is both in and out, it will appear in both the and properties. Returns a containing the output parameters for the method. - returned by the property and holds the return value of the method. - -## Property Value - A containing all the output parameters to the method. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example lists information about the **Win32_Process.Create** method using the class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + returned by the property and holds the return value of the method. + +## Property Value + A containing all the output parameters to the method. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example lists information about the **Win32_Process.Create** method using the class. For more information on the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_MethodData_OutParameters/cs/MethodData_OutParameters.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/MethodData/OutParameters/MethodData_OutParameters.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/MethodData/OutParameters/MethodData_OutParameters.vb" id="Snippet1"::: + ]]> @@ -232,24 +232,24 @@ Gets a collection of qualifiers defined in the method. Each element is of type and contains information such as the *qualifier* name, value, and *flavor*. Returns a containing the qualifiers for the method. - containing the qualifiers for this method. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example lists information about the **Win32_Process.Create** method using the class. For more information about the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. - + containing the qualifiers for this method. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example lists information about the **Win32_Process.Create** method using the class. For more information about the **Win32_Process** class, see the [Windows Management Instrumentation](/windows/desktop/wmisdk/wmi-start-page) documentation. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_MethodData_Qualifiers/cs/MethodData_Qualifiers.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/MethodData/Qualifiers/MethodData_Qualifiers.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/MethodData/Qualifiers/MethodData_Qualifiers.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Management/SelectQuery.xml b/xml/System.Management/SelectQuery.xml index 125a5def4c9..9f7645b9b5d 100644 --- a/xml/System.Management/SelectQuery.xml +++ b/xml/System.Management/SelectQuery.xml @@ -55,13 +55,13 @@ Initializes a new instance of the class. This is the parameterless constructor. - @@ -88,21 +88,21 @@ The entire query or the class name to use in the query. The parser in this class attempts to parse the string as a valid WQL SELECT query. If the parser is unsuccessful, it assumes the string is a class name. Initializes a new instance of the class for the specified query or the specified class name. - by specifying a query. - + by specifying a query. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_SelectQuery-S/cs/SelectQuery-S.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/.ctor/SelectQuery-S.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/.ctor/SelectQuery-S.vb" id="Snippet1"::: + ]]> @@ -132,21 +132,21 @@ The condition to be applied to form the result set of classes. Initializes a new instance of the class for a schema query, optionally specifying a condition. - by specifying a condition. - + by specifying a condition. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_SelectQuery-B_S/cs/SelectQuery-B_S.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/.ctor/SelectQuery-B_S.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/.ctor/SelectQuery-B_S.vb" id="Snippet1"::: + ]]> @@ -175,21 +175,21 @@ The condition to be applied in the query. Initializes a new instance of the class with the specified class name and condition. - by specifying a WMI class name and a condition. - + by specifying a WMI class name and a condition. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_SelectQuery-S_S/cs/SelectQuery-S_S.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/.ctor/SelectQuery-S_S.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/.ctor/SelectQuery-S_S.vb" id="Snippet1"::: + ]]> @@ -220,21 +220,21 @@ An array of property names to be returned in the query results. Initializes a new instance of the class with the specified class name and condition, selecting only the specified properties. - by specifying a WMI class name, condition, and array of properties. - + by specifying a WMI class name, condition, and array of properties. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_SelectQuery-S_S_S/cs/SelectQuery-S_S_S.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/.ctor/SelectQuery-S_S_S.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/.ctor/SelectQuery-S_S_S.vb" id="Snippet1"::: + ]]> @@ -261,13 +261,13 @@ Builds the query string according to the current property values. - @@ -294,27 +294,27 @@ Gets or sets the class name to be selected from in the query. Returns a value containing the name of the class in the query. - item in a SELECT query of the form "SELECT * FROM \ WHERE \". - -## Property Value - A string representing the name of the class in the query. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - - - -## Examples - The following example initializes a by specifying a query and then changes the property. - + item in a SELECT query of the form "SELECT * FROM \ WHERE \". + +## Property Value + A string representing the name of the class in the query. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + + + +## Examples + The following example initializes a by specifying a query and then changes the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_SelectQuery_ClassName/cs/SelectQuery_ClassName.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/ClassName/SelectQuery_ClassName.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/ClassName/SelectQuery_ClassName.vb" id="Snippet1"::: + ]]> @@ -342,13 +342,13 @@ Creates a copy of the object. The copied object. - @@ -375,19 +375,19 @@ Gets or sets the condition to be applied in the SELECT query. Returns a value containing the condition to be applied to the SELECT query. - item in a SELECT query of the form "SELECT * FROM \ WHERE \". - -## Property Value - A string containing the condition to be applied in the SELECT query. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - + item in a SELECT query of the form "SELECT * FROM \ WHERE \". + +## Property Value + A string containing the condition to be applied in the SELECT query. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + ]]> @@ -414,17 +414,17 @@ Gets or sets a value indicating whether this query is a schema query or an instances query. Returns a value indicating whether the query is a schema query. - @@ -454,13 +454,13 @@ The query string to be parsed. Parses the query string and sets the property values accordingly. - @@ -487,25 +487,25 @@ Gets or sets the query in the object, in string form. Returns a value containing the query. - with the parameterless constructor and then changes the property. - + with the parameterless constructor and then changes the property. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WindowsServer/wminet_SelectQuery_QueryString/cs/SelectQuery_QueryString.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/QueryString/SelectQuery_QueryString.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Management/SelectQuery/QueryString/SelectQuery_QueryString.vb" id="Snippet1"::: + ]]> @@ -532,19 +532,19 @@ Ggets or sets an array of property names to be selected in the query. Returns a containing the names of the properties to be selected in the query. - item in a SELECT query of the form "SELECT \ FROM \ WHERE \". - -## Property Value - A containing the names of the properties to be selected in the query. - -## .NET Framework Security - Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). - + item in a SELECT query of the form "SELECT \ FROM \ WHERE \". + +## Property Value + A containing the names of the properties to be selected in the query. + +## .NET Framework Security + Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see [Using Libraries from Partially Trusted Code](/dotnet/framework/misc/using-libraries-from-partially-trusted-code). + ]]> diff --git a/xml/System.Media/SoundPlayer.xml b/xml/System.Media/SoundPlayer.xml index b90cc0c0803..3246432ea96 100644 --- a/xml/System.Media/SoundPlayer.xml +++ b/xml/System.Media/SoundPlayer.xml @@ -53,7 +53,7 @@ ## Remarks The class provides a simple interface for loading and playing a .wav file. The class supports loading a .wav file from a file path, a URL, a that contains a .wav file, or an embedded resource that contains a .wav file. - To play a sound using the class, configure a with a path to the .wav file and call one of the play methods. You can identify the .wav file to play by using one of the constructors or by setting either the or property. The file can be loaded prior to playing by using one of the load methods, or loading can be deferred until one of the play methods is called. A configured to load a .wav file from a or URL must load the .wav file into memory before playback begins. + To play a sound using the class, configure a with a path to the .wav file and call one of the play methods. You can identify the .wav file to play by using one of the constructors or by setting either the or property. The file can be loaded prior to playing by using one of the load methods, or loading can be deferred until one of the play methods is called. A configured to load a .wav file from a or URL must load the .wav file into memory before playback begins. You can load or play a .wav file synchronously or asynchronously. If you call a synchronous load or play method, the calling thread will wait until the method returns, which may cause painting and other events to be interrupted. Calling an asynchronous load or play method will allow the calling thread to continue without interruption. For more information on asynchronous method calls, see [How to: Run an Operation in the Background](/dotnet/desktop/winforms/controls/how-to-run-an-operation-in-the-background). @@ -922,12 +922,12 @@ This method stores in the task it returns all non-usage exceptions that the meth when the property is set to a . + This property is set to when the property is set to a . ## Examples - The following code example demonstrates the use of the property to assign the .wav file source to an instance of the class. This code example is part of a larger example provided for the class. + The following code example demonstrates the use of the property to assign the .wav file source to an instance of the class. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/System.Windows.Forms.Sound/CPP/soundtestform.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Media/SoundPlayer/Overview/soundtestform.cs" id="Snippet2"::: @@ -1073,7 +1073,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property is set to a new and valid sound location. + This property is set to `null` when the property is set to a new and valid sound location. ]]> diff --git a/xml/System.Media/SystemSound.xml b/xml/System.Media/SystemSound.xml index 988d0316714..5f70e9fe372 100644 --- a/xml/System.Media/SystemSound.xml +++ b/xml/System.Media/SystemSound.xml @@ -32,7 +32,7 @@ property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/SystemSoundsExample/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Media/SystemSound/Overview/form1.cs" id="Snippet1"::: @@ -85,7 +85,7 @@ ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/SystemSoundsExample/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Media/SystemSound/Overview/form1.cs" id="Snippet1"::: diff --git a/xml/System.Media/SystemSounds.xml b/xml/System.Media/SystemSounds.xml index 8651c24b518..36f5f3c3ed5 100644 --- a/xml/System.Media/SystemSounds.xml +++ b/xml/System.Media/SystemSounds.xml @@ -88,7 +88,7 @@ property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/SystemSoundsExample/CPP/form1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Media/SystemSound/Overview/form1.cs" id="Snippet1"::: @@ -187,7 +187,7 @@ The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/SystemSoundsExample/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Media/SystemSound/Overview/form1.cs" id="Snippet3"::: @@ -235,7 +235,7 @@ The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/SystemSoundsExample/CPP/form1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Media/SystemSound/Overview/form1.cs" id="Snippet4"::: @@ -283,7 +283,7 @@ The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Winforms/SystemSoundsExample/CPP/form1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Media/SystemSound/Overview/form1.cs" id="Snippet5"::: diff --git a/xml/System.Messaging/AccessControlEntry.xml b/xml/System.Messaging/AccessControlEntry.xml index 5e0cfe65f7d..5e79af79155 100644 --- a/xml/System.Messaging/AccessControlEntry.xml +++ b/xml/System.Messaging/AccessControlEntry.xml @@ -18,13 +18,13 @@ Specifies access rights for a trustee (user, group, or computer) to perform application-specific implementations of common tasks. - class provides access to these common rights. - - When working with access control entries, you specify a trustee to which you are assigning the rights. You must set at least one of the , , or properties to indicate which rights to assign to the trustee. You can set the property to specify whether the rights you indicate should be granted or denied. The default entry type is to allow rights. - + class provides access to these common rights. + + When working with access control entries, you specify a trustee to which you are assigning the rights. You must set at least one of the , , or properties to indicate which rights to assign to the trustee. You can set the property to specify whether the rights you indicate should be granted or denied. The default entry type is to allow rights. + ]]> @@ -58,13 +58,13 @@ Initializes a new instance of the class that specifies neither a trustee nor set of rights to apply. - property and at least one of the , , or properties before using this instance to set access rights for a trustee. - - You can optionally set the property, though it defaults to `Allow` if you choose not to do so. - + property and at least one of the , , or properties before using this instance to set access rights for a trustee. + + You can optionally set the property, though it defaults to `Allow` if you choose not to do so. + ]]> @@ -90,11 +90,11 @@ A that specifies a user, group, computer, domain, or alias. Initializes a new instance of the class that specifies a trustee to which rights are granted or denied. - property and at least one of the , , or properties before using this instance to set access rights for a trustee. - + property and at least one of the , , or properties before using this instance to set access rights for a trustee. + ]]> The parameter is . @@ -128,11 +128,11 @@ One of the values, which specifies whether to allow, deny, set, or revoke the specified rights. Initializes a new instance of the class that specifies a trustee, rights to assign, and whether to grant or deny these rights. - property to a bitwise combination of the `genericAccessRights` and `standardAccessRights` parameters you specify. - + property to a bitwise combination of the `genericAccessRights` and `standardAccessRights` parameters you specify. + ]]> The parameter is . @@ -209,11 +209,11 @@ Gets or sets a set of common access rights that map to both standard and object-specific access rights for reading, writing, and executing. A bitwise combination of the values. - The value you set is not a valid combination of bitflag members. @@ -242,11 +242,11 @@ Gets or sets a set of standard access rights that correspond to operations common to most types of securable objects. A bitwise combination of the values. - The value you set is not a valid combination of bitflag members. @@ -275,11 +275,11 @@ Gets or sets the user, group, domain, or alias to which you are assigning access rights. A that specifies a user account, group account, or logon session to which a applies. - instances to allow or deny a set of access rights to one or more user accounts. - + instances to allow or deny a set of access rights to one or more user accounts. + ]]> The property is . diff --git a/xml/System.Messaging/AccessControlEntryType.xml b/xml/System.Messaging/AccessControlEntryType.xml index 202bb046a0a..98d82a08295 100644 --- a/xml/System.Messaging/AccessControlEntryType.xml +++ b/xml/System.Messaging/AccessControlEntryType.xml @@ -17,13 +17,13 @@ Specifies whether to allow, deny, or revoke access rights for a trustee. - class to specify a new access right for a trustee, you set its property to describe whether to grant the right or deny it. Furthermore, you can define whether the new right is appended to an existing list (if the trustee already exists in the context for which you are adding or removing access privileges) or if the new right overwrites and deletes any previously defined rights. - - When creating a new `Allow` entry, there might be a preexisting `Deny` entry for the same trustee that takes precedence and must be addressed. Similarly, when creating a new `Deny` entry, there might be an existing `Allow` entry that takes precedence. For information about the order in which access rights are applied, see . - + class to specify a new access right for a trustee, you set its property to describe whether to grant the right or deny it. Furthermore, you can define whether the new right is appended to an existing list (if the trustee already exists in the context for which you are adding or removing access privileges) or if the new right overwrites and deletes any previously defined rights. + + When creating a new `Allow` entry, there might be a preexisting `Deny` entry for the same trustee that takes precedence and must be addressed. Similarly, when creating a new `Deny` entry, there might be an existing `Allow` entry that takes precedence. For information about the order in which access rights are applied, see . + ]]> diff --git a/xml/System.Messaging/AcknowledgeTypes.xml b/xml/System.Messaging/AcknowledgeTypes.xml index 975bc85133d..59baa5a5a77 100644 --- a/xml/System.Messaging/AcknowledgeTypes.xml +++ b/xml/System.Messaging/AcknowledgeTypes.xml @@ -23,26 +23,26 @@ Specifies the types of acknowledgment message that Message Queuing returns to the sending application. - class provides a set of flags that you can combine to request one or more categories of acknowledgment messages. - - When an application sends a message, it can request that Message Queuing return acknowledgment messages indicating the success or failure of the original message. Message Queuing sends these acknowledgment messages to the administration queue you specify. Acknowledgment types can be divided broadly into four groups: positive arrival acknowledgments, positive read acknowledgments, negative arrival acknowledgments, and negative read acknowledgments. Requesting acknowledgments enables your application to receive notification of certain occurrences - for example, a message reaching its destination queue, a message being retrieved, or a time-out preventing a message from reaching or being retrieved from the destination queue. - - When you are using the class to send messages to a queue, you specify the types of acknowledgments your application should receive in the property, as well as the administration queue that receives the acknowledgment messages in the property. - - When you use the class to read acknowledgment messages in the administration queue, the instance's property indicates the condition responsible for the acknowledgment message, for example, if a time-out expired before the original message was read from the queue. - - - -## Examples - The following code example sends and receives a message that contains an order to and from a queue. It specifically requests a positive acknowledgment when the original message reaches or is retrieved from the queue. - + class provides a set of flags that you can combine to request one or more categories of acknowledgment messages. + + When an application sends a message, it can request that Message Queuing return acknowledgment messages indicating the success or failure of the original message. Message Queuing sends these acknowledgment messages to the administration queue you specify. Acknowledgment types can be divided broadly into four groups: positive arrival acknowledgments, positive read acknowledgments, negative arrival acknowledgments, and negative read acknowledgments. Requesting acknowledgments enables your application to receive notification of certain occurrences - for example, a message reaching its destination queue, a message being retrieved, or a time-out preventing a message from reaching or being retrieved from the destination queue. + + When you are using the class to send messages to a queue, you specify the types of acknowledgments your application should receive in the property, as well as the administration queue that receives the acknowledgment messages in the property. + + When you use the class to read acknowledgment messages in the administration queue, the instance's property indicates the condition responsible for the acknowledgment message, for example, if a time-out expired before the original message was read from the queue. + + + +## Examples + The following code example sends and receives a message that contains an order to and from a queue. It specifically requests a positive acknowledgment when the original message reaches or is retrieved from the queue. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Message.Acknowledgment/CPP/message_acknowledgment.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/AcknowledgeTypes/Overview/message_acknowledgment.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Messaging/AcknowledgeTypes/Overview/message_acknowledgment.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Messaging/AcknowledgeTypes/Overview/message_acknowledgment.vb" id="Snippet1"::: + ]]> @@ -115,7 +115,7 @@ 8 A mask used to request a negative acknowledgment when the original message fails to be received from the queue. - + Using the MessageQueue.Peek method does not remove a message from the queue, so this acknowledgment type could be returned even if you did peek the message. Only the MessageQueue.Receive method (or the related asynchronous MessageQueue.BeginReceive method) removes a message from the queue. diff --git a/xml/System.Messaging/Acknowledgment.xml b/xml/System.Messaging/Acknowledgment.xml index 1d65d88e274..6119ac31f06 100644 --- a/xml/System.Messaging/Acknowledgment.xml +++ b/xml/System.Messaging/Acknowledgment.xml @@ -17,26 +17,26 @@ Specifies the result of an attempted message delivery. - class defines the types of acknowledgment messages that Message Queuing posts in the administration queue and the conditions that cause an acknowledgment message to be sent. Acknowledgment types can be divided broadly into four groups: positive arrival acknowledgments, positive read acknowledgments, negative arrival acknowledgments, and negative read acknowledgments. - - The administration queue associated with message is specified in the property. - - Message Queuing sets the property to one of the enumeration values when it creates an acknowledgment message. The property value is typically meaningful only when the instance refers to a system-sent acknowledgment message. Reading the property for a message other than an acknowledgment message throws an exception. - - Message Queuing does not send an acknowledgment message unless the sending application requests that it do so. Your application makes this request by setting the appropriate value for the property. Message Queuing sends all acknowledgment messages to the administration queue specified in the property of the original . - - - -## Examples - The following code example sends and receives a message containing an order to and from a queue. It specifically requests a positive acknowledgment when the original message reaches or is retrieved from the queue. - + class defines the types of acknowledgment messages that Message Queuing posts in the administration queue and the conditions that cause an acknowledgment message to be sent. Acknowledgment types can be divided broadly into four groups: positive arrival acknowledgments, positive read acknowledgments, negative arrival acknowledgments, and negative read acknowledgments. + + The administration queue associated with message is specified in the property. + + Message Queuing sets the property to one of the enumeration values when it creates an acknowledgment message. The property value is typically meaningful only when the instance refers to a system-sent acknowledgment message. Reading the property for a message other than an acknowledgment message throws an exception. + + Message Queuing does not send an acknowledgment message unless the sending application requests that it do so. Your application makes this request by setting the appropriate value for the property. Message Queuing sends all acknowledgment messages to the administration queue specified in the property of the original . + + + +## Examples + The following code example sends and receives a message containing an order to and from a queue. It specifically requests a positive acknowledgment when the original message reaches or is retrieved from the queue. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Message.Acknowledgment/CPP/message_acknowledgment.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/AcknowledgeTypes/Overview/message_acknowledgment.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Messaging/AcknowledgeTypes/Overview/message_acknowledgment.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Messaging/AcknowledgeTypes/Overview/message_acknowledgment.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Messaging/ActiveXMessageFormatter.xml b/xml/System.Messaging/ActiveXMessageFormatter.xml index 3df0078d001..fd3664ad4f3 100644 --- a/xml/System.Messaging/ActiveXMessageFormatter.xml +++ b/xml/System.Messaging/ActiveXMessageFormatter.xml @@ -25,17 +25,17 @@ Serializes or deserializes primitive data types and other objects to or from the body of a Message Queuing message, using a format that is compatible with the MSMQ ActiveX Component. - is compatible with messages sent using Message Queuing COM components, allowing interoperability with applications that use the MSMQ COM control. - - The can serialize most primitives, as well as objects that implement the `IPersistStream` OLE interface. It can deserialize the same set of primitives, but requires further effort when deserializing a COM object (for example, an object created using Visual Basic 6.0) that implements `IPersistStream`. The object to deserialize must be in memory by first importing the object into a .NET Framework application. - - When an application sends a message to the queue using an instance of the class, the formatter serializes the object into a stream and inserts it into the message body. When reading from a queue using a , the formatter deserializes the message data into the property of a . - - ActiveX serialization is very compact, which makes using the and MSMQ COM control a very fast method of serialization. - + is compatible with messages sent using Message Queuing COM components, allowing interoperability with applications that use the MSMQ COM control. + + The can serialize most primitives, as well as objects that implement the `IPersistStream` OLE interface. It can deserialize the same set of primitives, but requires further effort when deserializing a COM object (for example, an object created using Visual Basic 6.0) that implements `IPersistStream`. The object to deserialize must be in memory by first importing the object into a .NET Framework application. + + When an application sends a message to the queue using an instance of the class, the formatter serializes the object into a stream and inserts it into the message body. When reading from a queue using a , the formatter deserializes the message data into the property of a . + + ActiveX serialization is very compact, which makes using the and MSMQ COM control a very fast method of serialization. + ]]> @@ -88,11 +88,11 @@ if the can deserialize the message; otherwise, . - returns `false` if the message body is not a primitive that the Message Queuing ActiveX control can deserialize or if it does not implement the `IPersistStream` interface. - + returns `false` if the message body is not a primitive that the Message Queuing ActiveX control can deserialize or if it does not implement the `IPersistStream` interface. + ]]> The parameter is . @@ -123,11 +123,11 @@ Creates an instance of the class that is identical to the current . An object whose properties are identical to those of this . - class in order to receive multiple messages at the same time (for example, if the application is receiving asynchronously). You typically do not need to call this method in your application code. - + class in order to receive multiple messages at the same time (for example, if the application is receiving asynchronously). You typically do not need to call this method in your application code. + ]]> @@ -187,32 +187,32 @@ Reads the contents from the given message and creates an object that contains the deserialized message. The deserialized message. - property must be one of the managed types in the following table. - -|BodyType value|Managed type| -|--------------------|------------------| -|VT_LPSTR| array (deserialized using ASCII encoding)| -|VT_BSTR, VT_LPWSTR| (deserialized using Unicode encoding)| -|VT_VECTOR | VT_UI1| array| -|VT_BOOL|| -|VT_CLSID|| -|VT_CY|| -|VT_DATE|| -|VT_I1, VT_UI1|| -|VT_I2|| -|VT_UI2|| -|VT_I4|| -|VT_UI4|| -|VT_I8|| -|VT_UI8|| -|VT_R4|| -|VT_R8|| -|VT_NULL|`null`| -|VT_STREAMED_OBJECT|| - + property must be one of the managed types in the following table. + +|BodyType value|Managed type| +|--------------------|------------------| +|VT_LPSTR| array (deserialized using ASCII encoding)| +|VT_BSTR, VT_LPWSTR| (deserialized using Unicode encoding)| +|VT_VECTOR | VT_UI1| array| +|VT_BOOL|| +|VT_CLSID|| +|VT_CY|| +|VT_DATE|| +|VT_I1, VT_UI1|| +|VT_I2|| +|VT_UI2|| +|VT_I4|| +|VT_UI4|| +|VT_I8|| +|VT_UI8|| +|VT_R4|| +|VT_R8|| +|VT_NULL|`null`| +|VT_STREAMED_OBJECT|| + ]]> The property of the passed as a parameter cannot be mapped to a primitive type, nor does it represent a streamed object. @@ -252,32 +252,32 @@ The object to be serialized into the message body. Serializes an object into the body of the message. - property. The object that you serialize must be one of these managed types or must implement the OLE `IPersistStream` interface. - -|BodyType value|Managed type| -|--------------------|------------------| -|VT_LPSTR|| -|VT_BSTR, VT_LPWSTR|| -|VT_VECTOR | VT_UI1|| -|VT_BOOL|| -|VT_CLSID|| -|VT_CY|| -|VT_DATE|| -|VT_I1, VT_UI1|| -|VT_I2|| -|VT_UI2|| -|VT_I4|| -|VT_UI4|| -|VT_I8|| -|VT_UI8|| -|VT_R4|| -|VT_R8|| -|VT_NULL|`null`| -|VT_STREAMED_OBJECT|`IPersistStream` (OLE) | - + property. The object that you serialize must be one of these managed types or must implement the OLE `IPersistStream` interface. + +|BodyType value|Managed type| +|--------------------|------------------| +|VT_LPSTR|| +|VT_BSTR, VT_LPWSTR|| +|VT_VECTOR | VT_UI1|| +|VT_BOOL|| +|VT_CLSID|| +|VT_CY|| +|VT_DATE|| +|VT_I1, VT_UI1|| +|VT_I2|| +|VT_UI2|| +|VT_I4|| +|VT_UI4|| +|VT_I8|| +|VT_UI8|| +|VT_R4|| +|VT_R8|| +|VT_NULL|`null`| +|VT_STREAMED_OBJECT|`IPersistStream` (OLE) | + ]]> The object to serialize is neither a primitive nor a streamed object that implements the OLE interface. diff --git a/xml/System.Messaging/BinaryMessageFormatter.xml b/xml/System.Messaging/BinaryMessageFormatter.xml index 8b4feae8012..16a994b027b 100644 --- a/xml/System.Messaging/BinaryMessageFormatter.xml +++ b/xml/System.Messaging/BinaryMessageFormatter.xml @@ -25,23 +25,23 @@ Serializes or deserializes an object, or an entire graph of connected objects, to or from the body of a Message Queuing message, using a binary format. - is very efficient and can be used to serialize most objects. The result is very compact and fast to parse, but does not allow for loosely coupled messaging as the does. Loosely coupled means that the client and the server can independently version the type that is sent and received. - - When the application sends a message to the queue using an instance of the class, the formatter serializes the object into a stream and inserts it into the message body. When reading from a queue using a , the formatter deserializes the message data into the property of a . - - provides faster throughput than the . Use the when pure speed rather than loosely coupled messaging is desired. - -## Examples + The is very efficient and can be used to serialize most objects. The result is very compact and fast to parse, but does not allow for loosely coupled messaging as the does. Loosely coupled means that the client and the server can independently version the type that is sent and received. + + When the application sends a message to the queue using an instance of the class, the formatter serializes the object into a stream and inserts it into the message body. When reading from a queue using a , the formatter deserializes the message data into the property of a . + + provides faster throughput than the . Use the when pure speed rather than loosely coupled messaging is desired. + +## Examples :::code language="csharp" source="~/snippets/csharp/System.Messaging/BinaryMessageFormatter/Overview/message_binaryformatter.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Messaging/BinaryMessageFormatter/Overview/message_binaryformatter.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Messaging/BinaryMessageFormatter/Overview/message_binaryformatter.vb" id="Snippet1"::: + ]]> @@ -58,7 +58,7 @@ Initializes a new instance of the class. - Initializes a new instance of the class without specifying a type style or top object assembly style. - property (which defines how the root object in a graph is laid out) and the property (which defines how object type descriptions are laid out) before using an instance of the class to serialize and send a message. - + property (which defines how the root object in a graph is laid out) and the property (which defines how object type descriptions are laid out) before using an instance of the class to serialize and send a message. + ]]> @@ -148,16 +148,16 @@ if the binary message formatter can deserialize the message; otherwise, . - returns `false` if the message body is not a binary object. - - On the receiving computer, returns `true` if the assembly for the class to be deserialized exists locally. The assembly must be found in the global assembly cache, or be linked to the application (for example, if the object represents a custom class). - + returns `false` if the message body is not a binary object. + + On the receiving computer, returns `true` if the assembly for the class to be deserialized exists locally. The assembly must be found in the global assembly cache, or be linked to the application (for example, if the object represents a custom class). + ]]> The parameter is . @@ -188,14 +188,14 @@ Creates an instance of the class whose read/write properties (the root object and type description formats) are the same as the current . An object whose properties are identical to those of this , but whose metadata does not specify it to be a formatter class instance. - . It is used for scalability, but does not guarantee read or write thread safety. - + +This method creates a copy of the formatter and initializes all its properties to the values of this . It is used for scalability, but does not guarantee read or write thread safety. + ]]> @@ -229,14 +229,14 @@ This method creates a copy of the formatter and initializes all its properties t Reads the contents from the given message and creates an object that contains the deserialized message. The deserialized message. - The message's property does not indicate a binary object. @@ -277,14 +277,14 @@ This method creates a copy of the formatter and initializes all its properties t Gets or sets a value that defines how the top (root) object of a graph is deserialized with regards to finding and loading its assembly. One of the enumeration values that defines the deserialization behavior. - @@ -321,14 +321,14 @@ Currently, you should accept the default value, `AssemblyStyle`. Gets or sets a value that defines how type descriptions are laid out in the serialized stream. One of the enumeration values that defines the type description format. - @@ -363,16 +363,16 @@ Currently, you should accept the default value, `AssemblyStyle`. The object to be serialized into the message body. Serializes an object into the body of the message. - and properties are used by the formatter only when deserializing a message. - - The can serialize most objects, but the result is not loosely coupled. However, it is compact, so the formatter is efficient for large objects. - + The top object format and type format need not be specified to write to the queue as they must be when reading. The and properties are used by the formatter only when deserializing a message. + + The can serialize most objects, but the result is not loosely coupled. However, it is compact, so the formatter is efficient for large objects. + ]]> The parameter is . diff --git a/xml/System.Messaging/DefaultPropertiesToSend.xml b/xml/System.Messaging/DefaultPropertiesToSend.xml index 4f1a1b7e56d..256f903e117 100644 --- a/xml/System.Messaging/DefaultPropertiesToSend.xml +++ b/xml/System.Messaging/DefaultPropertiesToSend.xml @@ -70,7 +70,7 @@ ## Remarks You can create a new instance of to define default property values to associate with objects sent to a queue that are not of type . When working with objects, a instance is created for you and associated with the member of the . - There are two ways to define a queue's default properties to send, as shown in the following C# code. You can set values for this instance of and associate it with the queue's property: + There are two ways to define a queue's default properties to send, as shown in the following C# code. You can set values for this instance of and associate it with the queue's property: ```csharp DefaultPropertiesToSend myDefaultProperties = new DefaultPropertiesToSend(); @@ -82,7 +82,7 @@ DefaultPropertiesToSend myDefaultProperties = new DefaultPropertiesToSend(); myMessageQueue.Send("hello"); ``` - Or, you can individually assign values to the instance's property directly: + Or, you can individually assign values to the instance's property directly: ```csharp myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; @@ -91,7 +91,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; myMessageQueue.Send("hello"); ``` - If you choose the second of these options, you do not need to call the constructor explicitly. You might want to create instances of , for example, if the properties' default values depend on some criterion of the message being sent. You can create multiple instances and assign one to the queue's property before sending the message to the queue. + If you choose the second of these options, you do not need to call the constructor explicitly. You might want to create instances of , for example, if the properties' default values depend on some criterion of the message being sent. You can create multiple instances and assign one to the queue's property before sending the message to the queue. The following table shows initial property values for an instance of . @@ -162,7 +162,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property specifies the type of acknowledgment messages to return to the sending application. For example, set the property to request notification when a message reaches its destination, when it is retrieved, or whether a time-out has prevented the message from reaching or being retrieved from the destination queue. + The property specifies the type of acknowledgment messages to return to the sending application. For example, set the property to request notification when a message reaches its destination, when it is retrieved, or whether a time-out has prevented the message from reaching or being retrieved from the destination queue. ]]> @@ -205,9 +205,9 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property can be any non-transactional queue. The acknowledgment messages sent to the administration queue can indicate whether or not the original message reached its destination queue, and whether or not it was removed from the queue. + The queue specified in the property can be any non-transactional queue. The acknowledgment messages sent to the administration queue can indicate whether or not the original message reached its destination queue, and whether or not it was removed from the queue. - When the property has any value other than `None`, the sending application must specify the queue to be used as the administration queue. + When the property has any value other than `None`, the sending application must specify the queue to be used as the administration queue. ]]> @@ -249,11 +249,11 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property contains additional, application-specific information that can be used to organize different types of messages, for example, using application-specific indexes. It is the responsibility of the application to interpret information. + The property contains additional, application-specific information that can be used to organize different types of messages, for example, using application-specific indexes. It is the responsibility of the application to interpret information. - Where possible, message data should be included in the body of the message rather than in the property. + Where possible, message data should be included in the body of the message rather than in the property. - When working with foreign queues, use the property to specify non-Message Queuing message properties. As with , it is the responsibility of the application to understand the content of the property. + When working with foreign queues, use the property to specify non-Message Queuing message properties. As with , it is the responsibility of the application to understand the content of the property. ]]> @@ -343,7 +343,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property specifies the algorithm used to encrypt the message body of a private message. + If a message is private, it is encrypted before it is sent and is decrypted when it is received. The property specifies the algorithm used to encrypt the message body of a private message. A queue can require that incoming messages be encrypted. If a non-encrypted (non-private) message is sent to a queue that only accepts private messages, or if a private message is sent to a queue that only accepts non-private messages, the message is rejected by the queue. The sending application can request a negative acknowledgment message be returned to the sending application if a message was rejected. @@ -398,11 +398,11 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property provides for additional application-defined information that is associated with the message, such as a large binary object. It is the responsibility of the receiving application to interpret the contents of the . + The property provides for additional application-defined information that is associated with the message, such as a large binary object. It is the responsibility of the receiving application to interpret the contents of the . Where possible, message data should be included in the body of the message rather than in the extension. - When working with foreign queues, use the property to specify non-Message Queuing message properties. + When working with foreign queues, use the property to specify non-Message Queuing message properties. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Microsoft Message Queuing communicates with such queues through a connector application. @@ -446,7 +446,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property identifies the hashing algorithm Message Queuing uses when authenticating messages or when creating a digital signature for a message. + The property identifies the hashing algorithm Message Queuing uses when authenticating messages or when creating a digital signature for a message. Message Queuing on the source computer uses the hashing algorithm when creating a digital signature for a message. The target Queue Manager then uses the same hashing algorithm to authenticate the message when it is received. @@ -539,7 +539,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property affects how Message Queuing handles the message while it is en route, as well as where the message is placed in the queue when it reaches its destination. Higher priority messages are given preference during routing and inserted toward the front of the queue. Messages with the same priority are placed in the queue according to their arrival time. + The property affects how Message Queuing handles the message while it is en route, as well as where the message is placed in the queue when it reaches its destination. Higher priority messages are given preference during routing and inserted toward the front of the queue. Messages with the same priority are placed in the queue according to their arrival time. Message priority can only be set meaningfully for non-transactional messages. The priority for transactional messages is automatically set to `Lowest`, which causes transactional message priority to be ignored. @@ -585,7 +585,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property indicates whether delivery of a message is guaranteed, even if a computer crashes while the message is en route to the destination queue. + The property indicates whether delivery of a message is guaranteed, even if a computer crashes while the message is en route to the destination queue. If delivery of a message is guaranteed, the message is stored locally at every step along the route until the message is successfully forwarded to the next computer. Setting to `true` on could affect the throughput. @@ -631,7 +631,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property identifies the queue that receives application-generated response messages that are returned to the sending application by the receiving application. Response queues are specified by the sending application when the application sends its messages. Any available queue can be specified as a response queue. + The property identifies the queue that receives application-generated response messages that are returned to the sending application by the receiving application. Response queues are specified by the sending application when the application sends its messages. Any available queue can be specified as a response queue. Messages returned to the response queue are application-specific. The application must define what is in the messages as well as what is to be done when a message is received. @@ -674,19 +674,19 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property specifies the total time in seconds for a sent message to be received from the destination queue. This time limit includes the time spent getting to the destination queue, plus the time spent waiting in the queue before the message is retrieved by an application. + The property specifies the total time in seconds for a sent message to be received from the destination queue. This time limit includes the time spent getting to the destination queue, plus the time spent waiting in the queue before the message is retrieved by an application. > [!CAUTION] > When using dependent client computers, synchronize the clock on the client computer with the clock on the server running Message Queuing. If the two clocks are not synchronized, you might see unpredictable behavior when sending messages when is not . - If the interval expires before the message is removed from the queue, the Message Queuing application discards the message. The message is either sent to the dead-letter queue, if the message's property is set to `true`, or ignored, if is `false`. If is less than , takes precedence. + If the interval expires before the message is removed from the queue, the Message Queuing application discards the message. The message is either sent to the dead-letter queue, if the message's property is set to `true`, or ignored, if is `false`. If is less than , takes precedence. - The message's property can be set to request that Message Queuing send a negative acknowledgment message back to the sending application if the message is not retrieved before the timer expires. + The message's property can be set to request that Message Queuing send a negative acknowledgment message back to the sending application if the message is not retrieved before the timer expires. > [!CAUTION] > If you have specified to receive negative acknowledgments, you will not receive them when the value of is less than the value of . - When several messages are sent in a transaction, Message Queuing uses the value of the first message's property. + When several messages are sent in a transaction, Message Queuing uses the value of the first message's property. ]]> @@ -729,13 +729,13 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; interval expires before the message reaches its destination, the Message Queuing application discards the message. The message is either sent to the dead-letter queue, if the message's property is set to `true`, or ignored, if is `false`. If is greater than , takes precedence. + If the interval expires before the message reaches its destination, the Message Queuing application discards the message. The message is either sent to the dead-letter queue, if the message's property is set to `true`, or ignored, if is `false`. If is greater than , takes precedence. - The message's property can be set to request that Message Queuing send a negative acknowledgment message back to the sending application if the message does not arrive before the timer expires. + The message's property can be set to request that Message Queuing send a negative acknowledgment message back to the sending application if the message does not arrive before the timer expires. If is 0 seconds, Message Queuing tries once to send the message to its destination if the queue is waiting for the message. If the queue is local, the message always reaches the queue. - When several messages are sent in a transaction, Message Queuing uses the value of the first message's property. + When several messages are sent in a transaction, Message Queuing uses the value of the first message's property. ]]> @@ -778,7 +778,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property identifies the transaction status queue on the source computer. The property is set by Message Queuing, and is used by connector applications when retrieving transactional messages sent to a foreign queue. + The property identifies the transaction status queue on the source computer. The property is set by Message Queuing, and is used by connector applications when retrieving transactional messages sent to a foreign queue. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Microsoft Message Queuing communicates with such queues through a connector application. @@ -826,7 +826,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property specifies whether the message needs to be authenticated. If the sending application requests authentication, Message Queuing creates a digital signature and uses it to sign the message when it is sent and to authenticate the message when it is received. + The property specifies whether the message needs to be authenticated. If the sending application requests authentication, Message Queuing creates a digital signature and uses it to sign the message when it is sent and to authenticate the message when it is received. If a message is sent to a queue that only accepts authenticated messages, the message will be rejected when it reaches the queue if is set to `false`. @@ -1025,7 +1025,7 @@ myMessageQueue.DefaultPropertiesToSend.Label = "myLabel"; property specifies whether to track the route of a message as it moves toward its destination queue. If `true`, a Message Queuing-generated report message is sent to a report queue each time the message passes through a Message Queuing routing server. The report queue is specified by the source Queue Manager. Report queues are not limited to Message Queuing-generated report messages. Your application-generated messages can be sent to report queues as well. + The property specifies whether to track the route of a message as it moves toward its destination queue. If `true`, a Message Queuing-generated report message is sent to a report queue each time the message passes through a Message Queuing routing server. The report queue is specified by the source Queue Manager. Report queues are not limited to Message Queuing-generated report messages. Your application-generated messages can be sent to report queues as well. Using tracing involves setting up Active Directory and specifying a report queue for the Message Queuing enterprise. These settings are configured by the administrator. diff --git a/xml/System.Messaging/IMessageFormatter.xml b/xml/System.Messaging/IMessageFormatter.xml index fc055a578b0..1e03a4f064e 100644 --- a/xml/System.Messaging/IMessageFormatter.xml +++ b/xml/System.Messaging/IMessageFormatter.xml @@ -25,13 +25,13 @@ Serializes or deserializes objects from the body of a Message Queuing message. - class, the formatter serializes the object (which can be an instance of any class) into a stream and inserts it into the message body. When reading from a queue using a , the formatter deserializes the message data into the property of a . - - and provide faster throughput than the . The allows interoperability with Visual Basic 6.0 Message Queuing applications. The is loosely coupled, which means that the server and client can version the type that is sent and received independently. - + class, the formatter serializes the object (which can be an instance of any class) into a stream and inserts it into the message body. When reading from a queue using a , the formatter deserializes the message data into the property of a . + + and provide faster throughput than the . The allows interoperability with Visual Basic 6.0 Message Queuing applications. The is loosely coupled, which means that the server and client can version the type that is sent and received independently. + ]]> diff --git a/xml/System.Messaging/Message.xml b/xml/System.Messaging/Message.xml index b15325c78aa..541617e0578 100644 --- a/xml/System.Messaging/Message.xml +++ b/xml/System.Messaging/Message.xml @@ -37,15 +37,15 @@ ## Remarks Use the class to peek or receive messages from a queue, or to have fine control over message properties when sending a message to a queue. - uses the class when it peeks or receives messages from queues, because both the and methods create a new instance of the class and set the instance's properties. The class's read-only properties apply to retrieving messages from a queue, while the read/write properties apply to sending and retrieving messages. When peeks or receives a message from a queue, its property determines which of the message's properties are retrieved. + uses the class when it peeks or receives messages from queues, because both the and methods create a new instance of the class and set the instance's properties. The class's read-only properties apply to retrieving messages from a queue, while the read/write properties apply to sending and retrieving messages. When peeks or receives a message from a queue, its property determines which of the message's properties are retrieved. - The class's method allows you to specify any object type for a message being sent to that queue. You can use the instance's property to specify settings for generic messages sent to the queue. The types of settings include formatter, label, encryption, and authentication. You can also specify values for the appropriate members when you coordinate your messaging application to respond to acknowledgment and report messages. Using a instance to send a message to the queue gives you the flexibility to access and modify many of these properties - either for a single message or on a message-by-message basis. properties take precedence over . + The class's method allows you to specify any object type for a message being sent to that queue. You can use the instance's property to specify settings for generic messages sent to the queue. The types of settings include formatter, label, encryption, and authentication. You can also specify values for the appropriate members when you coordinate your messaging application to respond to acknowledgment and report messages. Using a instance to send a message to the queue gives you the flexibility to access and modify many of these properties - either for a single message or on a message-by-message basis. properties take precedence over . - Message data is stored in the property and to a lesser extent, the and properties. When message data is encrypted, serialized, or deserialized, only the contents of the property are affected. + Message data is stored in the property and to a lesser extent, the and properties. When message data is encrypted, serialized, or deserialized, only the contents of the property are affected. - The contents of the property are serialized when the message is sent, using the property you specify. The serialized contents are found in the property. You can also set the property directly, for example, to send a file as the data content of a message. You can change the or properties at any time before sending the message, and the data will be serialized appropriately when you call . + The contents of the property are serialized when the message is sent, using the property you specify. The serialized contents are found in the property. You can also set the property directly, for example, to send a file as the data content of a message. You can change the or properties at any time before sending the message, and the data will be serialized appropriately when you call . - The properties defined by the property apply only to messages that are not of type . If you specify the property for a , the identically named properties in a instance sent to that queue cause these default properties to be ignored. + The properties defined by the property apply only to messages that are not of type . If you specify the property for a , the identically named properties in a instance sent to that queue cause these default properties to be ignored. For a list of initial property values for an instance of , see the constructor. @@ -101,9 +101,9 @@ ## Remarks Use this overload to create a new instance of the class that has an empty body. - Specify either the property or the property before sending the object. The property can be any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. + Specify either the property or the property before sending the object. The property can be any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. - Unless you write the contents of the message directly to the property, set the property before you send the message. The body is serialized using the property's value at the time the method is called on the instance. + Unless you write the contents of the message directly to the property, set the property before you send the message. The body is serialized using the property's value at the time the method is called on the instance. The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. @@ -186,7 +186,7 @@ class that contains the specified by the `body` parameter. The `body` parameter can be any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. The body is serialized using the unless you change the property before the is sent. If you change the or property at any time before calling , the message will be serialized according to the new property value. + Use this overload to create a new instance of the class that contains the specified by the `body` parameter. The `body` parameter can be any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. The body is serialized using the unless you change the property before the is sent. If you change the or property at any time before calling , the message will be serialized according to the new property value. The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. @@ -270,7 +270,7 @@ class that contains the specified by the `body` parameter and that uses any valid formatter to serialize the body. The `body` parameter is any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. If you change the or property at any time before calling , the message will be serialized according to the new property value. + Use this overload to create a new instance of the class that contains the specified by the `body` parameter and that uses any valid formatter to serialize the body. The `body` parameter is any object that can be serialized, such as a text string, a structure object, a class instance, or an embedded object. If you change the or property at any time before calling , the message will be serialized according to the new property value. The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. @@ -364,9 +364,9 @@ property specifies the type of acknowledgment messages requested by the sending application. Set the property before sending the message to request notification of certain occurrences - for example, a message reaching its destination queue, a message being retrieved, or a time-out preventing a message from reaching or being retrieved from the destination queue. + The property specifies the type of acknowledgment messages requested by the sending application. Set the property before sending the message to request notification of certain occurrences - for example, a message reaching its destination queue, a message being retrieved, or a time-out preventing a message from reaching or being retrieved from the destination queue. - Message Queuing returns notification by sending acknowledgment messages to the property specified by the original message. An acknowledgment message's property indicates the type of acknowledgment that it represents. For example, if an acknowledgment message was sent because a message did not reach the destination before the interval expired, the property of the acknowledgment message would contain the value `ReachQueueTimeout`. + Message Queuing returns notification by sending acknowledgment messages to the property specified by the original message. An acknowledgment message's property indicates the type of acknowledgment that it represents. For example, if an acknowledgment message was sent because a message did not reach the destination before the interval expired, the property of the acknowledgment message would contain the value `ReachQueueTimeout`. @@ -422,13 +422,13 @@ property to verify the status of the original message. + When you receive a message from an administration queue, read the property to verify the status of the original message. - When a message is sent to its destination queue, Message Queuing can be requested to post an acknowledgment message. Such a message can indicate, for example, whether the message arrived and was retrieved within specified time-outs, or it can indicate what went wrong in the case of delivery failure. The destination queue returns acknowledgment messages and posts them to the administration queue specified in the original message's property. The property of an acknowledgment message identifies the acknowledgment message, not the original message. You can find the identifier of the original message in the acknowledgment instance's property. + When a message is sent to its destination queue, Message Queuing can be requested to post an acknowledgment message. Such a message can indicate, for example, whether the message arrived and was retrieved within specified time-outs, or it can indicate what went wrong in the case of delivery failure. The destination queue returns acknowledgment messages and posts them to the administration queue specified in the original message's property. The property of an acknowledgment message identifies the acknowledgment message, not the original message. You can find the identifier of the original message in the acknowledgment instance's property. - If this instance represents an acknowledgment message, the property specifies the type of acknowledgment. Otherwise, the property contains the value `Normal`. + If this instance represents an acknowledgment message, the property specifies the type of acknowledgment. Otherwise, the property contains the value `Normal`. - Use the property of the original message to specify the circumstances under which acknowledgments will be returned. + Use the property of the original message to specify the circumstances under which acknowledgments will be returned. ]]> @@ -484,9 +484,9 @@ property can be any non-transactional queue. The acknowledgment messages sent to the administration queue can indicate whether the original message reached its destination queue and whether it was removed from the queue. + The queue specified in the property can be any non-transactional queue. The acknowledgment messages sent to the administration queue can indicate whether the original message reached its destination queue and whether it was removed from the queue. - When the property has any value other than `None`, the sending application must specify the queue to use as the administration queue. + When the property has any value other than `None`, the sending application must specify the queue to use as the administration queue. @@ -542,11 +542,11 @@ property contains application-specific information that you can use to organize different types of messages. For example, you can use application-specific indexes. It is the responsibility of the application to interpret property information. + The property contains application-specific information that you can use to organize different types of messages. For example, you can use application-specific indexes. It is the responsibility of the application to interpret property information. - Whenever possible, you should include message data in the body of the message rather than the property. + Whenever possible, you should include message data in the body of the message rather than the property. - When working with foreign queues, use the property to specify message properties that do not exist in Message Queuing. As with the property, it is the responsibility of the application to understand the content of the property. + When working with foreign queues, use the property to specify message properties that do not exist in Message Queuing. As with the property, it is the responsibility of the application to understand the content of the property. ]]> @@ -589,12 +589,12 @@ property indicates how quickly the message must be received from the destination queue. The property timer starts when the message is sent, not when the message arrives in the queue. + The message's property indicates how quickly the message must be received from the destination queue. The property timer starts when the message is sent, not when the message arrives in the queue. ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -647,9 +647,9 @@ property is an array of bytes that represents the identifier of the sending user. The sender ID is set by Message Queuing and is used by the receiving Queue Manager to verify whether the sender has access rights to a queue. + The property is an array of bytes that represents the identifier of the sending user. The sender ID is set by Message Queuing and is used by the receiving Queue Manager to verify whether the sender has access rights to a queue. - The absence of the sender ID is an indication by the sending application that Message Queuing should not validate the message's sender nor verify the sender's access rights to the receiving queue. The is trustworthy only if the message was authenticated when it reached the destination queue. The message is rejected when it reaches the destination queue if the queue accepts only authenticated messages and either the or the property is `false`. + The absence of the sender ID is an indication by the sending application that Message Queuing should not validate the message's sender nor verify the sender's access rights to the receiving queue. The is trustworthy only if the message was authenticated when it reached the destination queue. The message is rejected when it reaches the destination queue if the queue accepts only authenticated messages and either the or the property is `false`. > [!CAUTION] > If a message is rejected, it is either sent to the dead-letter queue (if is `true`), or it is ignored. You can request acknowledgments when a message fails to reach a queue. Otherwise, when is `false` the message might be lost without warning. @@ -657,7 +657,7 @@ ## Examples - The following code example gets and sets the value of a message's property. + The following code example gets and sets the value of a message's property. @@ -708,14 +708,14 @@ property is used only by the application while it is interacting with the message and trying to determine if authentication was requested. If the message is in the queue, the message was authenticated. Conversely, if the property is `true`, the receiving Queue Manager authenticated the message when it received that message. + The property is used only by the application while it is interacting with the message and trying to determine if authentication was requested. If the message is in the queue, the message was authenticated. Conversely, if the property is `true`, the receiving Queue Manager authenticated the message when it received that message. You cannot determine if a message failed authentication by looking at its properties. Message Queuing discards messages that fail authentication before they are delivered to the queue. However, you can request that an acknowledgment message be sent if a delivery failure prevents the message from arriving in the queue. ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -774,7 +774,7 @@ When sending a message, always set the and properties together. When the message is sent, Message Queuing ignores the authentication provider name if the connector type is not also set. - The property cannot be `null`, but it can be an empty string (""). + The property cannot be `null`, but it can be an empty string (""). ]]> @@ -829,7 +829,7 @@ property when working with foreign queues to specify which cryptographic service provider is associated with a message. Message Queuing requires the authentication provider name and authentication provider type of the cryptographic provider (authentication provider) to validate the digital signatures of both messages sent to a foreign queue and messages passed to Message Queuing from a foreign queue. + You typically use the property when working with foreign queues to specify which cryptographic service provider is associated with a message. Message Queuing requires the authentication provider name and authentication provider type of the cryptographic provider (authentication provider) to validate the digital signatures of both messages sent to a foreign queue and messages passed to Message Queuing from a foreign queue. Only `RsaFull` is intended to be used with messaging. @@ -884,17 +884,17 @@ property usually contains the data associated with the message. Although you can also send application-specific data in the and properties, you should include message data in the of the message whenever possible. Only the property contents are serialized or encrypted. + The message's property usually contains the data associated with the message. Although you can also send application-specific data in the and properties, you should include message data in the of the message whenever possible. Only the property contents are serialized or encrypted. - The property can contain any object whose size does not exceed 4 MB. If you use to send any object that is not of type to the , that object will be located in the property of the instance returned by or . + The property can contain any object whose size does not exceed 4 MB. If you use to send any object that is not of type to the , that object will be located in the property of the instance returned by or . The string argument in `MessageQueue.Send("hello.")` is an example of such a generic object. - The property indicates the type of information that is stored in the message body. Message Queuing uses this information to identify the type of the property contents. + The property indicates the type of information that is stored in the message body. Message Queuing uses this information to identify the type of the property contents. - Specify either the property or the property before sending the object. The property can be any serializable object, such as a text string, structure object, class instance, or embedded object. + Specify either the property or the property before sending the object. The property can be any serializable object, such as a text string, structure object, class instance, or embedded object. - Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . + Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . > [!NOTE] > Attempting to set the body of a message to will cause a when the `Send` method of the class is called and the is used. @@ -977,11 +977,11 @@ ## Remarks The body of a message can consist of any type of information - for example, a string, a date, a currency, a number, an array of bytes, or any managed object. This information is serialized into a to be passed to the queue. - Specify either the property or the property before sending the object. If you set the property, the contents are serialized into the property. However, you can choose to write the property directly. This is useful, for example, when you want to open a connection to a file and stream its contents as the body of your message. + Specify either the property or the property before sending the object. If you set the property, the contents are serialized into the property. However, you can choose to write the property directly. This is useful, for example, when you want to open a connection to a file and stream its contents as the body of your message. - Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . + Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . - If you set the property to `true` for the body of this message, the message will be encrypted when it is sent, not when you set the property. Therefore, the property is never encrypted. + If you set the property to `true` for the body of this message, the message will be encrypted when it is sent, not when you set the property. Therefore, the property is never encrypted. ]]> @@ -1034,9 +1034,9 @@ property indicates the type of the object within the property of the message. + Message Queuing recognizes the body contents as an object or as a serialized stream. The property indicates the type of the object within the property of the message. - The performs binding between native types and the object in a message body. If you use the , the formatter sets the property for you. + The performs binding between native types and the object in a message body. If you use the , the formatter sets the property for you. Other formatters can provide binding functionality also, as shown in the following C# code. @@ -1054,7 +1054,7 @@ if (myObject is float) { ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -1106,13 +1106,13 @@ if (myObject is float) { property be set whenever an application sets a message property that is usually set by Message Queuing. An application typically uses a in the following two cases: + Message Queuing requires the property be set whenever an application sets a message property that is usually set by Message Queuing. An application typically uses a in the following two cases: - Whenever a connector application passes a message. The tells the sending and receiving applications how to interpret the security and acknowledgment properties of the message. -- Whenever the sending application, rather than Message Queuing, encrypts a message. The tells Message Queuing to use the property value to decrypt the message. +- Whenever the sending application, rather than Message Queuing, encrypts a message. The tells Message Queuing to use the property value to decrypt the message. - You must set the property if you set any of the following properties (otherwise, the queue ignores these properties when the message is sent): + You must set the property if you set any of the following properties (otherwise, the queue ignores these properties when the message is sent): - @@ -1177,11 +1177,11 @@ if (myObject is float) { ## Remarks When Message Queuing generates an acknowledgment or report message, it uses the correlation identifier property to specify the message identifier of the original message. In this manner, the correlation identifier ties the report or acknowledgment message to the original message. - The sending application can then match the acknowledgment or report with the original message by using the property to identify the original message's property. + The sending application can then match the acknowledgment or report with the original message by using the property to identify the original message's property. - Connector applications also must set the property of the acknowledgment and report messages to the message identifier of the original message. + Connector applications also must set the property of the acknowledgment and report messages to the message identifier of the original message. - When your application sends a response message to the sending application, you can set the property of the response message to the message identifier of the original message. The sending application can then match your response message to the message that was sent. + When your application sends a response message to the sending application, you can set the property of the response message to the message identifier of the original message. The sending application can then match your response message to the message that was sent. @@ -1238,12 +1238,12 @@ if (myObject is float) { property is most commonly used to determine the original destination of a message that arrived in a journal or dead-letter queue. Usually, you do not need to examine this property, because you typically retrieve the message from its destination queue. + The property is most commonly used to determine the original destination of a message that arrived in a journal or dead-letter queue. Usually, you do not need to examine this property, because you typically retrieve the message from its destination queue. ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -1297,15 +1297,15 @@ if (myObject is float) { property. The first is when your application, rather than Message Queuing, encrypts a message. The second is when you send an encrypted message to a queuing system other than Message Queuing. + Two scenarios require you to use the property. The first is when your application, rather than Message Queuing, encrypts a message. The second is when you send an encrypted message to a queuing system other than Message Queuing. Before you set this property, you must encrypt the symmetric key with the public key of the receiving queue manager. When you send an application-encrypted message, the receiving queue manager uses the symmetric key to decrypt the message before sending it to its destination queue. If you send a message to a foreign queue, the message is first received by the appropriate connector application, which forwards the encrypted message with the attached symmetric key to the receiving application. It is then the responsibility of the receiving application to decrypt the message using the symmetric key. - When you set the property, you must also set the property. When the message is sent, Message Queuing ignores the property if the property is not also set. + When you set the property, you must also set the property. When the message is sent, Message Queuing ignores the property if the property is not also set. - The property has a maximum array size of 256. + The property has a maximum array size of 256. ]]> @@ -1353,15 +1353,15 @@ if (myObject is float) { property when the sending application requests authentication. The receiving application uses this property to retrieve the digital signature attached to the message. + Message Queuing uses the digital signature when authenticating messages that were sent by Message Queuing version 1.0. In most cases, Message Queuing generates and sets the property when the sending application requests authentication. The receiving application uses this property to retrieve the digital signature attached to the message. - You can only use the property when running Message Queuing version 2.0. The sending application must specify Message Queuing version 1.0 signatures when requesting authentication. If the sending application sends a Message Queuing version 2.0 signature, this property contains a buffer of four bytes, each containing zero. + You can only use the property when running Message Queuing version 2.0. The sending application must specify Message Queuing version 1.0 signatures when requesting authentication. If the sending application sends a Message Queuing version 2.0 signature, this property contains a buffer of four bytes, each containing zero. - The property, together with the property, is also used by connector applications when a message is sent. In this scenario, the connector application - rather than Message Queuing - generates the digital signature, which it bases on the certificate of the user sending the message. + The property, together with the property, is also used by connector applications when a message is sent. In this scenario, the connector application - rather than Message Queuing - generates the digital signature, which it bases on the certificate of the user sending the message. - The property has a maximum array size of 256. + The property has a maximum array size of 256. - When you set the property, you must also set the property. When a message is sent, Message Queuing ignores the property if the property is not also set. + When you set the property, you must also set the property. When a message is sent, Message Queuing ignores the property if the property is not also set. ]]> @@ -1411,7 +1411,7 @@ if (myObject is float) { property specifies the algorithm used to encrypt the message body of a private message. + If a message is private (encrypted), it is encrypted before it is sent and decrypted upon receipt. The property specifies the algorithm used to encrypt the message body of a private message. A queue can require that incoming messages be encrypted. If an application sends a non-encrypted (non-private) message to a queue that accepts only private messages, or if it sends a private message to a queue that accepts only non-private messages, the queue rejects the message. The sending application can request that a negative acknowledgment message be returned in such a case. @@ -1462,11 +1462,11 @@ if (myObject is float) { property provides for application-defined information, like a large binary object, that is associated with the message. It is the responsibility of the receiving application to interpret the contents of the property. + The property provides for application-defined information, like a large binary object, that is associated with the message. It is the responsibility of the receiving application to interpret the contents of the property. - Where possible, you should include message data in the property of the message rather than the property. + Where possible, you should include message data in the property of the message rather than the property. - When working with foreign queues, use the property to specify message properties that do not exist in Message Queuing. + When working with foreign queues, use the property to specify message properties that do not exist in Message Queuing. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Message Queuing communicates with such queues through a connector application. @@ -1512,9 +1512,9 @@ if (myObject is float) { property when reading and writing a message. When a message is sent to the queue, the formatter serializes the property into a stream that can be sent to the message queue. When reading from a queue, the formatter deserializes the message data into the property. + Use the property when reading and writing a message. When a message is sent to the queue, the formatter serializes the property into a stream that can be sent to the message queue. When reading from a queue, the formatter deserializes the message data into the property. - Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . + Unless you write the contents of the message directly to the property, set the property before you send the message. When the method is called on the instance, the body is serialized using the formatter contained in the property. If you send the message without specifying a value for the property, the formatter defaults to . The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. @@ -1632,9 +1632,9 @@ if (myObject is float) { ## Remarks Message Queuing generates a message identifier when the message is sent. The identifier is composed of 20 bytes and includes two items: the machine of the sending computer and a unique identifier for the message on the computer. The combination of the two items produces a message identifier that is unique on the network. - Message Queuing generates message identifiers for all messages - including acknowledgment and report messages. An acknowledgment message is generally sent by Message Queuing in reaction to the arrival or failure of an original, sent message. You can find the property value of the original message in the property of an acknowledgment message. + Message Queuing generates message identifiers for all messages - including acknowledgment and report messages. An acknowledgment message is generally sent by Message Queuing in reaction to the arrival or failure of an original, sent message. You can find the property value of the original message in the property of an acknowledgment message. - You can also use the property when sending a response message to a response queue. To include the identifier of the original message in a response message, set the property of the response message to the property of the original message. The application reading the response message can then use the correlation identifier of the response message to identify the original message. + You can also use the property when sending a response message to a response queue. To include the identifier of the original message in a response message, set the property of the response message to the property of the original message. The application reading the response message can then use the correlation identifier of the response message to identify the original message. @@ -1728,18 +1728,18 @@ if (myObject is float) { property to verify that a message was the first message sent in a single transaction to a single queue. + Receiving applications use the property to verify that a message was the first message sent in a single transaction to a single queue. This property is available only with Message Queuing version 2.0 and later. - To verify transaction boundaries, you can use the property along with two other properties: and . Use the former to check whether a message was the last message sent in the transaction, and use the latter to retrieve the identifier of the transaction. + To verify transaction boundaries, you can use the property along with two other properties: and . Use the former to check whether a message was the last message sent in the transaction, and use the latter to retrieve the identifier of the transaction. If only one message is sent in a transaction, the and properties are both set to `true`. ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -1790,18 +1790,18 @@ if (myObject is float) { property to verify that a message was the last message sent in a single transaction to a single queue. + Receiving applications use the property to verify that a message was the last message sent in a single transaction to a single queue. This property is available only with Message Queuing version 2.0 and later. - To verify transaction boundaries, you can use the property along with two other properties: and . Use the former to check whether a message was the first message sent in the transaction, and use the latter to retrieve the identifier of the transaction. + To verify transaction boundaries, you can use the property along with two other properties: and . Use the former to check whether a message was the first message sent in the transaction, and use the latter to retrieve the identifier of the transaction. If only one message is sent in a transaction, the and properties are both set to `true`. ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -1862,7 +1862,7 @@ if (myObject is float) { ## Examples - The following code example gets and sets the value of a message's property. + The following code example gets and sets the value of a message's property. @@ -1895,13 +1895,13 @@ if (myObject is float) { property provides read-only access to a message's lookup identifier. The lookup identifier, introduced in MSMQ 3.0, is a 64-bit identifier that is generated by Message Queuing and assigned to each message when the message is placed in the queue. The lookup identifier is not the same as the message identifier that is generated when the message is sent. + The property provides read-only access to a message's lookup identifier. The lookup identifier, introduced in MSMQ 3.0, is a 64-bit identifier that is generated by Message Queuing and assigned to each message when the message is placed in the queue. The lookup identifier is not the same as the message identifier that is generated when the message is sent. Message Queuing generates a lookup identifier for all messages that are placed in any queue, including application-generated destination, administration, and report queues, as well as system-generated journal, dead-letter, connector, and outgoing queues. In other words, this includes both messages sent by sending applications and by Message Queuing. The lookup identifier is unique to the queue and has no meaning outside the queue. If a message is sent to several destination queues, or if a copy of a message is stored in a computer journal or queue journal, each copy of the message will have its own lookup identifier when it is placed in its respective queue. - The property can only be read on messages retrieved from a queue. + The property can only be read on messages retrieved from a queue. A lookup identifier is used to read a specific message in the queue. Once the lookup identifier of a message is known, the receiving application can call the or function to go directly to that message and peek at or retrieve it from the queue, unlike cursors that must start at the front of the queue and navigate towards the end of the queue, @@ -1964,7 +1964,7 @@ if (myObject is float) { ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -2019,7 +2019,7 @@ if (myObject is float) { property affects how Message Queuing handles the message both while it is en route and once it reaches its destination. Higher-priority messages are given preference during routing and inserted toward the front of the destination queue. Messages with the same priority are placed in the queue according to their arrival time. + The property affects how Message Queuing handles the message both while it is en route and once it reaches its destination. Higher-priority messages are given preference during routing and inserted toward the front of the destination queue. Messages with the same priority are placed in the queue according to their arrival time. You can set a meaningful priority only for non-transactional messages. Message Queuing automatically sets the priority for transactional messages to `Lowest`, which causes transactional message priority to be ignored. @@ -2079,16 +2079,16 @@ if (myObject is float) { property indicates whether the delivery of a message is guaranteed - even if a computer crashes while the message is en route to the destination queue. + The property indicates whether the delivery of a message is guaranteed - even if a computer crashes while the message is en route to the destination queue. - If delivery of a message is guaranteed, the message is stored locally at every step along the route, until the message is successfully forwarded to the next computer. Setting the property to `true` could affect throughput. + If delivery of a message is guaranteed, the message is stored locally at every step along the route, until the message is successfully forwarded to the next computer. Setting the property to `true` could affect throughput. - If the message is transactional, Message Queuing automatically treats the message as recoverable, regardless of the value of the property. + If the message is transactional, Message Queuing automatically treats the message as recoverable, regardless of the value of the property. ## Examples - The following code example gets and sets the value of a message's property. + The following code example gets and sets the value of a message's property. @@ -2136,14 +2136,14 @@ if (myObject is float) { property identifies the queue that receives application-generated response messages, which the receiving application returns to the sending application. The sending application specifies response queues when the application sends its messages. Any available queue can be specified as a response queue. + The property identifies the queue that receives application-generated response messages, which the receiving application returns to the sending application. The sending application specifies response queues when the application sends its messages. Any available queue can be specified as a response queue. Messages returned to the response queue are application-specific. The application must define the contents of the messages as well as the action to take upon receipt of a message. ## Examples - The following code example gets and sets the value of a message's property. + The following code example gets and sets the value of a message's property. @@ -2225,9 +2225,9 @@ if (myObject is float) { property when the message includes an external security certificate. + The receiving application uses the property when the message includes an external security certificate. - Message Queuing can authenticate a message using either an internal or external security certificate. Message Queuing provides internal certificates, which are used to verify message integrity. A certification authority provides an external certificate, which you can access through the property of the message. In addition to allowing Message Queuing to authenticate the message, an external certificate allows the receiving application to further verify the sender. An internal certificate has no usable value to a receiving application. + Message Queuing can authenticate a message using either an internal or external security certificate. Message Queuing provides internal certificates, which are used to verify message integrity. A certification authority provides an external certificate, which you can access through the property of the message. In addition to allowing Message Queuing to authenticate the message, an external certificate allows the receiving application to further verify the sender. An internal certificate has no usable value to a receiving application. An external certificate must be registered with the directory service of the Message Queuing system. An external certificate contains information about the certification authority, the certificate user, the validity period of the certificate, the public key of the certificate user, and the certification authority's signature. @@ -2273,9 +2273,9 @@ if (myObject is float) { property is `false`, the sender identifier specified in the property is not attached to the message when it is sent. This indicates to Message Queuing that the sender should not be validated when it sends the message to the destination queue. If the property is `true`, the property value is trustworthy only if the message was authenticated. Use the property in conjunction with the property to verify the sender's access rights. + If the property is `false`, the sender identifier specified in the property is not attached to the message when it is sent. This indicates to Message Queuing that the sender should not be validated when it sends the message to the destination queue. If the property is `true`, the property value is trustworthy only if the message was authenticated. Use the property in conjunction with the property to verify the sender's access rights. - A connector application is an application that uses a connector server to provide communication between Message Queuing and other queuing systems. Message Queuing requires connector applications to provide sender identification. You must set the property when sending a message through a connector application. + A connector application is an application that uses a connector server to provide communication between Message Queuing and other queuing systems. Message Queuing requires connector applications to provide sender identification. You must set the property when sending a message through a connector application. ]]> @@ -2329,14 +2329,14 @@ if (myObject is float) { property is important for certain features. For example, transaction processing is supported only by Message Queuing 2.0 and later, and digital signatures are used to authenticate messages sent by MSMQ 1.0. + The property is important for certain features. For example, transaction processing is supported only by Message Queuing 2.0 and later, and digital signatures are used to authenticate messages sent by MSMQ 1.0. - The sending Queue Manager sets the property when the message is sent. + The sending Queue Manager sets the property when the message is sent. ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -2392,12 +2392,12 @@ if (myObject is float) { property is adjusted to the local time of the computer on which this instance of the class was created. This time zone could be different from those of the source and destination queues. + The property is adjusted to the local time of the computer on which this instance of the class was created. This time zone could be different from those of the source and destination queues. ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -2444,12 +2444,12 @@ if (myObject is float) { property does not include preceding two forward slashes (\\\\). For example, `myServer` is a valid . + The format of the property does not include preceding two forward slashes (\\\\). For example, `myServer` is a valid . ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -2506,23 +2506,23 @@ if (myObject is float) { property specifies the total time for a sent message to be received from the destination queue. The time limit includes the time spent getting to the destination queue and the time spent waiting in the queue before the message is received. + The property specifies the total time for a sent message to be received from the destination queue. The time limit includes the time spent getting to the destination queue and the time spent waiting in the queue before the message is received. > [!CAUTION] -> When using dependent client computers, be sure the clock on the client computer is synchronized with the clock on the server that is running Message Queuing. Otherwise, unpredictable behavior might result when sending a message whose property is not . +> When using dependent client computers, be sure the clock on the client computer is synchronized with the clock on the server that is running Message Queuing. Otherwise, unpredictable behavior might result when sending a message whose property is not . - If the interval specified by the property expires before the message is removed from the queue, Message Queuing discards the message in one of two ways. If the message's property is `true`, the message is sent to the dead-letter queue. If is `false`, the message is ignored. + If the interval specified by the property expires before the message is removed from the queue, Message Queuing discards the message in one of two ways. If the message's property is `true`, the message is sent to the dead-letter queue. If is `false`, the message is ignored. - You can set the message's property to request that Message Queuing send a negative acknowledgment message back to the sending application if the message is not retrieved before the timer expires. + You can set the message's property to request that Message Queuing send a negative acknowledgment message back to the sending application if the message is not retrieved before the timer expires. - If the value specified by the property is less than the value specified by the property, takes precedence. + If the value specified by the property is less than the value specified by the property, takes precedence. - When several messages are sent in a single transaction, Message Queuing uses the property of the first message. + When several messages are sent in a single transaction, Message Queuing uses the property of the first message. ## Examples - The following code example gets and sets the value of a message's property. + The following code example gets and sets the value of a message's property. @@ -2576,18 +2576,18 @@ if (myObject is float) { property expires before the message reaches its destination, Message Queuing discards the message in one of two ways. If the message's property is `true`, the message is sent to the dead-letter queue. If is `false`, the message is ignored + If the interval specified by the property expires before the message reaches its destination, Message Queuing discards the message in one of two ways. If the message's property is `true`, the message is sent to the dead-letter queue. If is `false`, the message is ignored - You can set the message's property to request that Message Queuing send a negative acknowledgment message back to the sending application if the message does not arrive before the timer expires. + You can set the message's property to request that Message Queuing send a negative acknowledgment message back to the sending application if the message does not arrive before the timer expires. - If the property is set to 0 seconds, Message Queuing tries once to send the message to its destination - if the queue is waiting for the message. If the queue is local, the message always reaches it. + If the property is set to 0 seconds, Message Queuing tries once to send the message to its destination - if the queue is waiting for the message. If the queue is local, the message always reaches it. - If the value specified by the property is greater than the value specified by the property, takes precedence. + If the value specified by the property is greater than the value specified by the property, takes precedence. - When several messages are sent in a single transaction, Message Queuing uses the property of the first message. + When several messages are sent in a single transaction, Message Queuing uses the property of the first message. ## Examples - The following code example gets and sets the value of a message's property. + The following code example gets and sets the value of a message's property. ]]> @@ -2631,18 +2631,18 @@ if (myObject is float) { property to verify that a message was sent as part of a specific transaction. The transaction identifier contains the identifier of the sending computer (first 16 bits) followed by a 4-byte transaction sequence number. + Receiving applications use the property to verify that a message was sent as part of a specific transaction. The transaction identifier contains the identifier of the sending computer (first 16 bits) followed by a 4-byte transaction sequence number. This property is available only for Message Queuing version 2.0 and later. Transaction identifiers are not guaranteed to be unique, because transaction sequence numbers are not persistent, and they start over again at 2 20. Message Queuing guarantees only that subsequent transactions will have different transaction sequence numbers. - You can use the property along with the and properties to verify transaction boundaries. + You can use the property along with the and properties to verify transaction boundaries. ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -2696,7 +2696,7 @@ if (myObject is float) { property identifies the transactional queue on the source computer that receives read-receipt acknowledgments from connector applications. Message Queuing sets the property, and connector applications use the property when retrieving transactional messages sent to foreign queues. + The property identifies the transactional queue on the source computer that receives read-receipt acknowledgments from connector applications. Message Queuing sets the property, and connector applications use the property when retrieving transactional messages sent to foreign queues. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Message Queuing communicates with such queues through a connector application. @@ -2705,7 +2705,7 @@ if (myObject is float) { ## Examples - The following code example displays the value of a message's property. + The following code example displays the value of a message's property. @@ -2763,7 +2763,7 @@ if (myObject is float) { property specifies whether the message needs to be authenticated. If the sending application requests authentication, Message Queuing creates a digital signature and uses it to sign the message when it is sent and authenticate the message when it is received. + The property specifies whether the message needs to be authenticated. If the sending application requests authentication, Message Queuing creates a digital signature and uses it to sign the message when it is sent and authenticate the message when it is received. If is `false` and a message is sent to a queue that accepts only authenticated messages, the message will be rejected when it reaches the queue. @@ -2832,7 +2832,7 @@ if (myObject is float) { ## Examples - The following code example gets and sets the value of a message's property. + The following code example gets and sets the value of a message's property. @@ -2889,7 +2889,7 @@ if (myObject is float) { ## Examples - The following code example gets and sets the value of a message's property. + The following code example gets and sets the value of a message's property. @@ -2950,7 +2950,7 @@ if (myObject is float) { ## Examples - The following code example gets and sets the value of a message's property. + The following code example gets and sets the value of a message's property. @@ -3002,14 +3002,14 @@ if (myObject is float) { property specifies whether to track the route of a message as it moves toward its destination queue. If `true`, a report message (generated by Message Queuing) is sent to a report queue each time the message passes through a Message Queuing routing server. The report queue is specified by the source Queue Manager. Report queues are not limited to report messages generated by Message Queuing; your application-generated messages can also be sent to report queues. + The property specifies whether to track the route of a message as it moves toward its destination queue. If `true`, a report message (generated by Message Queuing) is sent to a report queue each time the message passes through a Message Queuing routing server. The report queue is specified by the source Queue Manager. Report queues are not limited to report messages generated by Message Queuing; your application-generated messages can also be sent to report queues. Using tracing involves setting up Active Directory and specifying a report queue for the Message Queuing enterprise. The administrator configures these settings. ## Examples - The following code example gets and sets the value of a message's property. + The following code example gets and sets the value of a message's property. diff --git a/xml/System.Messaging/MessageEnumerator.xml b/xml/System.Messaging/MessageEnumerator.xml index 2f61d40ef5e..c205dbd2fa9 100644 --- a/xml/System.Messaging/MessageEnumerator.xml +++ b/xml/System.Messaging/MessageEnumerator.xml @@ -38,7 +38,7 @@ Because the enumerator is dynamic, a message that is appended beyond the cursor's current position (for example, due to low priority), can be accessed by the enumerator. A message that is inserted before the cursor's current position cannot be accessed. It is not possible to step backward with a . A cursor allows forward-only movement. The method enables you to place the cursor back at the beginning of the queue. - Instances of for a given queue work independently. You can create two instances that apply to the same queue. The changes that one makes to the messages in the queue will be reflected immediately in a second enumerator if the second enumerator is positioned before the first. However, if two enumerators have the same position and one of them removes the message at that position, an exception is thrown if the other enumerator attempts to get the value of the property on the now-deleted message. + Instances of for a given queue work independently. You can create two instances that apply to the same queue. The changes that one makes to the messages in the queue will be reflected immediately in a second enumerator if the second enumerator is positioned before the first. However, if two enumerators have the same position and one of them removes the message at that position, an exception is thrown if the other enumerator attempts to get the value of the property on the now-deleted message. > [!NOTE] > If you create an instance of with set to `true`, no other application can modify the messages in your enumerator while you have the connection to the queue. @@ -46,7 +46,7 @@ ## Examples - The following example gets a dynamic list of messages in a queue and counts all messages with the property set to . + The following example gets a dynamic list of messages in a queue and counts all messages with the property set to . :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetMessageEnumerator/CPP/mqgetmessageenumerator.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageEnumerator/Overview/mqgetmessageenumerator.cs" id="Snippet1"::: diff --git a/xml/System.Messaging/MessagePriority.xml b/xml/System.Messaging/MessagePriority.xml index 461e3aa0940..1a43910ad8c 100644 --- a/xml/System.Messaging/MessagePriority.xml +++ b/xml/System.Messaging/MessagePriority.xml @@ -17,26 +17,26 @@ Specifies the priority Message Queuing applies to a message while it is en route to a queue, and when inserting the message into the destination queue. - enumeration is used by the class's property. This property affects how Message Queuing handles the message both while it is en route and once it reaches its destination. Higher-priority messages are given preference during routing and inserted toward the front of the destination queue. Messages with the same priority are placed in the queue according to their arrival time. - - When Message Queuing routes a message to a public queue, the priority level of the message is added to the priority level of the public queue (which you can access through the class's property). The priority level of the queue has no effect on how messages are placed in the queue, only on how Message Queuing handles the message while en route. - - Base priority applies only to public queues. For a private queue, the base priority is always zero. - - You can set a meaningful priority only for non-transactional messages. Message Queuing automatically sets the priority for transactional messages to `Lowest`, which causes transactional message priority to be ignored. - - - -## Examples - The following example sends two messages of different priorities to the queue, and retrieves them subsequently. - + enumeration is used by the class's property. This property affects how Message Queuing handles the message both while it is en route and once it reaches its destination. Higher-priority messages are given preference during routing and inserted toward the front of the destination queue. Messages with the same priority are placed in the queue according to their arrival time. + + When Message Queuing routes a message to a public queue, the priority level of the message is added to the priority level of the public queue (which you can access through the class's property). The priority level of the queue has no effect on how messages are placed in the queue, only on how Message Queuing handles the message while en route. + + Base priority applies only to public queues. For a private queue, the base priority is always zero. + + You can set a meaningful priority only for non-transactional messages. Message Queuing automatically sets the priority for transactional messages to `Lowest`, which causes transactional message priority to be ignored. + + + +## Examples + The following example sends two messages of different priorities to the queue, and retrieves them subsequently. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Message.DefaultPropertiesToSend/CPP/message_defaultandpriority.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/Message/.ctor/message_defaultandpriority.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Messaging/Message/.ctor/message_defaultandpriority.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Messaging/Message/.ctor/message_defaultandpriority.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Messaging/MessagePropertyFilter.xml b/xml/System.Messaging/MessagePropertyFilter.xml index 4efbb388c2b..b60a9d9dab8 100644 --- a/xml/System.Messaging/MessagePropertyFilter.xml +++ b/xml/System.Messaging/MessagePropertyFilter.xml @@ -139,12 +139,12 @@ property of the class specifies the type of acknowledgment messages requested by the sending application. The type of acknowledgment defines when acknowledgments are returned. Set the property before sending the message to request a specific type of acknowledgment. + The property of the class specifies the type of acknowledgment messages requested by the sending application. The type of acknowledgment defines when acknowledgments are returned. Set the property before sending the message to request a specific type of acknowledgment. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet1"::: @@ -191,11 +191,11 @@ property of the class specifies the type of acknowledgment messages the system posts in the administration queue, which determines when acknowledgments are generated. + The property of the class specifies the type of acknowledgment messages the system posts in the administration queue, which determines when acknowledgments are generated. Acknowledgments are returned from the destination queue and posted as messages to the specified by the original message. The type of acknowledgment generated depends on what was requested. - Read the property when receiving a message from an administration queue to verify the status of the message originally sent to the message queue. + Read the property when receiving a message from an administration queue to verify the status of the message originally sent to the message queue. @@ -248,12 +248,12 @@ property of the class specifies the name of the queue that receives system-generated acknowledgments. + The property of the class specifies the name of the queue that receives system-generated acknowledgments. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet2"::: @@ -299,12 +299,12 @@ property of the class contains additional, application-specific information. + The property of the class contains additional, application-specific information. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet3"::: @@ -350,12 +350,12 @@ property of the class indicates when the message arrived at the destination queue. This is local time, adjusted from GMT, of the computer on which the message is retrieved. + The property of the class indicates when the message arrived at the destination queue. This is local time, adjusted from GMT, of the computer on which the message is retrieved. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet4"::: @@ -402,12 +402,12 @@ property of the class specifies whether the should be or has been attached to the message. The is set by Message Queuing and is used by the receiving Queue Manager to verify whether the sender has access rights to a queue. + The property of the class specifies whether the should be or has been attached to the message. The is set by Message Queuing and is used by the receiving Queue Manager to verify whether the sender has access rights to a queue. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet5"::: @@ -453,14 +453,14 @@ property of the class is used by the receiving application to determine if authentication was requested. If authentication was requested and the message is in the queue, then the message is authenticated. + The property of the class is used by the receiving application to determine if authentication was requested. If authentication was requested and the message is in the queue, then the message is authenticated. It is not possible to look at the properties of a message and determine whether a message failed authentication. Messages that fail authentication are discarded and are not delivered to the queue. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet6"::: @@ -506,14 +506,14 @@ property of the class specifies the name of the cryptographic provider used to generate the digital signature of the message. is typically used when working with foreign queues. + The property of the class specifies the name of the cryptographic provider used to generate the digital signature of the message. is typically used when working with foreign queues. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Microsoft Message Queuing communicates with such queues through a connector application. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet7"::: @@ -561,14 +561,14 @@ property of the class specifies the type of cryptographic provider used to generate the digital signature of the message. is typically used when working with foreign queues. + The property of the class specifies the type of cryptographic provider used to generate the digital signature of the message. is typically used when working with foreign queues. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Microsoft Message Queuing communicates with such queues through a connector application. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet8"::: @@ -614,12 +614,12 @@ property of the class represents the serialized contents of the message. The body can contain up to 4 MB of data. + The property of the class represents the serialized contents of the message. The body can contain up to 4 MB of data. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet9"::: @@ -735,16 +735,16 @@ property of the class is required when an application sets a message property that is typically set by Message Queuing. It is used in the following two instances: + The property of the class is required when an application sets a message property that is typically set by Message Queuing. It is used in the following two instances: - When a message is passed by a connector application, the is required for the sending and receiving applications to interpret the security and acknowledgment properties of the message. -- When sending application-encrypted messages, the property informs Message Queuing to use the symmetric key. +- When sending application-encrypted messages, the property informs Message Queuing to use the symmetric key. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet10"::: @@ -790,7 +790,7 @@ property of the class specifies a message identifier that is used by acknowledgment and report messages to reference the original message. It provides an application-defined identifier that the receiving application can use to sort messages. + The property of the class specifies a message identifier that is used by acknowledgment and report messages to reference the original message. It provides an application-defined identifier that the receiving application can use to sort messages. @@ -841,12 +841,12 @@ property of the class represents the serialized contents of the message. The body can contain up to 4 MB of data. Restricting the body size can improve performance. + The default body size specifies the number of bytes to allocate for the message's body contents. The property of the class represents the serialized contents of the message. The body can contain up to 4 MB of data. Restricting the body size can improve performance. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet11"::: @@ -893,12 +893,12 @@ property of the class represents the additional, application-defined information associated with the message, such as a binary large object. It is the responsibility of the application to interpret the contents of the . + The default extension size specifies the number of bytes to allocate for the message's extension. The property of the class represents the additional, application-defined information associated with the message, such as a binary large object. It is the responsibility of the application to interpret the contents of the . ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet12"::: @@ -945,12 +945,12 @@ property of the class specifies the label of the message. + The default label size specifies the number of bytes to allocate for the message's label. The property of the class specifies the label of the message. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet13"::: @@ -998,12 +998,12 @@ property of the class identifies the original destination queue of the message. It is typically used to determine the original destination of a message that is in a journal or dead-letter queue. It can also be used when sending a response message back to a response queue. + The property of the class identifies the original destination queue of the message. It is typically used to determine the original destination of a message that is in a journal or dead-letter queue. It can also be used when sending a response message back to a response queue. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet14"::: @@ -1049,14 +1049,14 @@ property of the class specifies the symmetric key used to encrypt the message. It is required when you send application-encrypted messages, or when you send encrypted messages to a foreign queue. + The property of the class specifies the symmetric key used to encrypt the message. It is required when you send application-encrypted messages, or when you send encrypted messages to a foreign queue. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Microsoft Message Queuing communicates with such queues through a connector application. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet15"::: @@ -1102,12 +1102,12 @@ property of the class specifies the digital signature used to authenticate the message. In most cases, it is generated and set by Message Queuing when the sending application requests authentication. + The property of the class specifies the digital signature used to authenticate the message. In most cases, it is generated and set by Message Queuing when the sending application requests authentication. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet16"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet16"::: @@ -1154,12 +1154,12 @@ property of the class specifies the algorithm used to encrypt the message body of a private message. + If a message is private, it is encrypted before it is sent and decrypted when it is received. The property of the class specifies the algorithm used to encrypt the message body of a private message. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet17"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet17"::: @@ -1205,12 +1205,12 @@ property of the class provides for additional application-defined information that is associated with the message, like a large binary object. It is the responsibility of the receiving application to interpret the contents of the . + The property of the class provides for additional application-defined information that is associated with the message, like a large binary object. It is the responsibility of the receiving application to interpret the contents of the . ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet18"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet18"::: @@ -1257,12 +1257,12 @@ property of the class identifies the hashing algorithm Message Queuing uses when authenticating messages. The hashing algorithm is also used when creating a digital signature for a message. + The property of the class identifies the hashing algorithm Message Queuing uses when authenticating messages. The hashing algorithm is also used when creating a digital signature for a message. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet19"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet19"::: @@ -1310,12 +1310,12 @@ property of the class indicates the Message Queuing-generated unique identifier of the message. This identifier is generated when the message is sent. + The property of the class indicates the Message Queuing-generated unique identifier of the message. This identifier is generated when the message is sent. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet20"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet20"::: @@ -1361,12 +1361,12 @@ property of the class is used by receiving applications to verify whether a message is the first message sent in a single transaction to a single queue. + The property of the class is used by receiving applications to verify whether a message is the first message sent in a single transaction to a single queue. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet50"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet50"::: @@ -1414,12 +1414,12 @@ property of the class is used by receiving applications to verify whether a message is the last message sent from a single transaction to a single queue. + The property of the class is used by receiving applications to verify whether a message is the last message sent from a single transaction to a single queue. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet51"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet51"::: @@ -1467,12 +1467,12 @@ property of the class specifies the label of the message. + The property of the class specifies the label of the message. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet21"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet21"::: @@ -1518,7 +1518,7 @@ property of the class specifies the lookup identifier of the message. + The property of the class specifies the lookup identifier of the message. ]]> @@ -1560,12 +1560,12 @@ property of the class identifies the type of the message. A message can be a normal message, a positive or negative acknowledgment message, or a report message. + The property of the class identifies the type of the message. A message can be a normal message, a positive or negative acknowledgment message, or a report message. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet22"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet22"::: @@ -1611,7 +1611,7 @@ property of the class affects how Message Queuing handles the message while it is en route, as well as where the message is placed in the queue when it reaches its destination. + The property of the class affects how Message Queuing handles the message while it is en route, as well as where the message is placed in the queue when it reaches its destination. Message priority can only be set meaningfully for non-transactional messages. The priority for transactional messages is automatically set to zero, which causes transactional message priority to be ignored. @@ -1665,14 +1665,14 @@ property of the class indicates whether delivery of a message is guaranteed, even if a computer crashes while the message is en route to the destination queue. + The property of the class indicates whether delivery of a message is guaranteed, even if a computer crashes while the message is en route to the destination queue. If delivery of a message is guaranteed, the message is stored locally at every step until the message is successfully forwarded to the next computer. Setting to `true` on the message could affect the throughput. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet23"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet23"::: @@ -1718,14 +1718,14 @@ property of the class identifies the queue that receives application-generated response messages that are sent back to the sending application by the receiving application. Response queues are specified by the sending application when the application sends its messages. Any available queue can be specified as a response queue. + The property of the class identifies the queue that receives application-generated response messages that are sent back to the sending application by the receiving application. Response queues are specified by the sending application when the application sends its messages. Any available queue can be specified as a response queue. Messages returned to the response queue are application-specific. The application must define what is in the messages as well as what is to be done when a message is received. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet24"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet24"::: @@ -1771,12 +1771,12 @@ property of the class specifies the security certificate used to authenticate messages. + The property of the class specifies the security certificate used to authenticate messages. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet25"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet25"::: @@ -1822,12 +1822,12 @@ property of the class is used primarily by the receiving queue manager when authenticating a message. The property is set by Message Queuing and is used by the queue manager to verify who sent the message and that the sender has access rights to the receiving queue. + The property of the class is used primarily by the receiving queue manager when authenticating a message. The property is set by Message Queuing and is used by the queue manager to verify who sent the message and that the sender has access rights to the receiving queue. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet26"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet26"::: @@ -1874,14 +1874,14 @@ property of the class specifies the version of Message Queuing used to send the message. The property is important to be aware of when using features like transaction processing, which is only supported by Message Queuing version 2.0 and later, or digital signatures, which are used to authenticate messages sent by version 1.0. + The property of the class specifies the version of Message Queuing used to send the message. The property is important to be aware of when using features like transaction processing, which is only supported by Message Queuing version 2.0 and later, or digital signatures, which are used to authenticate messages sent by version 1.0. is set by the sending queue manager when the message is sent. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet27"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet27"::: @@ -1929,12 +1929,12 @@ property of the class indicates the sending machine's date and time when the message was sent by the source Queue Manager. + The property of the class indicates the sending machine's date and time when the message was sent by the source Queue Manager. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet28"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet28"::: @@ -2045,7 +2045,7 @@ ||255| ||255| - The property represents a on which has been called. + The property represents a on which has been called. @@ -2097,12 +2097,12 @@ property of the class specifies the computer where the message originated. + The property of the class specifies the computer where the message originated. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet29"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet29"::: @@ -2148,12 +2148,12 @@ property of the class specifies the total time in seconds for a sent message to be received from the destination queue. The time limit for the message to be retrieved from the target queue includes the time spent getting to the destination queue, plus the time spent waiting in the queue before the message is retrieved by an application. + The property of the class specifies the total time in seconds for a sent message to be received from the destination queue. The time limit for the message to be retrieved from the target queue includes the time spent getting to the destination queue, plus the time spent waiting in the queue before the message is retrieved by an application. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet30"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet30"::: @@ -2200,12 +2200,12 @@ property of the class specifies a time limit in seconds from the time the message is sent for it to reach the destination queue. + The property of the class specifies a time limit in seconds from the time the message is sent for it to reach the destination queue. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet31"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet31"::: @@ -2252,12 +2252,12 @@ property of the class identifies the transaction that sent the message. Use this property within a receiving application to verify that a message was sent as part of a specific transaction. + The property of the class identifies the transaction that sent the message. Use this property within a receiving application to verify that a message was sent as part of a specific transaction. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet52"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet52"::: @@ -2305,14 +2305,14 @@ property of the class identifies the transaction status queue on the source computer. The property is used for sending acknowledgment messages back to the sending application. The transaction status queue is used by connector applications when receiving transactional messages sent to a foreign queue. + The property of the class identifies the transaction status queue on the source computer. The property is used for sending acknowledgment messages back to the sending application. The transaction status queue is used by connector applications when receiving transactional messages sent to a foreign queue. A foreign queue exists in a queuing system other than Microsoft Message Queuing. Microsoft Message Queuing communicates with such queues through a connector application. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet53"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet53"::: @@ -2359,14 +2359,14 @@ property of the class specifies whether the message needs to be authenticated. + The property of the class specifies whether the message needs to be authenticated. It is not possible to look at the properties of a message and determine whether a message failed authentication. Messages that fail authentication are discarded and are not delivered to the queue. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet32"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet32"::: @@ -2413,12 +2413,12 @@ property of the class specifies whether a copy of a message that could not be delivered should be sent to a dead-letter queue. + The property of the class specifies whether a copy of a message that could not be delivered should be sent to a dead-letter queue. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet33"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet33"::: @@ -2464,12 +2464,12 @@ property of the class specifies whether to encrypt a message. + The property of the class specifies whether to encrypt a message. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet34"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet34"::: @@ -2515,12 +2515,12 @@ property of the class specifies whether a copy of the message should be kept in a machine journal on the originating computer. + The property of the class specifies whether a copy of the message should be kept in a machine journal on the originating computer. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet35"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet35"::: @@ -2566,14 +2566,14 @@ property of the class specifies whether to track the route of a message as it moves toward its destination queue. If `true`, each time the original message passes through a Message Queuing routing server, a Message Queuing-generated report message is sent to the system report queue. + The property of the class specifies whether to track the route of a message as it moves toward its destination queue. If `true`, each time the original message passes through a Message Queuing routing server, a Message Queuing-generated report message is sent to the system report queue. Using tracing involves setting up Active Directory and specifying a report queue for the Message Queuing enterprise. These settings are configured by the administrator. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessagePropertyFilter/CPP/class1.cpp" id="Snippet36"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessagePropertyFilter/.ctor/class1.cs" id="Snippet36"::: diff --git a/xml/System.Messaging/MessageQueue.xml b/xml/System.Messaging/MessageQueue.xml index da574cf5e95..5877ca3f43e 100644 --- a/xml/System.Messaging/MessageQueue.xml +++ b/xml/System.Messaging/MessageQueue.xml @@ -72,7 +72,7 @@ Unlike , and are `static` members, so you can call them without creating a new instance of the class. - You can set the object's property with one of three names: the friendly name, the , or the . The friendly name, which is defined by the queue's and properties, is \\ for a public queue, and \\`Private$`\\ for a private queue. The property allows offline access to message queues. Lastly, you can use the queue's property to set the queue's . + You can set the object's property with one of three names: the friendly name, the , or the . The friendly name, which is defined by the queue's and properties, is \\ for a public queue, and \\`Private$`\\ for a private queue. The property allows offline access to message queues. Lastly, you can use the queue's property to set the queue's . For a list of initial property values for an instance of , see the constructor. @@ -136,7 +136,7 @@ class that is not immediately tied to a queue on the Message Queuing server. Before using this instance, you must connect it to an existing Message Queuing queue by setting the property. Alternatively, you can set the reference to the method's return value, thereby creating a new Message Queuing queue. + Use this overload to create a new instance of the class that is not immediately tied to a queue on the Message Queuing server. Before using this instance, you must connect it to an existing Message Queuing queue by setting the property. Alternatively, you can set the reference to the method's return value, thereby creating a new Message Queuing queue. The constructor instantiates a new instance of the class; it does not create a new Message Queuing queue. @@ -188,7 +188,7 @@ instance to a particular Message Queuing queue, for which you know the path, format name, or label. If you want to grant exclusive access to the first application that references the queue, you must set the property to `true` or use the constructor that passes a read-access restriction parameter. + Use this overload when you want to tie the new instance to a particular Message Queuing queue, for which you know the path, format name, or label. If you want to grant exclusive access to the first application that references the queue, you must set the property to `true` or use the constructor that passes a read-access restriction parameter. The constructor instantiates a new instance of the class; it does not create a new Message Queuing queue. To create a new queue in Message Queuing, use . @@ -504,7 +504,7 @@ When you set to `true`, you are restricting access to the queue on the server, not only to this instance. All clients working against the same Message Queuing queue will be affected. - A queue that accepts only authenticated messages will reject a non-authenticated message. To request notification of message rejection, a sending application can set the property of the message. Because no other indication of message rejection exists, the sending application can lose the message unless you request that it be sent to the dead-letter queue. + A queue that accepts only authenticated messages will reject a non-authenticated message. To request notification of message rejection, a sending application can set the property of the message. Because no other indication of message rejection exists, the sending application can lose the message unless you request that it be sent to the dead-letter queue. The following table shows whether this property is available in various Workgroup modes. @@ -518,7 +518,7 @@ ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet3"::: @@ -563,9 +563,9 @@ property to confer a higher or lower priority to all messages sent to the specified queue than those sent to other queues. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. + A message queue's base priority specifies how a message en route to that queue is treated as it travels through the network. You can set the property to confer a higher or lower priority to all messages sent to the specified queue than those sent to other queues. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. - A message queue's is not related to the property of a message, which specifies the order in which an incoming message is placed in the queue. + A message queue's is not related to the property of a message, which specifies the order in which an incoming message is placed in the queue. applies only to public queues whose paths are specified using the format name. The base priority of a private queue is always zero (0). @@ -581,7 +581,7 @@ ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet4"::: @@ -639,7 +639,7 @@ Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. If is `false`, the completion event is raised, but an exception will be thrown when calling . @@ -711,7 +711,7 @@ Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. @@ -781,7 +781,7 @@ is also raised if a message already exists in the queue. - Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can access this information by looking at the property of the that is associated with the operation. + Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can access this information by looking at the property of the that is associated with the operation. To use , create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. initiates an asynchronous peek operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or by retrieving the result using the . @@ -791,7 +791,7 @@ Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. @@ -873,7 +873,7 @@ Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + returns a that identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. @@ -952,7 +952,7 @@ Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - returns a that identifies the asynchronous operation started by the method. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. + returns a that identifies the asynchronous operation started by the method. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. @@ -1027,7 +1027,7 @@ Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. If is `false`, the completion event is raised, but an exception will be thrown when calling . @@ -1115,7 +1115,7 @@ myMessageQueue.BeginTransaction(); If is `false`, the completion event is raised, but an exception will be thrown when calling . - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. This overload specifies a time-out. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. @@ -1190,7 +1190,7 @@ myMessageQueue.BeginTransaction(); is also raised if a message already exists in the queue. - Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can detect this information by looking at the property of the that is associated with the operation. + Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. The event handler can detect this information by looking at the property of the that is associated with the operation. To use , create an event handler that processes the results of the asynchronous operation and associate it with your event delegate. initiates an asynchronous receive operation; the is notified, through the raising of the event, when a message arrives in the queue. The can then access the message by calling or retrieving the result using the . @@ -1200,7 +1200,7 @@ myMessageQueue.BeginTransaction(); Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. This overload specifies a time-out and a state object. If the interval specified by the `timeout` parameter expires, this component raises the event. Because no message exists, a subsequent call to will throw an exception. @@ -1289,7 +1289,7 @@ myMessageQueue.BeginTransaction(); Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, you use the property of the to identify the completed operation. The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. @@ -1378,7 +1378,7 @@ myMessageQueue.BeginTransaction(); Once an asynchronous operation completes, you can call or again in the event handler to keep receiving notifications. - The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. + The that returns identifies the asynchronous operation that the method started. You can use this throughout the lifetime of the operation, although you generally do not use it until is called. However, if you start several asynchronous operations, you can place their values in an array and specify whether to wait for all operations or any operation to complete. In this case, use the property of the to identify the completed operation. The state object associates state information with the operation. For example, if you call multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. @@ -1471,7 +1471,7 @@ myMessageQueue.BeginTransaction(); ## Examples - The following code example displays the value of a message queue's property. + The following code example displays the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet5"::: @@ -1536,7 +1536,7 @@ myMessageQueue.BeginTransaction(); ## Examples - The following code example displays the value of a message queue's property. + The following code example displays the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet6"::: @@ -1582,7 +1582,7 @@ myMessageQueue.BeginTransaction(); ## Remarks The queue category allows an application to categorize its queues. For example, you can place all Billing queues in one category and all Order queues in another. - The property provides access to the Message Queuing Type ID property (which is read/write), accessible through the **Queue Properties** dialog box in the Computer Management Console. You can define a new category. Although you can use to create a category value that is unique across all values, such an action is unnecessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. + The property provides access to the Message Queuing Type ID property (which is read/write), accessible through the **Queue Properties** dialog box in the Computer Management Console. You can define a new category. Although you can use to create a category value that is unique across all values, such an action is unnecessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. It is not necessary to set the . The value can be `null`. @@ -1600,7 +1600,7 @@ myMessageQueue.BeginTransaction(); ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet7"::: @@ -1699,7 +1699,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. - Create the with connection caching disabled. To do so, call the constructor and set the `enableConnectionCache` parameter to `false`. -- Disable connection caching. To do so, set the property to `false`. +- Disable connection caching. To do so, set the property to `false`. You should call for a queue before you delete the queue on the Message Queuing server. Otherwise, messages sent to the queue could throw exceptions or appear in the dead-letter queue. @@ -1773,7 +1773,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. |Public queue|`MachineName`\\`QueueName`| |Private queue|`MachineName`\\`Private$`\\`QueueName`| - Use "." for the local computer. For more syntax, see the property. + Use "." for the local computer. For more syntax, see the property. The following table shows whether this method is available in various Workgroup modes. @@ -1845,7 +1845,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. |Public queue|`MachineName`\\`QueueName`| |Private queue|`MachineName`\\`Private$`\\`QueueName`| - Use "." for the local computer. For more syntax, see the property. + Use "." for the local computer. For more syntax, see the property. The following table shows whether this method is available in various Workgroup modes. @@ -1950,7 +1950,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Examples - The following code example displays the value of a message queue's property. + The following code example displays the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet9"::: @@ -1998,7 +1998,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. to the queue, the inserts the object into a Message Queuing message. At that time, the applies to the message the property values you specify in the property. Conversely, if you send a to the queue, these properties are already specified for the instance itself, so is ignored for the . + When you send any object that is not of type to the queue, the inserts the object into a Message Queuing message. At that time, the applies to the message the property values you specify in the property. Conversely, if you send a to the queue, these properties are already specified for the instance itself, so is ignored for the . Although you set the properties through the object, the refers to the properties of the messages that are sent to the queue, not the queue itself. @@ -2088,7 +2088,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. |Public queue|`MachineName`\\`QueueName`| |Private queue|`MachineName`\\`Private$`\\`QueueName`| - For more syntax, see the property. + For more syntax, see the property. Alternatively, you can use the or to describe the queue path. @@ -2182,7 +2182,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet10"::: @@ -2274,7 +2274,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. |Remote computer and direct format name|Yes| ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet11"::: @@ -2321,7 +2321,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Setting this property modifies the Message Queuing queue. Therefore, any other instances are affected by the change. - Encrypting a message makes the message private. You can specify the queue's encryption requirement to be `None`, `Body`, or `Optional` by setting the property appropriately. The setting of the message must correspond to the encryption requirement of the queue. If the message is not encrypted but the queue specifies `Body`, or if the message is encrypted but the queue specifies `None`, the message is rejected by the queue. If the sending application requests a negative acknowledgment message in this event, Message Queuing indicates the message's rejection to the sending application. If the property is `true`, a message that fails encryption is sent to the dead-letter queue. Otherwise, the message is lost. + Encrypting a message makes the message private. You can specify the queue's encryption requirement to be `None`, `Body`, or `Optional` by setting the property appropriately. The setting of the message must correspond to the encryption requirement of the queue. If the message is not encrypted but the queue specifies `Body`, or if the message is encrypted but the queue specifies `None`, the message is rejected by the queue. If the sending application requests a negative acknowledgment message in this event, Message Queuing indicates the message's rejection to the sending application. If the property is `true`, a message that fails encryption is sent to the dead-letter queue. Otherwise, the message is lost. The following table shows whether this property is available in various Workgroup modes. @@ -2333,7 +2333,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. |Remote computer and direct format name|No| ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet12"::: @@ -2495,7 +2495,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. method determines whether a Message Queuing queue exists at a specified path. No method exists to determine whether a queue with a specified format name exists. For more information about the format name syntax and other path syntax forms, see the property.) + The method determines whether a Message Queuing queue exists at a specified path. No method exists to determine whether a queue with a specified format name exists. For more information about the format name syntax and other path syntax forms, see the property.) is an expensive operation. Use it only when it is necessary within the application. @@ -2510,7 +2510,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. cannot be called to verify the existence of a remote private queue. - For more syntax, see the property. + For more syntax, see the property. Alternatively, you can use the to describe the queue path. @@ -2580,7 +2580,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. property contains the format name of the queue. Message Queuing uses the format name to identify which queue to open and how to access it. Unlike most of a queue's characteristics, the format name is not a Message Queuing application queue property, so you cannot access it through the Message Queuing management tool. The format name is simply a unique name for the queue, which Message Queuing generates when it creates the queue or which the application generates later. + The property contains the format name of the queue. Message Queuing uses the format name to identify which queue to open and how to access it. Unlike most of a queue's characteristics, the format name is not a Message Queuing application queue property, so you cannot access it through the Message Queuing management tool. The format name is simply a unique name for the queue, which Message Queuing generates when it creates the queue or which the application generates later. If you specify a path using the path name syntax (such as `myComputer\myQueue`) rather than using the format name syntax when you read or write to the queue, the primary domain controller (which uses Active Directory) translates the into the associated before accessing the queue. If your application is working offline, you must use the format name syntax; otherwise, the primary domain controller will not be available to perform the path translation. @@ -2594,7 +2594,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. |Remote computer and direct format name|Yes| ## Examples - The following code example displays the value of a message queue's property. + The following code example displays the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet13"::: @@ -2652,17 +2652,17 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. property contains an instance of a formatter object, which transforms messages when your application reads or writes to the queue. + The property contains an instance of a formatter object, which transforms messages when your application reads or writes to the queue. - When the application sends message to the queue, the formatter serializes the object into a stream and inserts it into the message body. When reading from a queue, the formatter deserializes the message data into the property of a . + When the application sends message to the queue, the formatter serializes the object into a stream and inserts it into the message body. When reading from a queue, the formatter deserializes the message data into the property of a . The is loosely coupled, so it is not necessary to have the same object type on the sender and receiver when using this format. The and serialize the data into binary representation. The is used when sending or receiving COM components. and provide faster throughput than the . The allows interoperability with Visual Basic 6.0 Message Queuing applications. - When your application sends messages to the queue, the applies only to those messages that use the default message properties, . If you send a to the queue, Message Queuing uses the formatter defined in the property to serialize the body instead. + When your application sends messages to the queue, the applies only to those messages that use the default message properties, . If you send a to the queue, Message Queuing uses the formatter defined in the property to serialize the body instead. - The class will always use a to receive or peek a message from the queue. The message is deserialized using the property. + The class will always use a to receive or peek a message from the queue. The message is deserialized using the property. The following table shows whether this property is available in various Workgroup modes. @@ -2722,7 +2722,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. Because returns a copy of the messages in the queue at the time the method was called, the array does not reflect new messages that arrive in the queue or messages that are removed from the queue. - retrieves only those properties not filtered out by the property. + retrieves only those properties not filtered out by the property. The following table shows whether this method is available in various Workgroup modes. @@ -2824,7 +2824,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Remarks You can use a computer's identifier for two purposes, among others: to read the computer journal and to set security certificates. However, you cannot call for a remote computer when you are working offline because the application must have access to the directory service on the domain controller. - The computer identifier (or machine identifier) is a that Message Queuing creates when a computer is added to the enterprise. Message Queuing combines the computer identifier with the `Machine` and `Journal` keywords to create the machine journal's format name, which has the syntax `Machine=;Journal`. The machine journal, which is also known as the journal queue, is a system queue that stores copies of application-generated messages when the property is `true`. + The computer identifier (or machine identifier) is a that Message Queuing creates when a computer is added to the enterprise. Message Queuing combines the computer identifier with the `Machine` and `Journal` keywords to create the machine journal's format name, which has the syntax `Machine=;Journal`. The machine journal, which is also known as the journal queue, is a system queue that stores copies of application-generated messages when the property is `true`. This syntax for the journal is only valid when constructing the format name for the queue. The path name syntax is `MachineName`\\`Journal$`. @@ -3285,7 +3285,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. property provides access to the Message Queuing type ID property (which is read/write) of a particular queue. Although you can use to create a category value that is unique across all values, it is not necessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. + Use this method to filter the public queues by category. The property provides access to the Message Queuing type ID property (which is read/write) of a particular queue. Although you can use to create a category value that is unique across all values, it is not necessary. The category value needs to be distinct only from other categories, not from all other values. For example, you can assign {00000000-0000-0000-0000-000000000001} as the for one set of queues and {00000000-0000-0000-0000-000000000002} as the for another set. retrieves a static snapshot of the queues. To interact with a dynamic list of the queues, use . You can specify the category as part of the you pass into the method. @@ -3491,7 +3491,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. property when it creates the queue. This property is only available for public queues. + Message Queuing sets the property when it creates the queue. This property is only available for public queues. The following table shows whether this property is available in various Workgroup modes. @@ -3505,7 +3505,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Examples - The following code example displays the value of a message queue's property. + The following code example displays the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet15"::: @@ -3629,7 +3629,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Remarks The maximum length of a message queue label is 124 characters. - The property does not need to be unique across all queues. However, if multiple queues share the same , you cannot use the method to broadcast a message to all of them. If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. + The property does not need to be unique across all queues. However, if multiple queues share the same , you cannot use the method to broadcast a message to all of them. If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. The following table shows whether this property is available in various Workgroup modes. @@ -3643,7 +3643,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet18"::: @@ -3691,9 +3691,9 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. property that modifies the Message Queuing queue, such as . The value of the property represents the system time of the local computer. + The last modification time includes when the queue was created and any property that modifies the Message Queuing queue, such as . The value of the property represents the system time of the local computer. - You must call before getting the property; otherwise, the modification time associated with this might not be current. + You must call before getting the property; otherwise, the modification time associated with this might not be current. The following table shows whether this property is available in various Workgroup modes. @@ -3707,7 +3707,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Examples - The following code example displays the value of a message queue's property. + The following code example displays the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet19"::: @@ -3767,11 +3767,11 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. |Machine dead-letter queue|`MachineName`\\`Deadletter$`| |Machine transactional dead-letter queue|`MachineName`\\`XactDeadletter$`| - Use "." for the local computer when specifying the . Only the computer name is recognized for this property, for example, `Server0`. The property does not support the IP address format. + Use "." for the local computer when specifying the . Only the computer name is recognized for this property, for example, `Server0`. The property does not support the IP address format. If you define the in terms of the , the application throws an exception when working offline because the domain controller is required for path translation. Therefore, you must use the for the syntax when working offline. - The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. If the property is empty, the is set to the Journal queue of the computer you specify. + The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. If the property is empty, the is set to the Journal queue of the computer you specify. The following table shows whether this property is available in various Workgroup modes. @@ -3785,7 +3785,7 @@ myMessageQueue.Send("Text 2."); //Resources are re-acquired. ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet20"::: @@ -3857,7 +3857,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet21"::: @@ -3926,7 +3926,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet22"::: @@ -3978,7 +3978,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks This filter is a set of Boolean values restricting the message properties that the receives or peeks. When the receives or peeks a message from the server queue, it retrieves only those properties for which the value is `true`. - The following shows initial property values for the property. These settings are identical to calling on a . + The following shows initial property values for the property. These settings are identical to calling on a . |Property|Default value| |--------------|-------------------| @@ -4090,13 +4090,13 @@ The name of the computer is not valid, possibly because the syntax is incorrect. property is used to associate a non-transactional queue with a multicast address that can be used when sending messages. You cannot associate a transactional queue with a multicast address. When the sending application sends messages to a multicast address, Message Queuing sends a copy of the message to every queue associated with that address. + The property is used to associate a non-transactional queue with a multicast address that can be used when sending messages. You cannot associate a transactional queue with a multicast address. When the sending application sends messages to a multicast address, Message Queuing sends a copy of the message to every queue associated with that address. IP multicast addresses must be in the class D range from 224.0.0.0 to 239.255.255.255, which corresponds to setting the first four high-order bits equal to 1110. However, only certain ranges of addresses in this range are unreserved and available for sending multicast messages. For the latest list of reserved multicast addresses, see the [Internet Assigned Number Authority (IANA) Internet Multicast Addresses](https://go.microsoft.com/fwlink/?linkid=3859) Web page. There are no restrictions on the port number. If several source computers are sending multicast messages and you want a specific queue to receive messages from only one source computer, each source computer must send messages to a different combination of IP address and port number. - To dissociate a queue from a multicast address, set the property to a zero-length string. Do not set it to `null`, as this will result in a . + To dissociate a queue from a multicast address, set the property to a zero-length string. Do not set it to `null`, as this will result in a . The following table shows whether this property is available in various Workgroup modes. @@ -4186,7 +4186,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. property depends on the type of queue it points to, as shown in the following table. + The syntax for the property depends on the type of queue it points to, as shown in the following table. |Queue type|Syntax| |----------------|------------| @@ -4199,7 +4199,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Use "." to represent the local computer. - The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. + The , , and properties are related. Changing the property causes the property to change. It is built from the new and the . Changing the (for example, to use the format name syntax) resets the and properties to refer to the new queue. Alternatively, you can use the or to describe the queue path, as shown in the following table. @@ -4208,7 +4208,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. |Format name|`FormatName:` [ *format name* ]|`FormatName:Public=` 5A5F7535-AE9A-41d4-935C-845C2AFF7112| |Label|`Label:` [ *label* ]|`Label:` TheLabel| - If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. + If you use the label syntax for the property when you send the message, an exception will be thrown if the is not unique. To work offline, you must use the format name syntax, rather than the friendly name syntax in the first table. Otherwise, an exception is thrown because the primary domain controller (on which Active Directory resides) is not available to resolve the path to the format name. @@ -4482,7 +4482,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks This method looks in the queue referenced by the for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. Two other methods allow you to peek messages in a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. @@ -4548,7 +4548,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. Two other methods allow you to peek messages in a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. @@ -4756,7 +4756,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this method to read a message with a known lookup identifier without removing it from the queue. This method throws an exception immediately if the message is not in the queue. - The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. + The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. To read a message with a specified lookup identifier and remove it from the queue, use the method. @@ -4819,7 +4819,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this method to read a message with a known lookup identifier without removing it from the queue. This method throws an exception immediately if the message is not in the queue. - The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. + The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. To read a message with a specified identifier and remove it from the queue, use the method. @@ -4919,7 +4919,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. property. Messages that are purged from the queue are lost; they are not sent to the dead-letter queue or the journal queue. + Purging the queue causes Message Queuing to set the queue modification flag, which affects the property. Messages that are purged from the queue are lost; they are not sent to the dead-letter queue or the journal queue. The following table shows whether this method is available in various Workgroup modes. @@ -4983,7 +4983,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. with the to create a friendly name for the queue. The syntax for the friendly name variation of the property depends on the type of queue, as shown in the following table. + You can combine the with the to create a friendly name for the queue. The syntax for the friendly name variation of the property depends on the type of queue, as shown in the following table. |Queue type|Syntax| |----------------|------------| @@ -4993,7 +4993,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Use "." to represent the local computer. - Changing the property affects the property. If you set the without setting the property, the property becomes .\\`QueueName`. Otherwise, the becomes `MachineName`\\`QueueName`. + Changing the property affects the property. If you set the without setting the property, the property becomes .\\`QueueName`. Otherwise, the becomes `MachineName`\\`QueueName`. The following table shows whether this property is available in various Workgroup modes. @@ -5007,7 +5007,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet24"::: @@ -5723,7 +5723,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks This method looks in the non-transactional queue referenced by the for a message whose matches the specified `correlationId` parameter. If no message is found that matches the `correlationID` parameter, an exception is thrown. Otherwise, the message is removed from the queue and returned to the application. - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method retrieves a message by specifying its unique identifier. @@ -5791,7 +5791,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. @@ -5870,7 +5870,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. @@ -5940,7 +5940,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `correlationId` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `correlationId` parameter. - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. @@ -6016,7 +6016,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. @@ -6102,7 +6102,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. - The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. + The property is used to tie a message sent to the queue to associated response, report, or acknowledgment messages. Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve a message by specifying its unique identifier. @@ -6182,7 +6182,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this method to read a message with a known identifier and remove it from the queue. This method throws an exception immediately if the message is not in the queue. - The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. + The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. Two other methods allow you to receive messages from a queue. The method returns the first message in the queue, and the method is used to retrieve an acknowledgment, report, or application-generated response message that was created as a result of a message sent to the queue. @@ -6247,7 +6247,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this method to read a message with a known identifier and remove it from the queue, using the internal transaction context defined by the `transaction` parameter. This method throws an exception immediately if the message is not in the queue - The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. + The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. @@ -6326,7 +6326,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. If the message with the specified identifier is in a queue other than the one associated with this instance, the message will not be found. + The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. If the message with the specified identifier is in a queue other than the one associated with this instance, the message will not be found. If this method is called to receive a message from a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. @@ -6398,7 +6398,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. - The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. + The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. @@ -6474,7 +6474,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The `timeout` parameter does not specify the total running time for this method. Rather, it specifies the time to wait for a new message to arrive in the queue. Each time a new message arrives, this method examines the of the new message to see if it matches the `id` parameter. If not, this method starts the time-out period over and waits for another new message to arrive. Therefore, if new messages continue to arrive within the time-out period, it is possible for this method to continue running indefinitely, either until the time-out period expires without any new messages arriving, or until a message arrives whose matches the `id` parameter. - The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. + The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the timeout period specified by the `timeout` parameter. @@ -6564,7 +6564,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. Specify `Automatic` for the `transactionType` parameter if there is already an external transaction context attached to the thread that you want to use to receive the message. Specify `Single` if you want to receive the message as a single internal transaction. You can specify `None` if you want to receive a message from a transactional queue outside of a transaction context. - The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. If the message with the specified identifier is in a queue other than the one associated with this instance, the message will not be found. + The property of a message is unique across the Message Queuing enterprise, so there will be at most one message in the queue that matches the given `id` parameter. If the message with the specified identifier is in a queue other than the one associated with this instance, the message will not be found. Use this overload of when it is acceptable for the current thread to be blocked as long as new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. The thread will be blocked for at least the given period of time, or indefinitely if you specified the value for the `timeout` parameter, or if new messages continue to arrive in the queue within the time-out period specified by the `timeout` parameter. @@ -6646,7 +6646,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this method to read a message with a known lookup identifier and remove it from the queue. This method throws an exception immediately if the message is not in the queue. - The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. + The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. To read a message with a specified lookup identifier without removing it from the queue, use the method. @@ -6711,7 +6711,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this method to read a message with a known lookup identifier and remove it from the queue, using a transaction context defined by the `transaction` parameter. This method throws an exception immediately if the message is not in the queue. - The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. + The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. Because this method is called on a transactional queue, the message that is received would be returned to the queue if the transaction is aborted. The message is not permanently removed from the queue until the transaction is committed. @@ -6783,7 +6783,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Remarks Use this method to read a message with a known lookup identifier and remove it from the queue, using a transaction context defined by the `transactionType` parameter. This method throws an exception immediately if the message is not in the queue. - The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. + The property of a message is unique to the queue where the message resides, so there will be at most one message in the queue that matches the given `lookupId` parameter. To read a message with a specified identifier without removing it from the queue, use the method. There is no transaction context associated with a message returned by a call to . Because does not remove any messages from the queue, there would be nothing to roll back if the transaction were aborted. @@ -7010,9 +7010,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If you use this overload to send a message to a transactional queue, the message will be sent to the dead-letter queue. If you want the message to be part of a transaction that contains other messages, use an overload that takes a or as a parameter. - If you do not set the property before calling , the formatter defaults to the . + If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -7083,9 +7083,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If you use this overload to send a message to a non-transactional queue, the message might be sent to the dead-letter queue without throwing an exception. - If you do not set the property before calling , the formatter defaults to the . + If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. @@ -7167,9 +7167,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The object you send to the queue can be a or any managed object. If you send any object other than a , the object is serialized and inserted into the body of the message. - If you do not set the property before calling , the formatter defaults to the . + If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -7241,9 +7241,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If you use this overload to send a message to a transactional queue, the message will be sent to the dead-letter queue. If you want the message to be part of a transaction that contains other messages, use an overload that takes a or as a parameter. - The property for this instance must be specified before you send the message. If you do not set the property before calling , the formatter defaults to the . + The property for this instance must be specified before you send the message. If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -7316,9 +7316,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. If you use this overload to send a message to a non-transactional queue, the message might be sent to the dead-letter queue without throwing an exception. - If you do not set the property before calling , the formatter defaults to the . + If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over and the message's property takes precedence over the queue's property is threading apartment aware, so if your apartment state is `STA`, you cannot use the transaction in multiple threads. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. You apply the by using the following fragment. @@ -7408,9 +7408,9 @@ The name of the computer is not valid, possibly because the syntax is incorrect. The message label is distinct from the message queue label, but both are application-dependent and have no inherit meaning to Message Queuing. - If you do not set the property before calling , the formatter defaults to the . + If you do not set the property before calling , the formatter defaults to the . - The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over , and the message's property takes precedence over the queue's property. + The property applies to any object other than a . If you specify, for example, a label or a priority using the member, these values apply to any message that contains an object that is not of type when your application sends it to the queue. When sending a , the property values set for the take precedence over , and the message's property takes precedence over the queue's property. The following table shows whether this method is available in various Workgroup modes. @@ -7964,7 +7964,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example displays the value of a message queue's property. + The following code example displays the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet27"::: @@ -8032,7 +8032,7 @@ The name of the computer is not valid, possibly because the syntax is incorrect. ## Examples - The following code example gets and sets the value of a message queue's property. + The following code example gets and sets the value of a message queue's property. :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/.ctor/class1.cs" id="Snippet28"::: diff --git a/xml/System.Messaging/MessageQueueAccessControlEntry.xml b/xml/System.Messaging/MessageQueueAccessControlEntry.xml index ea6d89b6e83..d5c43d15ba6 100644 --- a/xml/System.Messaging/MessageQueueAccessControlEntry.xml +++ b/xml/System.Messaging/MessageQueueAccessControlEntry.xml @@ -29,7 +29,7 @@ The class is associated with security based on access control lists (ACLs), which you can use to give users access to the Message Queuing system itself. This is different from code access security, which is implemented through the and related classes. Message Queuing code access security defines queue-specific operations or queue access that an application might require that is subject to security control; it does not represent a right for the application to perform these operations or receive access in and of itself. See the topic [Code Access Security](/dotnet/framework/misc/code-access-security) for more information about code access security. - To set message queue permissions for a trustee, create a new instance of the class and pass it into an overload of the constructor. Specify the message queue access rights either by passing an instance of into the constructor or by setting the property on an existing instance. + To set message queue permissions for a trustee, create a new instance of the class and pass it into an overload of the constructor. Specify the message queue access rights either by passing an instance of into the constructor or by setting the property on an existing instance. You can then pass the instance directly to the method, or alternately add the entry to an instance of before calling . @@ -77,7 +77,7 @@ bitflag, which includes such rights as receiving messages, deleting queues, and setting queue properties. The constructor uses the rights you pass in to set this instance's property. + Use this overload of the constructor to grant rights to the specified trustee. The rights you specify in the `rights` parameter are a bitwise combination of members of the bitflag, which includes such rights as receiving messages, deleting queues, and setting queue properties. The constructor uses the rights you pass in to set this instance's property. Pass this instance of directly into an overload of the method to grant rights only to this trustee, or add this instance to a before calling to grant or deny rights to multiple trustees at once. @@ -117,7 +117,7 @@ bitflag, which includes such rights as receiving messages, deleting queues, and setting queue properties. The constructor uses the rights you pass in to set this instance's property. + Use this overload of the constructor to grant or deny rights to the specified trustee. The rights you specify in the `rights` parameter are a bitwise combination of members of the bitflag, which includes such rights as receiving messages, deleting queues, and setting queue properties. The constructor uses the rights you pass in to set this instance's property. For more information about granting or denying rights, see the topic. For two members, `Allow` and `Deny`, there may be preexisting and possibly contradictory access rights, so the order in which the rights appear in the queue's discretionary access control list (DACL) affects whether the right is ultimately granted. Two other members, `Set` and `Revoke`, overwrite any existing rights. Use the member whose behavior is applicable to your application. @@ -155,7 +155,7 @@ property enables you to specify Message Queuing object-specific rights such as receiving, peeking, or writing messages, or setting queue properties. The value of this property is set by the constructor, but you can change it at any time before using this instance of in a call to . + The property enables you to specify Message Queuing object-specific rights such as receiving, peeking, or writing messages, or setting queue properties. The value of this property is set by the constructor, but you can change it at any time before using this instance of in a call to . ]]> diff --git a/xml/System.Messaging/MessageQueueCriteria.xml b/xml/System.Messaging/MessageQueueCriteria.xml index 3888a85d3ef..c6947870b34 100644 --- a/xml/System.Messaging/MessageQueueCriteria.xml +++ b/xml/System.Messaging/MessageQueueCriteria.xml @@ -18,28 +18,28 @@ Filters message queues when performing a query using the class's method. - class provides a number of methods that enable you to filter your search for public queues on the network. Specific methods for filtering by queue label, category, or server location are the , , and . - - The class, when used with the method, allows you to refine your filter. You can specify search criteria not specifically addressed through one of the `GetPublicQueuesBy`* methods, or by multiple criteria. You can pass a instance into the method in order to search, for example, by queue creation or modification times, the computer the queue resides on, the queue label or category, or any combination of these properties. - - When filtering by multiple properties, the criteria are composed by applying the `AND` operator to the set of properties. Thus, when you specify a value for the property together with the property, you are asking for all queues that were created after a specified time and that reside on a specific computer. - - When you set any property, the method that sets the property also sets a flag to indicate that it should be included in the filter you are building. You cannot remove individual properties from the search filter. Instead, you remove all properties from the filter by calling , and then set the properties that you do want to build into the search filter. resets all properties into a "not set" default state. - - You must set a property before trying to read it; otherwise, an exception is thrown. - - - -## Examples - The following example iterates through message queues and displays the path of each queue that was created in the last day and that exists on the computer "MyComputer". - + class provides a number of methods that enable you to filter your search for public queues on the network. Specific methods for filtering by queue label, category, or server location are the , , and . + + The class, when used with the method, allows you to refine your filter. You can specify search criteria not specifically addressed through one of the `GetPublicQueuesBy`* methods, or by multiple criteria. You can pass a instance into the method in order to search, for example, by queue creation or modification times, the computer the queue resides on, the queue label or category, or any combination of these properties. + + When filtering by multiple properties, the criteria are composed by applying the `AND` operator to the set of properties. Thus, when you specify a value for the property together with the property, you are asking for all queues that were created after a specified time and that reside on a specific computer. + + When you set any property, the method that sets the property also sets a flag to indicate that it should be included in the filter you are building. You cannot remove individual properties from the search filter. Instead, you remove all properties from the filter by calling , and then set the properties that you do want to build into the search filter. resets all properties into a "not set" default state. + + You must set a property before trying to read it; otherwise, an exception is thrown. + + + +## Examples + The following example iterates through message queues and displays the path of each queue that was created in the last day and that exists on the computer "MyComputer". + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.GetMessageQueueEnumerator_criteria/CPP/mqgetmessagequeueenumerator_criteria.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/GetMessageQueueEnumerator/mqgetmessagequeueenumerator_criteria.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/GetMessageQueueEnumerator/mqgetmessagequeueenumerator_criteria.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/GetMessageQueueEnumerator/mqgetmessagequeueenumerator_criteria.vb" id="Snippet1"::: + ]]> @@ -88,13 +88,13 @@ Gets or sets the category by which to filter queues in the network. The queues' category. - property is application-defined and has no intrinsic meaning to Message Queuing. - - If you are filtering only by category when searching the queues on the network, you can use the method , which is specifically designed for this purpose. If you are searching by multiple criteria that include the category, set this property and pass the parameter into . - + property is application-defined and has no intrinsic meaning to Message Queuing. + + If you are filtering only by category when searching the queues on the network, you can use the method , which is specifically designed for this purpose. If you are searching by multiple criteria that include the category, set this property and pass the parameter into . + ]]> The application did not set the property before reading it. @@ -124,13 +124,13 @@ Clears all properties from being built into a filter and puts all property values into a "not set" state. - , the method sets flags related to each of the properties, which indicate that no properties are to be included when the application creates the search filter. resets all properties that currently have values into a "not set" default state. Any properties that you subsequently change are combined using the logical `AND` operator to define a new filter for the method. When you change the property, the method that sets the property also sets a flag to indicate that it should be included in the filter you are building. - - You cannot remove individual properties from the search filter. Instead, you remove all properties from the filter by calling , and then set the properties that you do want to build into the search filter. - + , the method sets flags related to each of the properties, which indicate that no properties are to be included when the application creates the search filter. resets all properties that currently have values into a "not set" default state. Any properties that you subsequently change are combined using the logical `AND` operator to define a new filter for the method. When you change the property, the method that sets the property also sets a flag to indicate that it should be included in the filter you are building. + + You cannot remove individual properties from the search filter. Instead, you remove all properties from the filter by calling , and then set the properties that you do want to build into the search filter. + ]]> @@ -156,13 +156,13 @@ Gets or sets the lower boundary of the queue creation date and time by which to filter queues on the network. A that specifies the lower boundary for a queue's creation date and time. - properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' creation. If you set only , there is no upper boundary on the date. - - If you try to set to a later value than , is reset to the same (new) value as . - + properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' creation. If you set only , there is no upper boundary on the date. + + If you try to set to a later value than , is reset to the same (new) value as . + ]]> The application did not set the property before reading it. @@ -192,13 +192,13 @@ Gets or sets the upper boundary of the queue creation date and time by which to filter queues on the network. A that specifies the upper boundary for a queue's creation date and time. - properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' creation. If you set only , there is no lower boundary on the date. - - If you try to set to an earlier value than , is reset to the same (new) value as . - + properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' creation. If you set only , there is no lower boundary on the date. + + If you try to set to an earlier value than , is reset to the same (new) value as . + ]]> The application did not set the property before reading it. @@ -228,13 +228,13 @@ Gets or sets the label by which to filter queues in the network. The queues' label. - , which is specifically designed for this purpose. If you are searching by multiple criteria that include the label, set this property and pass the parameter into . - + , which is specifically designed for this purpose. If you are searching by multiple criteria that include the label, set this property and pass the parameter into . + ]]> The application did not set the property before reading it. @@ -264,21 +264,21 @@ Gets or sets the computer name by which to filter queues in the network. The server name of the computer on which the queues reside. - reflects the name of the server on which the queue resides, without preceding backslashes (\\\\). - - If you are filtering only by computer name when searching the queues on the network, you can use the method , which is specifically designed for this purpose. If you are searching by multiple criteria that include the computer name, set this property and pass the parameter into . - - You can also search for private queues on the network by specifying a computer name in the method. - + reflects the name of the server on which the queue resides, without preceding backslashes (\\\\). + + If you are filtering only by computer name when searching the queues on the network, you can use the method , which is specifically designed for this purpose. If you are searching by multiple criteria that include the computer name, set this property and pass the parameter into . + + You can also search for private queues on the network by specifying a computer name in the method. + ]]> - The application did not set the property before reading it. - - -or- - + The application did not set the property before reading it. + + -or- + The computer name syntax is invalid. @@ -306,15 +306,15 @@ Gets or sets the lower boundary of the queue modification date and time by which to filter queues on the network. A that specifies the lower boundary for a queue's last modification date and time. - properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' last modification. If you set only , there is no upper boundary on the date. - - If you try to set to a later value than , is reset to the same (new) value as . - + properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' last modification. If you set only , there is no upper boundary on the date. + + If you try to set to a later value than , is reset to the same (new) value as . + ]]> The application did not set the property before reading it. @@ -344,15 +344,15 @@ Gets or sets the upper boundary of the queue modification date and time by which to filter queues on the network. A that specifies the upper boundary for a queue's last modification date and time. - properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' last modification. If you set only , there is no lower boundary on the date. - - If you try to set to an earlier value than , is reset to the same (new) value as . - + properties are combined using a logical `AND`, so setting both and bounds a time interval for the queues' last modification. If you set only , there is no lower boundary on the date. + + If you try to set to an earlier value than , is reset to the same (new) value as . + ]]> The application did not set the property before reading it. diff --git a/xml/System.Messaging/MessageQueueEnumerator.xml b/xml/System.Messaging/MessageQueueEnumerator.xml index cbd667b2704..ea80bea867f 100644 --- a/xml/System.Messaging/MessageQueueEnumerator.xml +++ b/xml/System.Messaging/MessageQueueEnumerator.xml @@ -301,7 +301,7 @@ For more information, see [Finalize Methods and Destructors](https://learn.micro ## Remarks returns `false` immediately if there are no queues associated with the enumeration. - will return `true` until it has reached the end of the collection. It will then return `false` for each successive call. However once has returned `false`, accessing the property will throw an exception. + will return `true` until it has reached the end of the collection. It will then return `false` for each successive call. However once has returned `false`, accessing the property will throw an exception. Upon creation, an enumerator is conceptually positioned before the first of the enumeration, and the first call to brings the first queue of the enumeration into view. diff --git a/xml/System.Messaging/MessageQueueErrorCode.xml b/xml/System.Messaging/MessageQueueErrorCode.xml index 55fe37b6351..ef650e8b32d 100644 --- a/xml/System.Messaging/MessageQueueErrorCode.xml +++ b/xml/System.Messaging/MessageQueueErrorCode.xml @@ -17,20 +17,20 @@ Identifies the source of an error that occurred within the Message Queuing application and generated a exception. - uses the property to identify the nature of the Message Queuing error. The `MessageQueueErrorCode` value determines a text string to associate with the error. - -## Examples - The following example verifies whether a Message Queuing queue exists, and then deletes it. - + uses the property to identify the nature of the Message Queuing error. The `MessageQueueErrorCode` value determines a text string to associate with the error. + +## Examples + The following example verifies whether a Message Queuing queue exists, and then deletes it. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ExistsDelete/CPP/mqexistsdelete.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Delete/mqexistsdelete.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/Delete/mqexistsdelete.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/Delete/mqexistsdelete.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Messaging/MessageQueueException.xml b/xml/System.Messaging/MessageQueueException.xml index 051dc718064..1d0556e0b36 100644 --- a/xml/System.Messaging/MessageQueueException.xml +++ b/xml/System.Messaging/MessageQueueException.xml @@ -28,25 +28,25 @@ The exception that is thrown if a Microsoft Message Queuing internal error occurs. - class are generated by internal errors within Message Queuing that should be dealt with through your code. - - Every exception consists of an error code and a text string that describes the source of the error. See the class for a list of these error codes and their descriptions. - - If a opens a queue with the `sharedModeDenyReceive` parameter set to true, any that subsequently tries to read from the queue generates a exception because of a sharing violation. The same exception is thrown if a tries to access the queue in exclusive mode while another already has nonexclusive access to the queue. - -> **alert tag is not supported!!!!** -> is threading-apartment-aware. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. - - - -## Examples + class are generated by internal errors within Message Queuing that should be dealt with through your code. + + Every exception consists of an error code and a text string that describes the source of the error. See the class for a list of these error codes and their descriptions. + + If a opens a queue with the `sharedModeDenyReceive` parameter set to true, any that subsequently tries to read from the queue generates a exception because of a sharing violation. The same exception is thrown if a tries to access the queue in exclusive mode while another already has nonexclusive access to the queue. + +> **alert tag is not supported!!!!** +> is threading-apartment-aware. Visual Basic sets the state of the main thread to `STA`, so you must apply the in the `Main` subroutine. Otherwise, sending a transactional message using another thread throws a exception. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ExistsDelete/CPP/mqexistsdelete.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/Delete/mqexistsdelete.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/Delete/mqexistsdelete.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/Delete/mqexistsdelete.vb" id="Snippet1"::: + ]]> @@ -140,11 +140,11 @@ Gets a value that describes the Message Queuing error. The description of the Message Queuing internal error that generated this . - property. If the method is unable to interpret the error code that Message Queuing generated, the property gets the value `UnknownError`. - + property. If the method is unable to interpret the error code that Message Queuing generated, the property gets the value `UnknownError`. + ]]> @@ -171,11 +171,11 @@ Gets a value that indicates the error code associated with this exception. A that identifies the type of error Message Queuing generated. - property contains a string associated with this that more fully describes the source of the error. - + property contains a string associated with this that more fully describes the source of the error. + ]]> diff --git a/xml/System.Messaging/MessageQueueInstaller.xml b/xml/System.Messaging/MessageQueueInstaller.xml index a93ee52f526..e2e56c3188f 100644 --- a/xml/System.Messaging/MessageQueueInstaller.xml +++ b/xml/System.Messaging/MessageQueueInstaller.xml @@ -206,7 +206,7 @@ ## Remarks The queue category enables an application to categorize associated queues according to the way they are used. The can be a null reference. You can also define a new category. - The property provides access to the Message Queuing type identifier property, which is associated with a particular queue and is read/write. You can use the method to create a category value that is guaranteed to be unique across all values. However, it is necessary only for the category value to be distinct from other categories, not from all other values. For example, you can set the for one group of queues to {00000000-0000-0000-0000-000000000001} and the for another group to {00000000-0000-0000-0000-000000000002}. + The property provides access to the Message Queuing type identifier property, which is associated with a particular queue and is read/write. You can use the method to create a category value that is guaranteed to be unique across all values. However, it is necessary only for the category value to be distinct from other categories, not from all other values. For example, you can set the for one group of queues to {00000000-0000-0000-0000-000000000001} and the for another group to {00000000-0000-0000-0000-000000000002}. ]]> @@ -241,7 +241,7 @@ ## Remarks Typically, you do not call the methods of the from within your code; they are generally called only by the installutil.exe installation utility. The utility automatically calls the method during the installation process. Installation is transactional, so if there is a failure of any installation project component during the installation, all the previously installed components are rolled back to their pre-installation states. This is accomplished by calling each component's method. - After a successful installation of all the components that are associated with the installation project has occurred, the installation utility commits the installations. completes the installation of the by setting the queue to the appropriate initial state. If the queue specified by the property already exists and contains messages, clears the messages. , rather than , clears the messages because the act of purging the messages cannot be rolled back. + After a successful installation of all the components that are associated with the installation project has occurred, the installation utility commits the installations. completes the installation of the by setting the queue to the appropriate initial state. If the queue specified by the property already exists and contains messages, clears the messages. , rather than , clears the messages because the act of purging the messages cannot be rolled back. An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `savedState` parameter, is continuously updated as the utility commits each instance. Usually, it is not necessary for your code to explicitly modify this state information. When the queue has been cleared, posts a log entry to the `savedState` that is associated with the installation. @@ -281,7 +281,7 @@ ## Remarks Typically, you do not call the methods of the from within your code; they are generally called only by the installutil.exe installation utility. is used by the installation utility to set the property values for the to the values of an existing . - If the of the that is passed in is an empty string (""), you must set the property to a non-empty value before the installer executes. + If the of the that is passed in is an empty string (""), you must set the property to a non-empty value before the installer executes. ]]> @@ -351,14 +351,14 @@ method writes message queue information to the registry, and associates the instance with a queue that is located at the path specified by the property. If the queue does not already exist, creates a transactional queue. sets the new or existing queue properties to those that you have specified in the . If the queue already exists, its properties are reset to those of the . If the existing queue is not transactional, it is deleted and then recreated as a transactional queue. + The method writes message queue information to the registry, and associates the instance with a queue that is located at the path specified by the property. If the queue does not already exist, creates a transactional queue. sets the new or existing queue properties to those that you have specified in the . If the queue already exists, its properties are reset to those of the . If the existing queue is not transactional, it is deleted and then recreated as a transactional queue. > [!CAUTION] > If it is necessary to recreate the queue, messages in the queue will be lost. Typically, you do not call the methods of the from within your code; they are generally called only by the installutil.exe installation utility. The utility automatically calls the method during the installation process to write registry information that is associated with the message queue being installed. Installation is transactional, so if there is a failure of any installation project component during the installation, all the previously installed components are rolled back to their pre-installation states. This is accomplished by calling each component's method. - After a successful installation of all the components that are associated with the installation project has occurred, the installation utility commits the installations. completes the installation of the by setting the queue to the appropriate initial state. If the queue specified by the property already exists and contains messages, clears the messages. , rather than , clears the messages because the act of purging the messages cannot be rolled back. + After a successful installation of all the components that are associated with the installation project has occurred, the installation utility commits the installations. completes the installation of the by setting the queue to the appropriate initial state. If the queue specified by the property already exists and contains messages, clears the messages. , rather than , clears the messages because the act of purging the messages cannot be rolled back. An application's install routine uses the project installer's to automatically maintain information about the components that have already been installed. This state information, which is passed to as the `stateSaver` parameter, is continuously updated as the utility installs each instance. Usually, it is not necessary for your code to explicitly modify this state information. @@ -435,7 +435,7 @@ property does not need to be unique across queues. + The property does not need to be unique across queues. ]]> @@ -607,7 +607,7 @@ property depends on the type of queue it references. The following table shows the syntax you should use for queues of various types. + The syntax for the property depends on the type of queue it references. The following table shows the syntax you should use for queues of various types. |Queue type|Syntax| |----------------|------------| @@ -674,7 +674,7 @@ ## Remarks By default, the creator of a public or private queue has full control, and the domain group Everyone has permission to get queue properties, get permissions, and write to the queue. Message Queuing accesses each permission list entry in turn until it finds one that applies to the current user and the current attempted action. As with the operating system permissions, the rights that you specifically deny to a user take precedence over those you allow. - When you construct the property, add instances to your collection. When you construct each access control entry, you can specify generic or standard access rights. The rights to a queue can be any combination of the following: + When you construct the property, add instances to your collection. When you construct each access control entry, you can specify generic or standard access rights. The rights to a queue can be any combination of the following: - Delete diff --git a/xml/System.Messaging/MessageQueuePermission.xml b/xml/System.Messaging/MessageQueuePermission.xml index 78f2c72a130..c1103cbcde3 100644 --- a/xml/System.Messaging/MessageQueuePermission.xml +++ b/xml/System.Messaging/MessageQueuePermission.xml @@ -28,13 +28,13 @@ Allows control of code access permissions for messaging. - and demonstrates the use of the property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet0"::: - + and demonstrates the use of the property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet0"::: + ]]> @@ -70,13 +70,13 @@ Initializes a new instance of the class. - . - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet1"::: - + . + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet1"::: + ]]> @@ -102,13 +102,13 @@ An array of objects. The property is set to this value. Initializes a new instance of the class with the specified permission access level entries. - . - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet4"::: - + . + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet4"::: + ]]> @@ -134,13 +134,13 @@ One of the values. Initializes a new instance of the class with the specified permission state. - . - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet5"::: - + . + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet5"::: + ]]> @@ -169,13 +169,13 @@ The path of the queue that is referenced by the . Initializes a new instance of the class with the specified access levels and the path of the queue. - . - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet2"::: - + . + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet2"::: + ]]> @@ -207,13 +207,13 @@ The queue category (Message Queuing type identifier). Initializes a new instance of the class with the specified access levels, computer to use, queue description, and queue category. - . - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet3"::: - + . + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet3"::: + ]]> @@ -372,13 +372,13 @@ Gets the collection of permission entries for this permissions request. A that contains the permission entries for this permissions request. - and gets the value of its property. - - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet6"::: - + and gets the value of its property. + + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermission/Overview/class1.cs" id="Snippet6"::: + ]]> diff --git a/xml/System.Messaging/MessageQueuePermissionAttribute.xml b/xml/System.Messaging/MessageQueuePermissionAttribute.xml index aa16bb1116b..91f5f896f39 100644 --- a/xml/System.Messaging/MessageQueuePermissionAttribute.xml +++ b/xml/System.Messaging/MessageQueuePermissionAttribute.xml @@ -28,19 +28,19 @@ Allows declarative permission checks. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionAttribute/cpp/class1.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet0"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet0"::: + ]]> @@ -71,14 +71,14 @@ One of the values. Initializes a new instance of the class. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionAttribute/cpp/class1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet1"::: + ]]> @@ -105,14 +105,14 @@ Gets or sets the queue category. The queue category (Message Queuing type identifier), which allows an application to categorize its queues. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionAttribute/cpp/class1.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet2"::: + ]]> The value is . @@ -140,14 +140,14 @@ Creates the permission based on the requested access levels, category, label, computer name, and path that are set through the , , , , and properties on the attribute. A that represents the created permission. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionAttribute/cpp/class1.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet7"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet7"::: + ]]> @@ -173,14 +173,14 @@ Gets or sets the queue description. The label for the message queue. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionAttribute/cpp/class1.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet3"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet3"::: + ]]> The value is . @@ -207,14 +207,14 @@ Gets or sets the name of the computer where the Message Queuing queue is located. The name of the computer where the queue is located. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionAttribute/cpp/class1.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet4"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet4"::: + ]]> The value is . @@ -241,14 +241,14 @@ Gets or sets the queue's path. The queue that is referenced by the . - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionAttribute/cpp/class1.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet5"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet5"::: + ]]> The value is . @@ -275,14 +275,14 @@ Gets or sets the permission access levels used in the permissions request. A bitwise combination of the values. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionAttribute/cpp/class1.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet6"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionAttribute/Overview/class1.cs" id="Snippet6"::: + ]]> diff --git a/xml/System.Messaging/MessageQueuePermissionEntry.xml b/xml/System.Messaging/MessageQueuePermissionEntry.xml index ffd4feb2a83..c5a1f0fe0a8 100644 --- a/xml/System.Messaging/MessageQueuePermissionEntry.xml +++ b/xml/System.Messaging/MessageQueuePermissionEntry.xml @@ -24,19 +24,19 @@ Defines the smallest unit of a code access security permission set for messaging. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntry/cpp/class1.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet0"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet0"::: + ]]> @@ -78,14 +78,14 @@ The path of the queue that is referenced by the object. The property is set to this value. Initializes a new instance of the class with the specified permission access levels and the path of the queue. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntry/cpp/class1.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet1"::: + ]]> @@ -117,14 +117,14 @@ The queue category (Message Queuing type identifier). The property is set to this value. Initializes a new instance of the class with the specified permission access levels, the name of the computer where the queue is located, the queue description, and the queue category. - . - + . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntry/cpp/class1.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet2"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet2"::: + ]]> @@ -150,14 +150,14 @@ Gets the queue category. The queue category (Message Queuing type identifier), which allows an application to categorize its queues. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntry/cpp/class1.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet3"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet3"::: + ]]> @@ -183,14 +183,14 @@ Gets the queue description. The label for the message queue. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntry/cpp/class1.cpp" id="Snippet4"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet4"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet4"::: + ]]> @@ -216,14 +216,14 @@ Gets the name of the computer where the Message Queuing queue is located. The name of the computer where the queue is located. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntry/cpp/class1.cpp" id="Snippet5"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet5"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet5"::: + ]]> @@ -249,14 +249,14 @@ Gets the queue's path. The queue that is referenced by the . - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntry/cpp/class1.cpp" id="Snippet6"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet6"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet6"::: + ]]> @@ -282,14 +282,14 @@ Gets the permission access levels used in the permissions request. A bitwise combination of the values. - property. - + property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueuePermissionEntry/cpp/class1.cpp" id="Snippet7"::: - :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet7"::: - + :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueuePermissionEntry/Overview/class1.cs" id="Snippet7"::: + ]]> diff --git a/xml/System.Messaging/MessageQueueTransaction.xml b/xml/System.Messaging/MessageQueueTransaction.xml index d85680c2408..cbea40a5896 100644 --- a/xml/System.Messaging/MessageQueueTransaction.xml +++ b/xml/System.Messaging/MessageQueueTransaction.xml @@ -67,7 +67,7 @@ property to `Initialized`. + This constructor sets the property to `Initialized`. ]]> diff --git a/xml/System.Messaging/MessageQueueTransactionStatus.xml b/xml/System.Messaging/MessageQueueTransactionStatus.xml index 1e4e01e7e68..2cb7f55de07 100644 --- a/xml/System.Messaging/MessageQueueTransactionStatus.xml +++ b/xml/System.Messaging/MessageQueueTransactionStatus.xml @@ -17,11 +17,11 @@ Specifies the state of an internal Message Queuing transaction. - class has been created, its property is set by the constructor to `Initialized`. After a transaction has begun, but before it is committed or rolled back, the is `Pending`. - + class has been created, its property is set by the constructor to `Initialized`. After a transaction has begun, but before it is committed or rolled back, the is `Pending`. + ]]> diff --git a/xml/System.Messaging/MessageType.xml b/xml/System.Messaging/MessageType.xml index f669f7a1c50..25da18c08c9 100644 --- a/xml/System.Messaging/MessageType.xml +++ b/xml/System.Messaging/MessageType.xml @@ -17,15 +17,15 @@ Identifies the type of a message. A message can be a typical Message Queuing message, a positive (arrival and read) or negative (arrival and read) acknowledgment message, or a report message. - class or any overload of the method. - - Message Queuing generates acknowledgment messages whenever the sending application requests one. If you send a message using the class, you can use its property to specify the types of acknowledgments to receive. For example, Message Queuing can generate positive or negative messages to indicate that the original message arrived or was read. Message Queuing returns the appropriate acknowledgment message to the administration queue specified by the sending application. When you receive or peek an acknowledgment message using a , its property indicates the reason Message Queuing sent the acknowledgment. - - Message Queuing generates report messages whenever a report queue is defined at the source queue manager. When tracing is enabled (by setting the property on the original message), Message Queuing sends a report message to the Message Queuing report queue each time the original message enters or leaves a Message Queuing server. - + class or any overload of the method. + + Message Queuing generates acknowledgment messages whenever the sending application requests one. If you send a message using the class, you can use its property to specify the types of acknowledgments to receive. For example, Message Queuing can generate positive or negative messages to indicate that the original message arrived or was read. Message Queuing returns the appropriate acknowledgment message to the administration queue specified by the sending application. When you receive or peek an acknowledgment message using a , its property indicates the reason Message Queuing sent the acknowledgment. + + Message Queuing generates report messages whenever a report queue is defined at the source queue manager. When tracing is enabled (by setting the property on the original message), Message Queuing sends a report message to the Message Queuing report queue each time the original message enters or leaves a Message Queuing server. + ]]> diff --git a/xml/System.Messaging/MessagingDescriptionAttribute.xml b/xml/System.Messaging/MessagingDescriptionAttribute.xml index 431e0e85c9e..ad16a310618 100644 --- a/xml/System.Messaging/MessagingDescriptionAttribute.xml +++ b/xml/System.Messaging/MessagingDescriptionAttribute.xml @@ -24,11 +24,11 @@ Specifies a description for a property or event. - property to get or set the text associated with this attribute. - + property to get or set the text associated with this attribute. + ]]> @@ -57,11 +57,11 @@ The application-defined description text. Initializes a new instance of the class, using the specified description. - constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies - + constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies + ]]> diff --git a/xml/System.Messaging/PeekCompletedEventArgs.xml b/xml/System.Messaging/PeekCompletedEventArgs.xml index 6880fb409b4..860207defb4 100644 --- a/xml/System.Messaging/PeekCompletedEventArgs.xml +++ b/xml/System.Messaging/PeekCompletedEventArgs.xml @@ -18,24 +18,24 @@ Provides data for the event. When your asynchronous peek operation calls an event handler, an instance of this class is passed to the handler. - to begin the asynchronous processing. When a message is peeked, your application is notified through the event. An instance of is passed into the event delegate that calls your event handler. The data associated with the event is contained in the delegate's parameter. - - There are two ways to provide notification of event completion: event notification and callbacks. is used only with event notification. For information comparing callbacks and event notification, see "Events vs. Callbacks" on MSDN. - - provides access to the message that initiated the end of the asynchronous peek operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . - - - -## Examples - The following code example creates an event handler for the event and associates it with the event delegate by using the . The event handler, `MyPeekCompleted`, peeks a message and writes its label to the screen. - + to begin the asynchronous processing. When a message is peeked, your application is notified through the event. An instance of is passed into the event delegate that calls your event handler. The data associated with the event is contained in the delegate's parameter. + + There are two ways to provide notification of event completion: event notification and callbacks. is used only with event notification. For information comparing callbacks and event notification, see "Events vs. Callbacks" on MSDN. + + provides access to the message that initiated the end of the asynchronous peek operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . + + + +## Examples + The following code example creates an event handler for the event and associates it with the event delegate by using the . The event handler, `MyPeekCompleted`, peeks a message and writes its label to the screen. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.BeginPeek_noparms/CPP/mqbeginpeek_noparms.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_noparms.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_noparms.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/BeginPeek/mqbeginpeek_noparms.vb" id="Snippet1"::: + ]]> @@ -67,13 +67,13 @@ Gets or sets the result of the asynchronous operation requested. A that contains the data associated with the peek operation. - identifies ongoing or completed asynchronous operations. The property contains data that helps determine which of several potential asynchronous operations to complete, and when passed to the event handler, enables to access the message associated with the completed operation. - - When you call , a is returned immediately, even though a message, if one exists, has not yet been retrieved because the operation is not completed. The indicates the state of the asynchronous operation. creates the object, which is modified throughout the operation until completes it. - + identifies ongoing or completed asynchronous operations. The property contains data that helps determine which of several potential asynchronous operations to complete, and when passed to the event handler, enables to access the message associated with the completed operation. + + When you call , a is returned immediately, even though a message, if one exists, has not yet been retrieved because the operation is not completed. The indicates the state of the asynchronous operation. creates the object, which is modified throughout the operation until completes it. + ]]> @@ -102,13 +102,13 @@ Gets the message associated with the asynchronous peek operation. A that represents the end result of the asynchronous peek operation. - property provides a means for retrieving the message that initiated the end of the asynchronous peek operation. - - is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. - + property provides a means for retrieving the message that initiated the end of the asynchronous peek operation. + + is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. + ]]> The could not be retrieved. The time-out on the asynchronous operation might have expired. diff --git a/xml/System.Messaging/ReceiveCompletedEventArgs.xml b/xml/System.Messaging/ReceiveCompletedEventArgs.xml index 69923643393..c9c9f01862d 100644 --- a/xml/System.Messaging/ReceiveCompletedEventArgs.xml +++ b/xml/System.Messaging/ReceiveCompletedEventArgs.xml @@ -18,24 +18,24 @@ Provides data for the event. When your asynchronous receive operation calls an event handler, an instance of this class is passed to the handler. - to begin the asynchronous processing. When a message is received, your application is notified through the event. An instance of is passed into the event delegate that calls your event handler. The data associated with the event is contained in the delegate's parameter. - - There are two ways to provide notification of event completion: event notification and callbacks. is used only with event notification. For information comparing callbacks and event notification, see "Events vs. Callbacks" on MSDN. - - provides access to the message that initiated the end of the asynchronous receive operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . - - - -## Examples - The following code example creates an event handler for the event and associates it with the event delegate by using the . The event handler, `MyReceiveCompleted`, receives a message from a queue and writes its body to the screen. - + to begin the asynchronous processing. When a message is received, your application is notified through the event. An instance of is passed into the event delegate that calls your event handler. The data associated with the event is contained in the delegate's parameter. + + There are two ways to provide notification of event completion: event notification and callbacks. is used only with event notification. For information comparing callbacks and event notification, see "Events vs. Callbacks" on MSDN. + + provides access to the message that initiated the end of the asynchronous receive operation, through the member. This is an alternate access to the message, and behaves much the same as a call to . + + + +## Examples + The following code example creates an event handler for the event and associates it with the event delegate by using the . The event handler, `MyReceiveCompleted`, receives a message from a queue and writes its body to the screen. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/MessageQueue.ReceiveCompleted/CPP/mqreceivecompletedeventhandler.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Messaging/MessageQueue/ReceiveCompleted/mqreceivecompletedeventhandler.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/ReceiveCompleted/mqreceivecompletedeventhandler.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Messaging/MessageQueue/ReceiveCompleted/mqreceivecompletedeventhandler.vb" id="Snippet1"::: + ]]> @@ -67,13 +67,13 @@ Gets or sets the result of the asynchronous operation requested. A that contains the data associated with the receive operation. - identifies ongoing or completed asynchronous operations. The property contains data that helps determine which of several potential asynchronous operations to complete, and when passed to the event handler, enables to access the message associated with the completed operation. - - When you call , a is returned immediately, even though a message, if one exists, has not yet been retrieved because the operation is not completed. The indicates the state of the asynchronous operation. creates the object, which is modified throughout the operation until completes it. - + identifies ongoing or completed asynchronous operations. The property contains data that helps determine which of several potential asynchronous operations to complete, and when passed to the event handler, enables to access the message associated with the completed operation. + + When you call , a is returned immediately, even though a message, if one exists, has not yet been retrieved because the operation is not completed. The indicates the state of the asynchronous operation. creates the object, which is modified throughout the operation until completes it. + ]]> @@ -102,13 +102,13 @@ Gets the message associated with the asynchronous receive operation. A that represents the end result of the asynchronous receive operation. - property provides a means for retrieving the message that initiated the end of the asynchronous receive operation. - - is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. - + property provides a means for retrieving the message that initiated the end of the asynchronous receive operation. + + is called the first time the property is read, so it is not necessary to call prior to getting the value of this property. + ]]> The could not be retrieved. The time-out on the asynchronous operation might have expired. diff --git a/xml/System.Messaging/Trustee.xml b/xml/System.Messaging/Trustee.xml index 73ceeeeb06d..22d473759a9 100644 --- a/xml/System.Messaging/Trustee.xml +++ b/xml/System.Messaging/Trustee.xml @@ -18,13 +18,13 @@ Specifies a user account, group account, or logon session to which an access control entry applies. - member (either directly or using the constructor) to specify whether the trustee is a user, computer, or other type. If you do not specify the trustee type before setting permissions for the trustee, the type defaults to `Unknown`. - - You must specify a value for the property before using the to set permissions. The contains the name of the user, group, or computer account to which the new access rights will be assigned. Optionally, you can set the property to identify the name of the system on which the trustee account is looked up to resolve the name's security identifier. If you do not specify a value for , the local computer looks up the account name. - + member (either directly or using the constructor) to specify whether the trustee is a user, computer, or other type. If you do not specify the trustee type before setting permissions for the trustee, the type defaults to `Unknown`. + + You must specify a value for the property before using the to set permissions. The contains the name of the user, group, or computer account to which the new access rights will be assigned. Optionally, you can set the property to identify the name of the system on which the trustee account is looked up to resolve the name's security identifier. If you do not specify a value for , the local computer looks up the account name. + ]]> @@ -58,11 +58,11 @@ Initializes a new instance of the class without setting any of its read/write properties. - property before using the instance to set permissions. Optionally, you can set the property to identify the name of the system on which the trustee account is looked up to resolve the name's security identifier. If you do not specify a value for , the local computer looks up the account name. - + property before using the instance to set permissions. Optionally, you can set the property to identify the name of the system on which the trustee account is looked up to resolve the name's security identifier. If you do not specify a value for , the local computer looks up the account name. + ]]> @@ -88,11 +88,11 @@ The value to assign to the property. Initializes a new instance of the class of type , setting the property to the value specified, and the to . - property is set to `Unknown`, but you can modify that value before using this instance of to set permissions. - + property is set to `Unknown`, but you can modify that value before using this instance of to set permissions. + ]]> The parameter is . @@ -122,11 +122,11 @@ The value to assign to the property. Initializes a new instance of the class of type , setting the and the properties to the values specified. - property is set to `Unknown`, but you can modify that value before using this instance of to set permissions. - + property is set to `Unknown`, but you can modify that value before using this instance of to set permissions. + ]]> The parameter is . @@ -159,13 +159,13 @@ A that indicates the account type of the trustee. Initializes a new instance of the class of the specified type, setting the and the properties to the values specified. - property at construction, but you can modify that value before using this instance of to set permissions. The `Unknown` trustee type (which the other overloads of the constructor set by default) should be used only when you do not know the kind of trust that is being used, but know that it is valid. - + property at construction, but you can modify that value before using this instance of to set permissions. The `Unknown` trustee type (which the other overloads of the constructor set by default) should be used only when you do not know the kind of trust that is being used, but know that it is valid. + ]]> The parameter is . @@ -195,15 +195,15 @@ Gets or sets the name of the trustee. The name of the account to which the new rights will be assigned. The default is . - property before using the to set permissions. The contains the name of the user, group, or computer account to which the new access rights will be assigned. - - If you do not specify a value for the property, the account you identify in the property is looked up on the local computer. If you do specify a , the account is looked up on the computer you specify. - - If you are not connected to the network (for example, if you are in workgroup mode), the property can be any local user or group. In this case, you should not specify any value for , as workgroup mode is local by definition. - + property before using the to set permissions. The contains the name of the user, group, or computer account to which the new access rights will be assigned. + + If you do not specify a value for the property, the account you identify in the property is looked up on the local computer. If you do specify a , the account is looked up on the computer you specify. + + If you are not connected to the network (for example, if you are in workgroup mode), the property can be any local user or group. In this case, you should not specify any value for , as workgroup mode is local by definition. + ]]> The property is . @@ -231,11 +231,11 @@ Gets or sets the computer on which to look up the trustee's account. The local or remote computer on which the account exists. The default is , which indicates that the name will be looked up on the local computer. - before you use this instance of to set permissions, but is optional. If you leave `null`, the local computer is used to look up the account you specify in the property. - + before you use this instance of to set permissions, but is optional. If you leave `null`, the local computer is used to look up the account you specify in the property. + ]]> @@ -262,13 +262,13 @@ Gets or sets the type of the trustee, which identifies whether the trustee is a user, group, computer, domain, or alias. A that indicates what type of account the trustee has on the system. The default is . - indicates what type of account the trustee is associated with on the domain controller or on the local computer. This can be, for example, a user account, a group account, or a computer account. - - If you are specifying a predefined group name for the property, such as Everyone, the is `Group`, rather than `Alias`. - + indicates what type of account the trustee is associated with on the domain controller or on the local computer. This can be, for example, a user account, a group account, or a computer account. + + If you are specifying a predefined group name for the property, such as Everyone, the is `Group`, rather than `Alias`. + ]]> The trustee type specified is not one of the enumeration members. diff --git a/xml/System.Messaging/XmlMessageFormatter.xml b/xml/System.Messaging/XmlMessageFormatter.xml index 690676d3259..5258d479ab3 100644 --- a/xml/System.Messaging/XmlMessageFormatter.xml +++ b/xml/System.Messaging/XmlMessageFormatter.xml @@ -28,9 +28,9 @@ is the default formatter that an instance of uses to serialize messages written to the queue. When you create an instance of , an instance of is created for you and associated with the . You can specify a different formatter by creating it in your code and assigning it to the property of your . + The is the default formatter that an instance of uses to serialize messages written to the queue. When you create an instance of , an instance of is created for you and associated with the . You can specify a different formatter by creating it in your code and assigning it to the property of your . - A queue's default instance can be used to write to the queue, but it cannot be used to read from the queue until you set either the or property on the formatter. You can either set one or both of these values on the default formatter instance, or you can create a new instance of the formatter and set the values automatically by passing them as arguments into the appropriate constructor. + A queue's default instance can be used to write to the queue, but it cannot be used to read from the queue until you set either the or property on the formatter. You can either set one or both of these values on the default formatter instance, or you can create a new instance of the formatter and set the values automatically by passing them as arguments into the appropriate constructor. When specifying rather than , type existence is checked at compile time rather than read time, reducing possibility for error. requires every entry to be fully qualified, specifying its assembly name. Further, when working with multiple concurrent versions, the version number must also be appended to the target type name as well. @@ -146,7 +146,7 @@ ## Remarks The constructors with target type parameters are most frequently used when reading from the queue. When writing, it is not necessary to specify target types. - This overload of the constructor sets the property to the array values passed in through the `targetTypeNames` parameter. Setting this property enables a using this instance to read messages containing objects of given types. + This overload of the constructor sets the property to the array values passed in through the `targetTypeNames` parameter. Setting this property enables a using this instance to read messages containing objects of given types. Both the and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. @@ -192,7 +192,7 @@ ## Remarks The constructors with target type parameters are most frequently used when reading from the queue. When writing, it is not necessary to specify target types. - This overload of the constructor sets the property to the array values passed in through the `targetTypes` parameter. Setting this property enables a using this instance to read messages containing objects of the given types. + This overload of the constructor sets the property to the array values passed in through the `targetTypes` parameter. Setting this property enables a using this instance to read messages containing objects of the given types. Both the and properties tell the formatter what schemas to attempt to match when deserializing a message. This allows the formatter to interpret the message body. @@ -249,7 +249,7 @@ TargetTypes = new Type[]{typeof(MyClass)} - The message was not formatted using the . -- The schema of the message body is not among those listed in either the or property. +- The schema of the message body is not among those listed in either the or property. The and properties tell the formatter what types of objects it must be able to deserialize. If any type is missing from the list, yet is found within the message, returns `false`. @@ -497,7 +497,7 @@ TargetTypes = new Type[]{typeof(MyClass)} or property is used by the formatter only when deserializing a message. + The target types need not be specified to write to the queue as they must be when reading. The or property is used by the formatter only when deserializing a message. The makes use of the class, which defines what can be serialized. Only public fields and public properties can be serialized. Structures, structures with arrays, and arrays of structures are all serializable, as long as they do not use the encoded style with the SOAP protocol. diff --git a/xml/System.Net.Cache/HttpRequestCacheLevel.xml b/xml/System.Net.Cache/HttpRequestCacheLevel.xml index 1f382bbd2a2..eb7c6d38432 100644 --- a/xml/System.Net.Cache/HttpRequestCacheLevel.xml +++ b/xml/System.Net.Cache/HttpRequestCacheLevel.xml @@ -51,7 +51,7 @@ This `BypassCache` value is the default cache behavior specified in the machine configuration file that ships with the .NET Framework. No entries are taken from caches, added to caches, or removed from caches between the client and server. - The property is used to get or set the default cache policy for instances. The property is used to get or set the default cache policy for a instance. The property is used to get or set the cache policy for a specific request. + The property is used to get or set the default cache policy for instances. The property is used to get or set the default cache policy for a instance. The property is used to get or set the cache policy for a specific request. A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the default cache policy level for this request. @@ -59,7 +59,7 @@ ## Examples The following code example sets the application domain's caching policy to Default. - + :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet2"::: ]]> diff --git a/xml/System.Net.Cache/HttpRequestCachePolicy.xml b/xml/System.Net.Cache/HttpRequestCachePolicy.xml index 78a2e57c35f..52df322d07c 100644 --- a/xml/System.Net.Cache/HttpRequestCachePolicy.xml +++ b/xml/System.Net.Cache/HttpRequestCachePolicy.xml @@ -48,9 +48,9 @@ property or the application or machine configuration files. For more information, see [<requestCaching> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/requestcaching-element-network-settings). + You can specify a default cache policy for your application by using the property or the application or machine configuration files. For more information, see [<requestCaching> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/requestcaching-element-network-settings). - You can specify the cache policy for an individual request by using the property. + You can specify the cache policy for an individual request by using the property. Caching for Web services is not supported. @@ -58,7 +58,7 @@ ## Examples The following code example creates a default cache policy for the application domain, and overrides it for a request. - + :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet2"::: ]]> @@ -120,7 +120,7 @@ property to . + This constructor initializes the property to . @@ -177,7 +177,7 @@ ## Remarks The cache synchronization date allows you to specify an absolute date when cached contents must be revalidated. If the cache entry was last revalidated prior to the cache synchronization date, revalidation with the server occurs. If the cache entry was revalidated after the cache synchronization date and there are no server revalidation requirements that make the cached entry invalid, the entry from the cache is used. If the cache synchronization date is set to a future date, the entry is revalidated every time it is requested, until the cache synchronization date passes. - This constructor initializes the property to . The property is initialized to `cacheSyncDate`. + This constructor initializes the property to . The property is initialized to `cacheSyncDate`. @@ -232,7 +232,7 @@ property to `level`. + This constructor initializes the property to `level`. The value controls whether caching is enabled, and when the cache can be used. For additional information, see the documentation. @@ -291,9 +291,9 @@ , the property is set to the value of the `ageOrFreshOrStale` parameter. + The `cacheAgeControl` value defines the meaning of the `ageOrFreshOrStale` parameter value and is used to set the associated property. For example, when you specify , the property is set to the value of the `ageOrFreshOrStale` parameter. - This constructor initializes the property to . + This constructor initializes the property to . @@ -353,11 +353,11 @@ , the property is set to the value of the `freshOrStale` parameter. When you specify , the property is set using the value of the `maxAge` parameter and the property is set using the value of the `freshOrStale` parameter. + The `cacheAgeControl` value is used to interpret the meaning of the `freshOrStale` parameter value and set the associated property. For example, when you specify , the property is set to the value of the `freshOrStale` parameter. When you specify , the property is set using the value of the `maxAge` parameter and the property is set using the value of the `freshOrStale` parameter. - Note that unless you specify or , the property is not set. + Note that unless you specify or , the property is not set. - This constructor initializes the property to . + This constructor initializes the property to . @@ -419,11 +419,11 @@ , the property is set to the value of the `freshOrStale` parameter. When you specify , the property is set using the value of the `maxAge` parameter and the property is set using the value of the `freshOrStale` parameter. + The `cacheAgeControl` value is used to interpret the meaning of the `freshOrStale` parameter value and set the associated property. For example, when you specify , the property is set to the value of the `freshOrStale` parameter. When you specify , the property is set using the value of the `maxAge` parameter and the property is set using the value of the `freshOrStale` parameter. - Note that unless you specify or , the property is not set. + Note that unless you specify or , the property is not set. - This constructor initializes the property to `cacheSyncDate`, and initializes the property to . + This constructor initializes the property to `cacheSyncDate`, and initializes the property to . @@ -539,7 +539,7 @@ as their cache policy level. The property, if not `null`, determines the cache policy in effect for a request. The default policy for the application domain can be set using the property or by settings in the machine or application configuration files. For more information, see [<requestCaching> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/requestcaching-element-network-settings). + Applications typically use as their cache policy level. The property, if not `null`, determines the cache policy in effect for a request. The default policy for the application domain can be set using the property or by settings in the machine or application configuration files. For more information, see [<requestCaching> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/requestcaching-element-network-settings). diff --git a/xml/System.Net.Cache/RequestCacheLevel.xml b/xml/System.Net.Cache/RequestCacheLevel.xml index ad2fa6328ea..0dad264554d 100644 --- a/xml/System.Net.Cache/RequestCacheLevel.xml +++ b/xml/System.Net.Cache/RequestCacheLevel.xml @@ -47,11 +47,11 @@ objects. The current setting for a object is available in the property. + Members of this enumeration are used to initialize objects. The current setting for a object is available in the property. This value is the default cache behavior specified in the machine configuration file that ships with the .NET Framework. No entries are taken from caches, added to caches, or removed from caches between the client and server. - The property is used to get or set the default cache policy for instances. The property is used to get or set the default cache policy for a instances. The property is used to get or set the cache policy for a specific request. + The property is used to get or set the default cache policy for instances. The property is used to get or set the default cache policy for a instances. The property is used to get or set the cache policy for a specific request. If the cache behavior is `CacheIfAvailable` or `Revalidate`, a copy of a requested resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. With `CacheIfAvailable`, subsequent requests for the same resource would use a cached copy. With `Revalidate`, subsequent requests for the same resource would use a cached copy if the timestamp for the cached resource is the same as the timestamp of the resource on the server. @@ -59,7 +59,7 @@ A copy of a resource is only added to the cache if the response stream for the r ## Examples The following code example creates policy that returns a resource only if it is in the cache. - + :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet13"::: ]]> diff --git a/xml/System.Net.Cache/RequestCachePolicy.xml b/xml/System.Net.Cache/RequestCachePolicy.xml index 099df857bc7..53717f62cc5 100644 --- a/xml/System.Net.Cache/RequestCachePolicy.xml +++ b/xml/System.Net.Cache/RequestCachePolicy.xml @@ -48,9 +48,9 @@ property or the application or machine configuration files. For more information, see [<requestCaching> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/requestcaching-element-network-settings). + You can specify a default cache policy for your application by using the property or the application or machine configuration files. For more information, see [<requestCaching> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/requestcaching-element-network-settings). - You can specify the cache policy for an individual request by using the property. + You can specify the cache policy for an individual request by using the property. Caching for Web services is not supported. @@ -58,7 +58,7 @@ ## Examples The following code example creates a policy with set to , and uses it to set the cache policy of a . - + :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/CachePolicy/example.cs" id="Snippet13"::: ]]> @@ -120,7 +120,7 @@ property to . + This constructor initializes the property to . @@ -176,7 +176,7 @@ property to `level`. + This constructor initializes the property to `level`. The value controls whether caching is enabled, and when the cache can be used. For additional information, see the documentation. @@ -241,7 +241,7 @@ as their cache policy level. Using the level, the effective cache policy is determined by the current cache policy and the age of the content in the cache. The property, if not `null`, determines the cache policy in effect for a request. + Applications typically use as their cache policy level. Using the level, the effective cache policy is determined by the current cache policy and the age of the content in the cache. The property, if not `null`, determines the cache policy in effect for a request. The default policy for the application domain can be set using the or the application or machine configuration file. For more information, see [<requestCaching> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/requestcaching-element-network-settings). diff --git a/xml/System.Net.Configuration/AuthenticationModuleElement.xml b/xml/System.Net.Configuration/AuthenticationModuleElement.xml index 0bc4a8149ce..409fdf20145 100644 --- a/xml/System.Net.Configuration/AuthenticationModuleElement.xml +++ b/xml/System.Net.Configuration/AuthenticationModuleElement.xml @@ -17,15 +17,15 @@ Represents the type information for an authentication module. This class cannot be inherited. - and classes. - - This class provides programmatic access to information that can be stored in configuration files. - + and classes. + + This class provides programmatic access to information that can be stored in configuration files. + ]]> @@ -58,11 +58,11 @@ Initializes a new instance of the class. - property to `null`. - + property to `null`. + ]]> @@ -90,11 +90,11 @@ A string that identifies the type and the assembly that contains it. Initializes a new instance of the class with the specified type information. - @@ -156,11 +156,11 @@ Gets or sets the type and assembly information for the current instance. A string that identifies a type that implements an authentication module or if no value has been specified. - diff --git a/xml/System.Net.Configuration/AuthenticationModulesSection.xml b/xml/System.Net.Configuration/AuthenticationModulesSection.xml index 31ad019a58f..4cd2e825e71 100644 --- a/xml/System.Net.Configuration/AuthenticationModulesSection.xml +++ b/xml/System.Net.Configuration/AuthenticationModulesSection.xml @@ -17,15 +17,15 @@ Represents the configuration section for authentication modules. This class cannot be inherited. - and classes. - - This class provides programmatic access to information that can be stored in configuration files. - + and classes. + + This class provides programmatic access to information that can be stored in configuration files. + ]]> @@ -49,11 +49,11 @@ Initializes a new instance of the class. - class to the property. - + class to the property. + ]]> @@ -87,11 +87,11 @@ Gets the collection of authentication modules in the section. A that contains the registered authentication modules. - returned by this property contains one for each authentication module in the configuration file. - + returned by this property contains one for each authentication module in the configuration file. + ]]> diff --git a/xml/System.Net.Configuration/BypassElement.xml b/xml/System.Net.Configuration/BypassElement.xml index 50222cd092d..ed8efae38b3 100644 --- a/xml/System.Net.Configuration/BypassElement.xml +++ b/xml/System.Net.Configuration/BypassElement.xml @@ -17,15 +17,15 @@ Represents the address information for resources that are not retrieved using a proxy server. This class cannot be inherited. - and classes. A resource in the bypass list is retrieved directly from the server where it resides. - - This class provides programmatic access to information that can be stored in configuration files. - + and classes. A resource in the bypass list is retrieved directly from the server where it resides. + + This class provides programmatic access to information that can be stored in configuration files. + ]]> @@ -81,11 +81,11 @@ A string that identifies the address of a resource. Initializes a new instance of the class with the specified type information. - property is set to `address`. - + property is set to `address`. + ]]> @@ -118,11 +118,11 @@ Gets or sets the addresses of resources that bypass the proxy server. A string that identifies a resource. - diff --git a/xml/System.Net.Configuration/ConnectionManagementElement.xml b/xml/System.Net.Configuration/ConnectionManagementElement.xml index 6ebd70b4098..8f380a0a386 100644 --- a/xml/System.Net.Configuration/ConnectionManagementElement.xml +++ b/xml/System.Net.Configuration/ConnectionManagementElement.xml @@ -17,15 +17,15 @@ Represents the maximum number of connections to a remote computer. This class cannot be inherited. - @@ -85,11 +85,11 @@ An integer that identifies the maximum number of connections allowed to from the local computer. Initializes a new instance of the class with the specified address and connection limit information. - property to `address` and the property to `maxConnection`. - + property to `address` and the property to `maxConnection`. + ]]> @@ -123,13 +123,13 @@ Gets or sets the address for remote computers. A string that contains a regular expression describing an IP address or DNS name. - property specifies how many simultaneous connections are allowed between the local computer and the remote computers. - + property specifies how many simultaneous connections are allowed between the local computer and the remote computers. + ]]> @@ -160,13 +160,13 @@ Gets or sets the maximum number of connections that can be made to a remote computer. An integer that specifies the maximum number of connections. - property. - - The property is per . If an application is not changing from the default, then the property applies to the entire application domain. If only a single application domain is running in your application, then the property setting is application-wide. - + property. + + The property is per . If an application is not changing from the default, then the property applies to the entire application domain. If only a single application domain is running in your application, then the property setting is application-wide. + ]]> diff --git a/xml/System.Net.Configuration/FtpCachePolicyElement.xml b/xml/System.Net.Configuration/FtpCachePolicyElement.xml index eb162e34a56..fb4b6f62b15 100644 --- a/xml/System.Net.Configuration/FtpCachePolicyElement.xml +++ b/xml/System.Net.Configuration/FtpCachePolicyElement.xml @@ -17,15 +17,15 @@ Represents the default FTP cache policy for network resources. This class cannot be inherited. - and classes. - - This class provides programmatic access to information that can be stored in configuration files. - + and classes. + + This class provides programmatic access to information that can be stored in configuration files. + ]]> @@ -101,11 +101,11 @@ Gets or sets FTP caching behavior for the local machine. A value that specifies the cache behavior. - as their cache policy level. The property, if not `null`, determines the cache policy in effect for a request. - + as their cache policy level. The property, if not `null`, determines the cache policy in effect for a request. + ]]> diff --git a/xml/System.Net.Configuration/HttpCachePolicyElement.xml b/xml/System.Net.Configuration/HttpCachePolicyElement.xml index d157002871b..6fddaabe932 100644 --- a/xml/System.Net.Configuration/HttpCachePolicyElement.xml +++ b/xml/System.Net.Configuration/HttpCachePolicyElement.xml @@ -17,15 +17,15 @@ Represents the default HTTP cache policy for network resources. This class cannot be inherited. - and classes. - - This class provides programmatic access to information that can be stored in configuration files. - + and classes. + + This class provides programmatic access to information that can be stored in configuration files. + ]]> @@ -48,11 +48,11 @@ Initializes a new instance of the class. - , , , and properties to the collection. - + , , , and properties to the collection. + ]]> @@ -110,11 +110,11 @@ Gets or sets the maximum age permitted for a resource returned from the cache. A value that specifies the maximum age for cached resources specified in the configuration file. - @@ -145,11 +145,11 @@ Gets or sets the maximum staleness value permitted for a resource returned from the cache. A value that is set to the maximum staleness value specified in the configuration file. - @@ -180,11 +180,11 @@ Gets or sets the minimum freshness permitted for a resource returned from the cache. A value that specifies the minimum freshness specified in the configuration file. - @@ -215,11 +215,11 @@ Gets or sets HTTP caching behavior for the local machine. A value that specifies the cache behavior. - as their cache policy level. The property, if not `null`, determines the cache policy in effect for a request. - + as their cache policy level. The property, if not `null`, determines the cache policy in effect for a request. + ]]> diff --git a/xml/System.Net.Configuration/HttpListenerElement.xml b/xml/System.Net.Configuration/HttpListenerElement.xml index b0e6c3b1b41..f1ca6aab783 100644 --- a/xml/System.Net.Configuration/HttpListenerElement.xml +++ b/xml/System.Net.Configuration/HttpListenerElement.xml @@ -21,9 +21,9 @@ ## Remarks This class corresponds to the \ Element (Network Settings) configuration element. This class provides programmatic access to information that can be stored in configuration files. - The property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. + The property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. - When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. + When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. The `http.sys` service exposes two request URI strings: @@ -45,7 +45,7 @@ `http://www.contoso.com/path/` - The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: + The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: - Un-escapes all percent encoded values. @@ -62,7 +62,7 @@ |EnableNonUTF8|1|If zero, `http.sys` accepts only UTF-8-encoded URLs.

If non-zero, `http.sys` also accepts ANSI-encoded or DBCS-encoded URLs in requests.| |FavorUTF8|1|If non-zero, `http.sys` always tries to decode a URL as UTF-8 first; if that conversion fails and EnableNonUTF8 is non-zero, Http.sys then tries to decode it as ANSI or DBCS.

If zero (and EnableNonUTF8 is non-zero), `http.sys` tries to decode it as ANSI or DBCS; if that is not successful, it tries a UTF-8 conversion.| - When receives a request, it uses the converted URI from `http.sys` as input to the property. + When receives a request, it uses the converted URI from `http.sys` as input to the property. There is a need for supporting characters besides characters and numbers in URIs. An example is the following URI, which is used to retrieve customer information for customer number "1/3812": @@ -82,7 +82,7 @@ This is not the intent of the sender of the request. - If the property is set to false, then when the receives a request, it uses the raw URI instead of the converted URI from `http.sys` as input to the property. + If the property is set to false, then when the receives a request, it uses the raw URI instead of the converted URI from `http.sys` as input to the property. ]]>
@@ -200,9 +200,9 @@ property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. + The property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. - When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. + When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. The `http.sys` service exposes two request URI strings: @@ -224,7 +224,7 @@ `http://www.contoso.com/path/` - The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: + The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: - Un-escapes all percent encoded values. @@ -241,7 +241,7 @@ |EnableNonUTF8|1|If zero, `http.sys` accepts only UTF-8-encoded URLs.

If non-zero, `http.sys` also accepts ANSI-encoded or DBCS-encoded URLs in requests.| |FavorUTF8|1|If non-zero, `http.sys` always tries to decode a URL as UTF-8 first; if that conversion fails and EnableNonUTF8 is non-zero, Http.sys then tries to decode it as ANSI or DBCS.

If zero (and EnableNonUTF8 is non-zero), `http.sys` tries to decode it as ANSI or DBCS; if that is not successful, it tries a UTF-8 conversion.| - When receives a request, it uses the converted URI from `http.sys` as input to the property. + When receives a request, it uses the converted URI from `http.sys` as input to the property. There is a need for supporting characters besides characters and numbers in URIs. An example is the following URI, which is used to retrieve customer information for customer number "1/3812": @@ -261,7 +261,7 @@ This is not the intent of the sender of the request. - If the property is set to false, then when the receives a request, it uses the raw URI instead of the converted URI from `http.sys` as input to the property. + If the property is set to false, then when the receives a request, it uses the raw URI instead of the converted URI from `http.sys` as input to the property. ]]>
diff --git a/xml/System.Net.Configuration/Ipv6Element.xml b/xml/System.Net.Configuration/Ipv6Element.xml index 2cb4702480a..5a2f783d6c4 100644 --- a/xml/System.Net.Configuration/Ipv6Element.xml +++ b/xml/System.Net.Configuration/Ipv6Element.xml @@ -17,15 +17,15 @@ Determines whether Internet Protocol version 6 is enabled on the local computer. This class cannot be inherited. - Network Settings Schema @@ -47,11 +47,11 @@ Initializes a new instance of the class. - property to the collection. - + property to the collection. + ]]> Network Settings Schema diff --git a/xml/System.Net.Configuration/ModuleElement.xml b/xml/System.Net.Configuration/ModuleElement.xml index 86ece824fc0..3a291f30017 100644 --- a/xml/System.Net.Configuration/ModuleElement.xml +++ b/xml/System.Net.Configuration/ModuleElement.xml @@ -17,15 +17,15 @@ Represents the type information for a custom module. This class cannot be inherited. - and classes. - - This class provides programmatic access to information that can be stored in configuration files. - + and classes. + + This class provides programmatic access to information that can be stored in configuration files. + ]]> @@ -48,11 +48,11 @@ Initializes a new instance of the class. - object for the property to the collection. - + object for the property to the collection. + ]]> @@ -114,11 +114,11 @@ Gets or sets the type and assembly information for the current instance. A string that identifies a type that implements the interface or if no value has been specified. - Network Settings Schema diff --git a/xml/System.Net.Configuration/RequestCachingSection.xml b/xml/System.Net.Configuration/RequestCachingSection.xml index 3287498ebf2..a1fdb94543d 100644 --- a/xml/System.Net.Configuration/RequestCachingSection.xml +++ b/xml/System.Net.Configuration/RequestCachingSection.xml @@ -17,15 +17,15 @@ Represents the configuration section for cache behavior. This class cannot be inherited. - and classes. - - This class provides programmatic access to information that can be stored in configuration files. - + and classes. + + This class provides programmatic access to information that can be stored in configuration files. + ]]> Network Settings Schema @@ -103,11 +103,11 @@ Gets the default caching behavior for the local computer. A that defines the default cache policy. - property is set to `true`, the policy returned by this property overrides the policy set in the property. - + property is set to `true`, the policy returned by this property overrides the policy set in the property. + ]]> @@ -194,11 +194,11 @@ if caching is disabled on the local computer; otherwise, . - @@ -230,11 +230,11 @@ if the cache provides user isolation; otherwise, . - @@ -315,11 +315,11 @@ Gets or sets a value used as the maximum age for cached resources that do not have expiration information. A that provides a default maximum age for cached resources. - diff --git a/xml/System.Net.Configuration/ServicePointManagerElement.xml b/xml/System.Net.Configuration/ServicePointManagerElement.xml index 32ed8506c36..c0e14a952db 100644 --- a/xml/System.Net.Configuration/ServicePointManagerElement.xml +++ b/xml/System.Net.Configuration/ServicePointManagerElement.xml @@ -17,15 +17,15 @@ Represents the default settings used to create connections to a remote computer. This class cannot be inherited. - objects. - - This class provides programmatic access to information that can be stored in configuration files. - + objects. + + This class provides programmatic access to information that can be stored in configuration files. + ]]> @@ -114,11 +114,11 @@ if the certificate revocation list is checked; otherwise, . The default value is . - @@ -152,11 +152,11 @@ Gets or sets the amount of time after which address information is refreshed. A that specifies when addresses are resolved using DNS. - property. - + property. + ]]> @@ -221,11 +221,11 @@ Gets or sets the to use. The encryption policy to use for a instance. - property can require, allow, or prevent encryption. The will be applied to an SSL/TLS session. The use of the Null cipher is required when the encryption policy is set to . - + property can require, allow, or prevent encryption. The will be applied to an SSL/TLS session. The use of the Null cipher is required when the encryption policy is set to . + ]]> @@ -261,13 +261,13 @@ to expect 100-Continue responses for requests; otherwise, . The default value is . - . - + . + ]]> @@ -352,11 +352,11 @@ to use the Nagle algorithm; otherwise, . The default value is . - diff --git a/xml/System.Net.Configuration/SmtpNetworkElement.xml b/xml/System.Net.Configuration/SmtpNetworkElement.xml index 6742610a61b..c5b7dd6782a 100644 --- a/xml/System.Net.Configuration/SmtpNetworkElement.xml +++ b/xml/System.Net.Configuration/SmtpNetworkElement.xml @@ -17,11 +17,11 @@ Represents the network element in the SMTP configuration file. This class cannot be inherited. - @@ -76,19 +76,19 @@ Gets or sets the client domain name used in the initial SMTP protocol request to connect to an SMTP mail server. A string that represents the client domain name used in the initial SMTP protocol request to connect to an SMTP mail server. - property allows an application to change the client domain name used in the initial SMTP protocol request to an SMTP server. If the property is not set, the default is to use the localhost name of the local computer sending the request. - - RFC 2821 that defines the details of the Simple Mail Transport Protocol (SMTP). This RFC stipulates that an SMTP client should use a fully-qualified domain name as part of its HELO or Extended HELO (EHLO) message to a server. - - The property allows an application to change the client domain name (the RFC uses the term Domain in the protocol description) to use the fully-qualified domain name of the local machine, rather than the localhost name that is used by default. This provides greater compliance with the SMTP protocol standards. However, the fully-qualified domain name may expose private information about the local computer. - - Any name set in the property should conform to DNS rules for 7-bit ASCII names. - - The default value for this network element in the SMTP configuration file can also be changed by manually editing the machine or application configuration files directly. - + property allows an application to change the client domain name used in the initial SMTP protocol request to an SMTP server. If the property is not set, the default is to use the localhost name of the local computer sending the request. + + RFC 2821 that defines the details of the Simple Mail Transport Protocol (SMTP). This RFC stipulates that an SMTP client should use a fully-qualified domain name as part of its HELO or Extended HELO (EHLO) message to a server. + + The property allows an application to change the client domain name (the RFC uses the term Domain in the protocol description) to use the fully-qualified domain name of the local machine, rather than the localhost name that is used by default. This provides greater compliance with the SMTP protocol standards. However, the fully-qualified domain name may expose private information about the local computer. + + Any name set in the property should conform to DNS rules for 7-bit ASCII names. + + The default value for this network element in the SMTP configuration file can also be changed by manually editing the machine or application configuration files directly. + ]]> @@ -161,13 +161,13 @@ indicates that SSL will be used to access the SMTP mail server; otherwise, . - property indicates if SSL is used to access an SMTP mail server. The class only supports the SMTP Service Extension for Secure SMTP over Transport Layer Security as defined in RFC 3207. In this mode, the SMTP session begins on an unencrypted channel, then a STARTTLS command is issued by the client to the server to switch to secure communication using SSL. See RFC 3207 published by the Internet Engineering Task Force (IETF) for more information. - - An alternate connection method is where an SSL session is established up front before any protocol commands are sent. This connection method is sometimes called SMTPS and by default uses port 465. This alternate connection method using SSL is not currently supported. - + property indicates if SSL is used to access an SMTP mail server. The class only supports the SMTP Service Extension for Secure SMTP over Transport Layer Security as defined in RFC 3207. In this mode, the SMTP session begins on an unencrypted channel, then a STARTTLS command is issued by the client to the server to switch to secure communication using SSL. See RFC 3207 published by the Internet Engineering Task Force (IETF) for more information. + + An alternate connection method is where an SSL session is established up front before any protocol commands are sent. This connection method is sometimes called SMTPS and by default uses port 465. This alternate connection method using SSL is not currently supported. + ]]> @@ -233,11 +233,11 @@ Gets or sets the user password to use to connect to an SMTP mail server. A string that represents the password to use to connect to an SMTP mail server. - takes precedence over setting and . and are used only if is set to `false`. - + takes precedence over setting and . and are used only if is set to `false`. + ]]> @@ -359,13 +359,13 @@ Gets or sets the Service Provider Name (SPN) to use for authentication when using extended protection to connect to an SMTP mail server. A string that represents the SPN to use for authentication when using extended protection to connect to an SMTP mail server. - property allows an application to get or set the SPN to use for authentication when integrated Windows authentication with extended protection. If the property is not set, the default value for this SPN is of the form "SMTPSVC/\" where \ is the hostname of the SMTP mail server. - - The default value for this network element in the SMTP configuration file can also be changed by manually editing the machine or application configuration files directly. - + property allows an application to get or set the SPN to use for authentication when integrated Windows authentication with extended protection. If the property is not set, the default value for this SPN is of the form "SMTPSVC/\" where \ is the hostname of the SMTP mail server. + + The default value for this network element in the SMTP configuration file can also be changed by manually editing the machine or application configuration files directly. + ]]> @@ -403,11 +403,11 @@ Gets or sets the user name to connect to an SMTP mail server. A string that represents the user name to connect to an SMTP mail server. - takes precedence over setting and . and are used only if is set to `false`. - + takes precedence over setting and . and are used only if is set to `false`. + ]]> diff --git a/xml/System.Net.Configuration/SocketElement.xml b/xml/System.Net.Configuration/SocketElement.xml index 10d6f40c227..695f1ed5dcf 100644 --- a/xml/System.Net.Configuration/SocketElement.xml +++ b/xml/System.Net.Configuration/SocketElement.xml @@ -17,15 +17,15 @@ Represents information used to configure objects. This class cannot be inherited. - Network Settings Schema @@ -48,11 +48,11 @@ Initializes a new instance of the class. - and properties to the collection. - + and properties to the collection. + ]]> @@ -144,11 +144,11 @@ Gets or sets a value that specifies the default to use for a socket. The value of the for the current instance. - property enables configuration of a restriction for an IPv6 socket to a specified scope, such as addresses with the same link local or site local prefix. This option enables applications to place access restrictions on IPv6 sockets. Such restrictions enable an application running on a private LAN to simply and robustly harden itself against external attacks. This option widens or narrows the scope of a listening socket, enabling unrestricted access from public and private users when appropriate, or restricting access only to the same site, as required. This option has three defined protection levels specified in the enumeration. - + property enables configuration of a restriction for an IPv6 socket to a specified scope, such as addresses with the same link local or site local prefix. This option enables applications to place access restrictions on IPv6 sockets. Such restrictions enable an application running on a private LAN to simply and robustly harden itself against external attacks. This option widens or narrows the scope of a listening socket, enabling unrestricted access from public and private users when appropriate, or restricting access only to the same site, as required. This option has three defined protection levels specified in the enumeration. + ]]> diff --git a/xml/System.Net.Configuration/WebRequestModuleElement.xml b/xml/System.Net.Configuration/WebRequestModuleElement.xml index af1b3d01464..aa3a6095938 100644 --- a/xml/System.Net.Configuration/WebRequestModuleElement.xml +++ b/xml/System.Net.Configuration/WebRequestModuleElement.xml @@ -96,7 +96,7 @@ ## Remarks The `type` parameter contains the fully qualified type name followed by a comma (,) and the assembly information. The elements of the assembly information are separated with commas, for example, "`System.Net.DigestClient, System, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"`. - The property is set to `prefix` and the property is set to `type`. + The property is set to `prefix` and the property is set to `type`. ]]>
@@ -127,7 +127,7 @@ property is set to `prefix` and the property is set to `type`. + The property is set to `prefix` and the property is set to `type`. ]]> diff --git a/xml/System.Net.Http.Headers/CacheControlHeaderValue.xml b/xml/System.Net.Http.Headers/CacheControlHeaderValue.xml index 24008ea5917..cbeb4ab42ba 100644 --- a/xml/System.Net.Http.Headers/CacheControlHeaderValue.xml +++ b/xml/System.Net.Http.Headers/CacheControlHeaderValue.xml @@ -180,11 +180,11 @@ Cache-extension tokens, each with an optional assigned value. A collection of cache-extension tokens each with an optional assigned value. -
@@ -226,13 +226,13 @@ Serves as a hash function for a object. A hash code for the current object. - method is suitable for use in hashing algorithms and data structures such as a hash table. - + method is suitable for use in hashing algorithms and data structures such as a hash table. + ]]>
@@ -273,13 +273,13 @@ The maximum age, specified in seconds, that the HTTP client is willing to accept a response. The time in seconds. - property is also set, the client is not willing to accept a stale response. - + property is also set, the client is not willing to accept a stale response. + ]]>
@@ -321,11 +321,11 @@ if the HTTP client is willing to accept a response that has exceed the expiration time; otherwise, . -
@@ -366,13 +366,13 @@ The maximum time, in seconds, an HTTP client is willing to accept a response that has exceeded its expiration time. The time in seconds. - property is assigned a value other than zero, then the client is willing to accept a response that has exceeded its expiration time by no more than the specified number of seconds. If a value of zero is assigned to the property, then the client is willing to accept a stale response of any age. - + property is assigned a value other than zero, then the client is willing to accept a response that has exceeded its expiration time by no more than the specified number of seconds. If a value of zero is assigned to the property, then the client is willing to accept a stale response of any age. + ]]>
@@ -413,13 +413,13 @@ The freshness lifetime, in seconds, that an HTTP client is willing to accept a response. The time in seconds. -
@@ -461,11 +461,11 @@ if the origin server requires revalidation of a cache entry on any subsequent use when the entry becomes stale; otherwise, . - @@ -507,13 +507,13 @@ if the HTTP client is not willing to accept a cached response; otherwise, . - property is set to `true` present in a HTTP request message, an application should forward the request toward the origin server even if it has a cached copy of what is being requested. - + property is set to `true` present in a HTTP request message, an application should forward the request toward the origin server even if it has a cached copy of what is being requested. + ]]> @@ -554,11 +554,11 @@ A collection of fieldnames in the "no-cache" directive in a cache-control header field on an HTTP response. A collection of fieldnames. - @@ -600,13 +600,13 @@ if a cache must not store any part of either the HTTP request message or any response; otherwise, . - property is to prevent the inadvertent release or retention of sensitive information. This property applies to the entire message, and may be sent either in an HTTP request or a response. - + property is to prevent the inadvertent release or retention of sensitive information. This property applies to the entire message, and may be sent either in an HTTP request or a response. + ]]> @@ -648,13 +648,13 @@ if a cache or proxy must not change any aspect of the entity-body; otherwise, . - is set to `true`, intermediate caches or proxies must not change any aspect of the entity body. Implementors of intermediate caches and proxies have found it useful to convert the media type of certain entity bodies. A non-transparent proxy might, for example, convert between image formats in order to save cache space or to reduce the amount of traffic on a slow link. Serious operational problems occur, however, when these transformations are applied to entity bodies intended for certain kinds of applications. - + is set to `true`, intermediate caches or proxies must not change any aspect of the entity body. Implementors of intermediate caches and proxies have found it useful to convert the media type of certain entity bodies. A non-transparent proxy might, for example, convert between image formats in order to save cache space or to reduce the amount of traffic on a slow link. Serious operational problems occur, however, when these transformations are applied to entity bodies intended for certain kinds of applications. + ]]> @@ -696,11 +696,11 @@ if a cache should either respond using a cached entry that is consistent with the other constraints of the HTTP request, or respond with a 504 (Gateway Timeout) status; otherwise, . - @@ -796,11 +796,11 @@ if the HTTP response message is intended for a single user and must not be cached by a shared cache; otherwise, . - @@ -841,11 +841,11 @@ A collection fieldnames in the "private" directive in a cache-control header field on an HTTP response. A collection of fieldnames. - @@ -887,13 +887,13 @@ if the origin server requires revalidation of a cache entry on any subsequent use when the entry becomes stale for shared user agent caches; otherwise, . - @@ -935,11 +935,11 @@ if the HTTP response may be cached by any cache, even if it would normally be non-cacheable or cacheable only within a non- shared cache; otherwise, . - @@ -980,11 +980,11 @@ The shared maximum age, specified in seconds, in an HTTP response that overrides the "max-age" directive in a cache-control header or an Expires header for a shared cache. The time in seconds. - diff --git a/xml/System.Net.Http.Headers/ContentDispositionHeaderValue.xml b/xml/System.Net.Http.Headers/ContentDispositionHeaderValue.xml index 2ef709c37d7..9b3937729c6 100644 --- a/xml/System.Net.Http.Headers/ContentDispositionHeaderValue.xml +++ b/xml/System.Net.Http.Headers/ContentDispositionHeaderValue.xml @@ -243,7 +243,7 @@ property of "inline" if it is intended to be displayed automatically upon display of the message. A body part can be designated with a property of "attachment" to indicate that they are separate from the main body of the HTTP request or response. + A body part should be marked with a property of "inline" if it is intended to be displayed automatically upon display of the message. A body part can be designated with a property of "attachment" to indicate that they are separate from the main body of the HTTP request or response. ]]> @@ -340,7 +340,7 @@ property uses MIME encoding for non-ascii characters. + The property uses MIME encoding for non-ascii characters. ]]> @@ -386,7 +386,7 @@ property uses IETF RFC 5987 encoding. The and properties differ only in that uses the encoding defined in IETF RFC 5987, allowing the use of characters not present in the ISO-8859-1 character set. + The property uses IETF RFC 5987 encoding. The and properties differ only in that uses the encoding defined in IETF RFC 5987, allowing the use of characters not present in the ISO-8859-1 character set. ]]> diff --git a/xml/System.Net.Http/DelegatingHandler.xml b/xml/System.Net.Http/DelegatingHandler.xml index 3da8f341bbd..7cdbac16221 100644 --- a/xml/System.Net.Http/DelegatingHandler.xml +++ b/xml/System.Net.Http/DelegatingHandler.xml @@ -48,13 +48,13 @@ A type for HTTP handlers that delegate the processing of HTTP response messages to another handler, called the inner handler. - property before calling ; otherwise, an will be thrown. - - Note that property may be a delegating handler as well. This approach allows the creation of handler stacks to process the HTTP response messages. - + property before calling ; otherwise, an will be thrown. + + Note that property may be a delegating handler as well. This approach allows the creation of handler stacks to process the HTTP response messages. + ]]> @@ -103,11 +103,11 @@ Creates a new instance of the class. - . - + . + ]]> @@ -235,13 +235,13 @@ Gets or sets the inner handler which processes the HTTP response messages. The inner handler for HTTP response messages. - property can only be set before the class is used (the method is called). - - Note that property may be a delegating handler too, although this is uncommon. This approach allows the creation of handler stacks for the HTTP response messages. - + property can only be set before the class is used (the method is called). + + Note that property may be a delegating handler too, although this is uncommon. This approach allows the creation of handler stacks for the HTTP response messages. + ]]> @@ -280,12 +280,12 @@ Sends an HTTP request to the inner handler to send to the server. An HTTP response message. - method is mainly used by the system and not by applications. When this method is called, it calls the method on the inner handler. - + + The method is mainly used by the system and not by applications. When this method is called, it calls the method on the inner handler. + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -333,13 +333,13 @@ Sends an HTTP request to the inner handler to send to the server as an asynchronous operation. The task object representing the asynchronous operation. - method forwards the HTTP request to the inner handler to send to the server as an asynchronous operation. - - The method is mainly used by the system and not by applications. When this method is called, it calls the method on the inner handler. - + method forwards the HTTP request to the inner handler to send to the server as an asynchronous operation. + + The method is mainly used by the system and not by applications. When this method is called, it calls the method on the inner handler. + ]]> The was . diff --git a/xml/System.Net.Http/HttpClient.xml b/xml/System.Net.Http/HttpClient.xml index 4d35762ca0b..6d74bd2e88b 100644 --- a/xml/System.Net.Http/HttpClient.xml +++ b/xml/System.Net.Http/HttpClient.xml @@ -276,7 +276,7 @@ The specified `handler` will be disposed of by calling [HttpClient.Dispose](xref with a relative URI, the message URI is added to the property to create an absolute URI. + When sending a with a relative URI, the message URI is 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 Generic Syntax specification. @@ -2528,7 +2528,7 @@ The response status code was outside of the range of 200-299 (which indicate suc 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. + An app can set the 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. ]]> diff --git a/xml/System.Net.Http/HttpClientHandler.xml b/xml/System.Net.Http/HttpClientHandler.xml index dcf946444ec..8498ca07cc7 100644 --- a/xml/System.Net.Http/HttpClientHandler.xml +++ b/xml/System.Net.Http/HttpClientHandler.xml @@ -133,7 +133,7 @@ to `true` if you want the handler to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. + Set to `true` if you want the handler to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. If is set to `false`, all HTTP responses with an HTTP status code from 300 to 399 are returned to the application. @@ -407,9 +407,9 @@ On .NET Core, the key usage attribute on the X509 certificate, if present, is re property provides an instance of the class that contains the cookies associated with this handler. + The property provides an instance of the class that contains the cookies associated with this handler. - If the property is `true`, the property represents the cookie container used to store the server cookies. The user can set custom cookies before sending requests using this property. If the property is false and the user adds cookies to , cookies are ignored and not sent to the server. Setting the to `null` will throw an exception. + If the property is `true`, the property represents the cookie container used to store the server cookies. The user can set custom cookies before sending requests using this property. If the property is false and the user adds cookies to , cookies are ignored and not sent to the server. Setting the to `null` will throw an exception. ]]> @@ -513,15 +513,15 @@ If the property h to connect to a server with a certificate that shouldn't be validated, such as a self-signed certificate. You commonly do this with by setting the property to a delegate that always returns `True`; this indicates that the certificate has passed validation. However, not all implementations support this callback, and some throw . + Particularly in test scenarios, a common pattern use to connect to a server with a certificate that shouldn't be validated, such as a self-signed certificate. You commonly do this with by setting the property to a delegate that always returns `True`; this indicates that the certificate has passed validation. However, not all implementations support this callback, and some throw . - The property addresses this limitation. The delegate returned by the property can be assigned to the property, as the following example does: + The property addresses this limitation. The delegate returned by the property can be assigned to the property, as the following example does: ```csharp handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator; ``` - This gives implementations a known object reference identity that expresses the developer's intention. If the object stored in the property is reference equals to , the runtime is able to entirely disable validation on a platform that would otherwise throw a . + This gives implementations a known object reference identity that expresses the developer's intention. If the object stored in the property is reference equals to , the runtime is able to entirely disable validation on a platform that would otherwise throw a . As a side benefit, developers can use this property to make it easier for tools to flag the danger of disabling certificate validation, which makes it easier for developers to avoid shipping insecure applications. @@ -674,7 +674,7 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA property sets the maximum number of redirections for the request to follow if the property is `true`. + The property sets the maximum number of redirections for the request to follow if the property is `true`. ]]> @@ -774,7 +774,7 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA property to a lower value to limit the size of the request buffer. If the size of the request content is greater than the property, an exception is thrown. + An app can set the property to a lower value to limit the size of the request buffer. If the size of the request content is greater than the property, an exception is thrown. ]]> @@ -907,11 +907,11 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA is successfully authenticated, if the property is `true` and credentials are supplied, matches against the credential list supplied in the property. The Authorization header is sent with each request to any that matches the specific up to the last forward slash. + After a client request to a specific is successfully authenticated, if the property is `true` and credentials are supplied, matches against the credential list supplied in the property. The Authorization header is sent with each request to any that matches the specific up to the last forward slash. If the client request to a specific is not successfully authenticated, the request uses standard authentication procedures. - With the exception of the first request, the property indicates whether to send authentication information with subsequent requests to a that matches the specific up to the last forward slash without waiting to be challenged by the server. + With the exception of the first request, the property indicates whether to send authentication information with subsequent requests to a that matches the specific up to the last forward slash without waiting to be challenged by the server. ]]> @@ -1024,9 +1024,9 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. + The property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. - The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the handler will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the handler uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. + The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the handler will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the handler uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. The class supports local proxy bypass. The class considers a destination to be local if any of the following conditions are met: @@ -1485,7 +1485,7 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA 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. + 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. diff --git a/xml/System.Net.Http/HttpCompletionOption.xml b/xml/System.Net.Http/HttpCompletionOption.xml index f54e37a8476..238ccb1db37 100644 --- a/xml/System.Net.Http/HttpCompletionOption.xml +++ b/xml/System.Net.Http/HttpCompletionOption.xml @@ -47,7 +47,7 @@ > [!WARNING] > The value affects the scope of the timeout specified in the options when reading a response. The timeout on the always applies on the relevant invoked methods up until the point where those methods complete/return. Crucially, when using the option, the timeout applies only up to where the headers end and the content starts. The content reading operation needs to be timed out separately in case the server promptly returns the status line and headers but takes too long to return the content. -> This consideration also applies to the property. The limit is only enforced when using . +> This consideration also applies to the property. The limit is only enforced when using . > Below is an example illustrating this point: :::code language="csharp" source="~/snippets/csharp/System.Net.Http/HttpCompletionOption/HttpCompletionOptionSnippets.cs" id="SnippetHttpCompletionOption"::: diff --git a/xml/System.Net.Http/HttpContent.xml b/xml/System.Net.Http/HttpContent.xml index 1cc068b3a8c..6e7496ee982 100644 --- a/xml/System.Net.Http/HttpContent.xml +++ b/xml/System.Net.Http/HttpContent.xml @@ -484,7 +484,7 @@ Once the operation completes, the returned memory stream represents the HTTP con ## Remarks This operation will not block. The returned object will complete after all of the content has been written to the memory stream. - Once the operation completes, the property on the returned task object contains the memory stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. + Once the operation completes, the property on the returned task object contains the memory stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. The method buffers the content to a memory stream. Derived classes can override this behavior if there is a better way to retrieve the content as stream. For example, a byte array or a string could use a more efficient method way such as wrapping a read-only around the bytes or string. @@ -529,7 +529,7 @@ Once the operation completes, the returned memory stream represents the HTTP con ## Remarks This operation will not block. The returned object will complete after all of the content has been written to the memory stream. - Once the operation completes, the property on the returned task object contains the memory stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. + Once the operation completes, the property on the returned task object contains the memory stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. The method buffers the content to a memory stream. Derived classes can override this behavior if there is a better way to retrieve the content as stream. For example, a byte array or a string could use a more efficient method way such as wrapping a read-only around the bytes or string.) @@ -914,7 +914,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel ## Remarks This operation will not block. The returned object will complete after all of the content has been written as a byte array. - Once the operation completes, the property on the returned task object contains the byte array with the HTTP content. + Once the operation completes, the property on the returned task object contains the byte array with the HTTP content. Note that this method will internally buffer the content via . @@ -959,7 +959,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel ## Remarks This operation will not block. The returned object will complete after all of the content has been written as a byte array. - Once the operation completes, the property on the returned task object contains the byte array with the HTTP content. + Once the operation completes, the property on the returned task object contains the byte array with the HTTP content. Note that this method will internally buffer the content via . @@ -1117,7 +1117,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel ## Remarks This operation will not block. The returned object will complete after all of the stream that represents content has been read. - Once the operation completes, the property on the returned task object contains the stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. + Once the operation completes, the property on the returned task object contains the stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. 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 . @@ -1163,7 +1163,7 @@ When the `disposing` parameter is `true`, this method releases all resources hel This operation will not block. The returned object will complete after all of the stream that represents content has been read (unless has been implemented to do otherwise). For example, when using , a method such as returns a class derived from that conditionally buffers based on what's passed for the `completionOption` parameter. - Once the operation completes, the property on the returned task object contains the stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. + Once the operation completes, the property on the returned task object contains the stream that represents the HTTP content. The returned stream can then be used to read the content using various stream APIs. 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 . @@ -1214,7 +1214,7 @@ For example, when using , a method such as object will complete after all of the content has been written as a string. - Once the operation completes, the property on the returned task object contains the string with the HTTP content. + Once the operation completes, the property on the returned task object contains the string with the HTTP content. Note that this method will internally buffer the content via . @@ -1259,7 +1259,7 @@ For example, when using , a method such as object will complete after all of the content has been written as a string. - Once the operation completes, the property on the returned task object contains the string with the HTTP content. + Once the operation completes, the property on the returned task object contains the string with the HTTP content. Note that this method will internally buffer the content via . diff --git a/xml/System.Net.Http/MultipartContent.xml b/xml/System.Net.Http/MultipartContent.xml index 0ab8e365eb9..401dd51861d 100644 --- a/xml/System.Net.Http/MultipartContent.xml +++ b/xml/System.Net.Http/MultipartContent.xml @@ -183,12 +183,12 @@ If your server doesn't support such contents with zero parts, consider condition The boundary string for the multipart content. Creates a new instance of the class. To be added. - The was or an empty string. - - The was or contains only white space characters. - - -or- - + The was or an empty string. + + The was or contains only white space characters. + + -or- + The ends with a space character. The length of the was greater than 70. @@ -267,9 +267,9 @@ If your server doesn't support such contents with zero parts, consider condition Serializes the HTTP content to a stream using the multipart/* encoding. The HTTP content stream that represents the multipart/* encoded HTTP content. - to use a custom stream that contains an array, with each HTTP content entity and its boundary encoded and serialized to a instance. ]]> @@ -309,15 +309,15 @@ This method overrides Serializes the HTTP content to a stream using the multipart/* encoding as an asynchronous operation. The task object representing the asynchronous operation. - to use a custom stream that contains an array, with each HTTP content and its boundary encoded and serialized to a instance. - This operation will not block. The returned object will complete after all of the content has been written to the memory stream. - - Once the operation completes, the property on the returned task object contains the stream that represents the multipart/* encoded HTTP content. The returned stream can then be used to read the content using various stream APIs. - + This operation will not block. The returned object will complete after all of the content has been written to the memory stream. + + Once the operation completes, the property on the returned task object contains the stream that represents the multipart/* encoded HTTP content. The returned stream can then be used to read the content using various stream APIs. + ]]> @@ -354,15 +354,15 @@ This method overrides Serializes the HTTP content to a stream using the multipart/* encoding as an asynchronous operation. The task object representing the asynchronous operation. - to use a custom stream that contains an array, with each HTTP content and its boundary encoded and serialized to a instance. - This operation will not block. The returned object will complete after all of the content has been written to the memory stream. - - Once the operation completes, the property on the returned task object contains the stream that represents the multipart/* encoded HTTP content. The returned stream can then be used to read the content using various stream APIs. - + This operation will not block. The returned object will complete after all of the content has been written to the memory stream. + + Once the operation completes, the property on the returned task object contains the stream that represents the multipart/* encoded HTTP content. The returned stream can then be used to read the content using various stream APIs. + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -408,13 +408,13 @@ This method overrides 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 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. + ]]> @@ -459,15 +459,15 @@ When the `disposing` parameter is `true`, this method releases all resources hel Returns an enumerator that iterates through the collection of objects that get serialized using the multipart/* content type specification. An object that can be used to iterate through the collection. - @@ -603,11 +603,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel Serialize the multipart HTTP content to a stream as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after all of the content has been serialized to the target stream. - + object will complete after all of the content has been serialized to the target stream. + ]]> @@ -655,11 +655,11 @@ When the `disposing` parameter is `true`, this method releases all resources hel Serialize the multipart HTTP content to a stream as an asynchronous operation. The task object representing the asynchronous operation. - object will complete after all of the content has been serialized to the target stream. - + object will complete after all of the content has been serialized to the target stream. + ]]> The cancellation token was canceled. This exception is stored into the returned task. @@ -756,11 +756,11 @@ This member is an explicit interface member implementation. It can be used only if is a valid length; otherwise, . - method gives HTTP multipart content the ability to calculate the content length. This is useful for content types which are able to easily calculate the content length. If computing the content length is not possible or expensive (would require the system to buffer the whole content where the serialization would be expensive or require the system to allocate a lot of memory), this method can return `false`. If this method returns `false`, this implies that either chunked transfer is needed or the content must get buffered before being sent to the server. - + method gives HTTP multipart content the ability to calculate the content length. This is useful for content types which are able to easily calculate the content length. If computing the content length is not possible or expensive (would require the system to buffer the whole content where the serialization would be expensive or require the system to allocate a lot of memory), this method can return `false`. If this method returns `false`, this implies that either chunked transfer is needed or the content must get buffered before being sent to the server. + ]]> diff --git a/xml/System.Net.Http/SocketsHttpHandler.xml b/xml/System.Net.Http/SocketsHttpHandler.xml index cd6e4bdaf09..e89a6f8d0c5 100644 --- a/xml/System.Net.Http/SocketsHttpHandler.xml +++ b/xml/System.Net.Http/SocketsHttpHandler.xml @@ -55,7 +55,7 @@ If this change is undesirable and you are on .NET Core 2.1-3.1, you can configur ```vb AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", False) ``` - + - By defining the `System.Net.Http.UseSocketsHttpHandler` switch in the *.netcore.runtimeconfig.json* configuration file: ```json @@ -166,7 +166,7 @@ These configuration options are not available starting with .NET 5. to `true` if you want the handler to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. + Set to `true` if you want the handler to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. If is set to `false`, all HTTP responses with an HTTP status code from 300 to 399 are returned to the application. diff --git a/xml/System.Net.Http/WebRequestHandler.xml b/xml/System.Net.Http/WebRequestHandler.xml index 84e739c5beb..14af5506c45 100644 --- a/xml/System.Net.Http/WebRequestHandler.xml +++ b/xml/System.Net.Http/WebRequestHandler.xml @@ -66,7 +66,7 @@ property to indicate a preference for pipelined connections. When is `true`, an application makes pipelined connections to the servers that support them. + An application uses the property to indicate a preference for pipelined connections. When is `true`, an application makes pipelined connections to the servers that support them. ]]> @@ -124,7 +124,7 @@ ## Remarks The current cache policy and the presence of the requested resource in the cache determine whether a response can be retrieved from the cache. Using cached responses usually improves application performance, but there is a risk that the response in the cache does not match the response on the server. - The default cache policy can be specified in the Machine.config configuration file or by setting the property. + The default cache policy can be specified in the Machine.config configuration file or by setting the property. A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request. @@ -226,9 +226,9 @@ ## Remarks The length of the response header includes the response status line and any extra control characters that are received as part of HTTP protocol. A value of -1 means no limit is imposed on the response headers; a value of 0 means that all requests fail. - If the property is not explicitly set, it defaults to the value of the property. + If the property is not explicitly set, it defaults to the value of the property. - If the length of the response header received exceeds the value of the property, an exception is thrown when the response is accessed. + If the length of the response header received exceeds the value of the property, an exception is thrown when the response is accessed. ]]> @@ -320,7 +320,7 @@ You may want to consider enabling this mechanism if your are having performance problems and your application is running on a Web server with integrated Windows authentication. - Enabling this setting opens the system to security risks. If you set the property to `true` be sure to take the following precautions: + Enabling this setting opens the system to security risks. If you set the property to `true` be sure to take the following precautions: - Run your application in a protected environment to help avoid possible connection exploits. diff --git a/xml/System.Net.Http/WinHttpHandler.xml b/xml/System.Net.Http/WinHttpHandler.xml index d7b2caef659..2fd36d731f3 100644 --- a/xml/System.Net.Http/WinHttpHandler.xml +++ b/xml/System.Net.Http/WinHttpHandler.xml @@ -297,7 +297,7 @@ When this property is set to `true`, all HTTP redirect responses from the server . If this value is set to , then a container object must be initialized and assigned to the property. Otherwise, an exception will be thrown when trying to send a request. + The default for this property is . If this value is set to , then a container object must be initialized and assigned to the property. Otherwise, an exception will be thrown when trying to send a request. ]]> diff --git a/xml/System.Net.Mail/Attachment.xml b/xml/System.Net.Mail/Attachment.xml index b41f8a39fdc..0aae5bfbdb2 100644 --- a/xml/System.Net.Mail/Attachment.xml +++ b/xml/System.Net.Mail/Attachment.xml @@ -58,11 +58,11 @@ Attachment content can be a , , or file name. You can specify the content in an attachment by using any of the constructors. - The MIME Content-Type header information for the attachment is represented by the property. The Content-Type header specifies the media type and subtype and any associated parameters. Use to get the instance associated with an attachment. + The MIME Content-Type header information for the attachment is represented by the property. The Content-Type header specifies the media type and subtype and any associated parameters. Use to get the instance associated with an attachment. - The MIME Content-Disposition header is represented by the property. The Content-Disposition header specifies the presentation and file time stamps for an attachment. A Content-Disposition header is sent only if the attachment is a file. Use the property to get the instance associated with an attachment. + The MIME Content-Disposition header is represented by the property. The Content-Disposition header specifies the presentation and file time stamps for an attachment. A Content-Disposition header is sent only if the attachment is a file. Use the property to get the instance associated with an attachment. - The MIME Content-Transfer-Encoding header is represented by the property. + The MIME Content-Transfer-Encoding header is represented by the property. @@ -193,9 +193,9 @@ property is set to . + The property is set to . - If the stream's property is `false`, the attachment and the that contains it are not reusable. You must supply a stream that can be searched to reuse an attachment. + If the stream's property is `false`, the attachment and the that contains it are not reusable. You must supply a stream that can be searched to reuse an attachment. @@ -266,9 +266,9 @@ (""), the for this attachment is constructed with the property set to `name`. The property is set to . + If `name` is not `null` or equal to (""), the for this attachment is constructed with the property set to `name`. The property is set to . - If the stream's property is `false`, the attachment and the that contains it are not reusable. You must supply a stream that can be searched in order to reuse an attachment. + If the stream's property is `false`, the attachment and the that contains it are not reusable. You must supply a stream that can be searched in order to reuse an attachment. @@ -382,7 +382,7 @@ (""), the property for this attachment is set to . If `mediaType` is not `null` and is not a zero-length string, it is used to construct the associated with this attachment. + If `mediaType` is `null` or equal to (""), the property for this attachment is set to . If `mediaType` is not `null` and is not a zero-length string, it is used to construct the associated with this attachment. @@ -455,9 +455,9 @@ ## Remarks If `mediaType` is not `null` or equal to (""), it is used to construct the class associated with this attachment. - If `mediaType` and `name` both contain information, the value specified in `name` is used. The property is set to . + If `mediaType` and `name` both contain information, the value specified in `name` is used. The property is set to . - If the stream's property is `false`, the attachment and the that contains it are not reusable. You must supply a stream that can be searched in order to reuse an attachment. + If the stream's property is `false`, the attachment and the that contains it are not reusable. You must supply a stream that can be searched in order to reuse an attachment. ## Examples The following code example demonstrates how to call this constructor. @@ -763,7 +763,7 @@ property is used in the Content-Type header generated for this attachment. The is displayed as the attachment's name when the email with the attachment is received. A grammar that details the syntax of the Content-Type header is described in RFC 2045 Section 5.1. RFC 2046 provides detailed information about MIME media types and their parameters. These RFCs are available at [https://www.ietf.org/](https://www.ietf.org/). + The property is used in the Content-Type header generated for this attachment. The is displayed as the attachment's name when the email with the attachment is received. A grammar that details the syntax of the Content-Type header is described in RFC 2045 Section 5.1. RFC 2046 provides detailed information about MIME media types and their parameters. These RFCs are available at [https://www.ietf.org/](https://www.ietf.org/). diff --git a/xml/System.Net.Mail/AttachmentCollection.xml b/xml/System.Net.Mail/AttachmentCollection.xml index 5f60c79aa63..d06900bb525 100644 --- a/xml/System.Net.Mail/AttachmentCollection.xml +++ b/xml/System.Net.Mail/AttachmentCollection.xml @@ -63,15 +63,15 @@ ## Remarks Instances of the class are returned by the and properties. - Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want provide a plain text version in case some of the recipients use email readers that cannot display HTML content. + Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want provide a plain text version in case some of the recipients use email readers that cannot display HTML content. - Use the collection returned by the property to add an attachment, such as a file or the contents of a to this . + Use the collection returned by the property to add an attachment, such as a file or the contents of a to this . ## Examples The following code example demonstrates how to create and send an email message with an attachment. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet6"::: ]]> diff --git a/xml/System.Net.Mail/LinkedResourceCollection.xml b/xml/System.Net.Mail/LinkedResourceCollection.xml index 809fce6d780..3eb5c4133ec 100644 --- a/xml/System.Net.Mail/LinkedResourceCollection.xml +++ b/xml/System.Net.Mail/LinkedResourceCollection.xml @@ -58,11 +58,11 @@ Stores linked resources to be sent as part of an email message. - class is returned by the property. - + class is returned by the property. + ]]> @@ -150,16 +150,16 @@ Releases all resources used by the . - when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the occupied. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - - This method invokes on all views in this collection. This method is called by the method. You do not need to call it in your application. - + when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the occupied. For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + + This method invokes on all views in this collection. This method is called by the method. You do not need to call it in your application. + > [!NOTE] -> Always call before you release your last reference to the . Otherwise, the resources it is using are not freed until the garbage collector calls the object's `Finalize` method. - +> Always call before you release your last reference to the . Otherwise, the resources it is using are not freed until the garbage collector calls the object's `Finalize` method. + ]]> diff --git a/xml/System.Net.Mail/MailAddressCollection.xml b/xml/System.Net.Mail/MailAddressCollection.xml index 0b87318854d..1d408687529 100644 --- a/xml/System.Net.Mail/MailAddressCollection.xml +++ b/xml/System.Net.Mail/MailAddressCollection.xml @@ -64,8 +64,8 @@ ## Examples - The following example adds an email address to the that is returned by the property. - + The following example adds an email address to the that is returned by the property. + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: ]]> @@ -312,7 +312,7 @@ ## Examples - The following example displays the email addresses in the that are returned by the property. + The following example displays the email addresses in the that are returned by the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet9"::: diff --git a/xml/System.Net.Mail/MailMessage.xml b/xml/System.Net.Mail/MailMessage.xml index 61970fdc402..82527f41995 100644 --- a/xml/System.Net.Mail/MailMessage.xml +++ b/xml/System.Net.Mail/MailMessage.xml @@ -78,9 +78,9 @@ |Sender|| |Subject|| - The class also allows an application to access the headers collection for the message using the property. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After a the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. + The class also allows an application to access the headers collection for the message using the property. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After a the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. - If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: + If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: - Bcc - Cc @@ -98,11 +98,11 @@ - To - X-Priority - If the application does not specify an X-Sender header using the property, the class will create one when the message is sent. + If the application does not specify an X-Sender header using the property, the class will create one when the message is sent. - Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. For an example that demonstrates creating a message with alternate views, see . + Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. For an example that demonstrates creating a message with alternate views, see . - Use the property to add attachments to an email message. For an example that demonstrates creating a message with an attachment, see . Calling Dispose on the MailMessage also calls Dispose on each referenced Attachment. + Use the property to add attachments to an email message. For an example that demonstrates creating a message with an attachment, see . Calling Dispose on the MailMessage also calls Dispose on each referenced Attachment. After assembling your email message, you can send it by using the or methods. @@ -216,7 +216,7 @@ property is initialized using `from` and the property is initialized using `to`. + The property is initialized using `from` and the property is initialized using `to`. ## Examples The following code example demonstrates calling this constructor. @@ -280,7 +280,7 @@ property is initialized using `from` and the property is initialized using `to`. + The property is initialized using `from` and the property is initialized using `to`. @@ -450,9 +450,9 @@ property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. + Use the property to specify copies of an email message in different formats. For example, if you send a message in HTML, you might also want to provide a plain text version in case some of the recipients use email readers that cannot display HTML content. - To add an alternate view to a object, create an for the view, and then add it to the collection returned by . Use the property to specify the text version and use the collection to specify views with other MIME types. Use the class members to specify the MIME type for the alternate view. + To add an alternate view to a object, create an for the view, and then add it to the collection returned by . Use the property to specify the text version and use the collection to specify views with other MIME types. Use the class members to specify the MIME type for the alternate view. @@ -508,7 +508,7 @@ property to add an attachment, such as a file or the contents of a , to this . + Use the collection returned by the property to add an attachment, such as a file or the contents of a , to this . Create an that contains or references the data to be attached, and then add the to the collection returned by . @@ -566,7 +566,7 @@ for the recipient's address, and then add that object to the collection returned by the property. + To add a BCC recipient to an email message, create a for the recipient's address, and then add that object to the collection returned by the property. When recipients view an email message, the addresses are usually not displayed. @@ -624,14 +624,14 @@ of the content is "text/plain". Specify the encoding used for the body with the property. + The of the content is "text/plain". Specify the encoding used for the body with the property. - If the body content is available in alternative formats that provide richer presentation options for the recipients, you can specify alternate views for the body content by using the property. For example, an application might choose to send both the plain text body and an HTML version of the message body. Email readers that can display HTML can present the HTML version of the body to the recipient, while readers that cannot display HTML will display the plain text version of the message instead. + If the body content is available in alternative formats that provide richer presentation options for the recipients, you can specify alternate views for the body content by using the property. For example, an application might choose to send both the plain text body and an HTML version of the message body. Email readers that can display HTML can present the HTML version of the body to the recipient, while readers that cannot display HTML will display the plain text version of the message instead. ## Examples - The following code example demonstrates setting the property. + The following code example demonstrates setting the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailMessage/Overview/mail.vb" id="Snippet2"::: @@ -697,9 +697,9 @@ property sets the character set field in the Content-Type header. The default character set is `"us-ascii"`. + The value specified for the property sets the character set field in the Content-Type header. The default character set is `"us-ascii"`. - If you set the property to , , or , the Framework selects a of for this . + If you set the property to , , or , the Framework selects a of for this . @@ -799,7 +799,7 @@ for the recipient's address and then add that object to the collection returned by the property. + To add a CC recipient to an email message, create a for the recipient's address and then add that object to the collection returned by the property. @@ -1049,7 +1049,7 @@ ## Examples - The following code example demonstrates setting a value for the property. + The following code example demonstrates setting a value for the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailMessage/Overview/mail.vb" id="Snippet10"::: @@ -1100,9 +1100,9 @@ property allows an application to access the headers collection for the message. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. + The property allows an application to access the headers collection for the message. While this collection is read-only (a new collection can not be set), custom headers can be added to or deleted from this collection. Any custom headers added will be included when the instance is sent. Before a message is sent, only headers specifically added to this collection in the property are included in the collection. After the instance is sent, the property will also include headers that are set using the associated properties of the class or parameters passed when a is used to initialize a object. - If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: + If some mail headers are malformed, they could cause the email message to become corrupted. So any mail header in the headers collection that can be set using a property on the class should only be set using the class property or as a parameter passed when a initializes a object. The following list of mail headers should not be added using the property and any values set for these headers using the property will be discarded or overwritten when the message is sent: - Bcc @@ -1134,7 +1134,7 @@ - X-Priority - If the application does not specify an X-Sender header using the property, the class will create one when the message is sent. + If the application does not specify an X-Sender header using the property, the class will create one when the message is sent. The sender, recipient, subject, and body of an email message may be specified as parameters when a is used to initialize a object. These parameters may also be set or accessed using properties on the object. @@ -1214,7 +1214,7 @@ property defaults to . + The value of the property defaults to . SMTP messages consist of headers and body parts. The IETF RFCs for SMTP restrict the header and body part names to be ASCII. However, the IETF RFCs allow header and body part values to contain Unicode characters. In any particular value, if non-ASCII characters exist, then the value is encoded using a combination of character encoding (UTF8 or Shift-JIS, for example) followed by byte encoding ( or for example). The result is usually that only ASCII characters are in the network transmission stream. @@ -1380,7 +1380,7 @@ property to indicate an address other than the address to use to reply to this message. + Use the property to indicate an address other than the address to use to reply to this message. ]]> @@ -1427,9 +1427,9 @@ property to indicate the list of addresses other than the address to use to reply to this message. + Use the property to indicate the list of addresses other than the address to use to reply to this message. - The property replaces the property that only allows a single address to reply to. + The property replaces the property that only allows a single address to reply to. ]]> @@ -1532,12 +1532,12 @@ property. + Specify the encoding used for the subject by using the property. ## Examples - The following code example demonstrates setting the property. + The following code example demonstrates setting the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailMessage/Overview/mail.vb" id="Snippet2"::: @@ -1600,7 +1600,7 @@ ## Examples - The following code example demonstrates setting the property. + The following code example demonstrates setting the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/MailAddress/.ctor/mailasync.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailAddress/.ctor/mailasync.vb" id="Snippet3"::: @@ -1655,12 +1655,12 @@ property is used to designate the addresses on the To line of an email message. To add a recipient to an email message, create a for the recipient's address, and then add that object to the collection returned by this property. + The property is used to designate the addresses on the To line of an email message. To add a recipient to an email message, create a for the recipient's address, and then add that object to the collection returned by this property. ## Examples - The following code example demonstrates setting the property. + The following code example demonstrates setting the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Mail/MailMessage/Overview/mail.vb" id="Snippet7"::: diff --git a/xml/System.Net.Mail/SmtpClient.xml b/xml/System.Net.Mail/SmtpClient.xml index 0f279b92343..028dee27559 100644 --- a/xml/System.Net.Mail/SmtpClient.xml +++ b/xml/System.Net.Mail/SmtpClient.xml @@ -88,12 +88,12 @@ The classes shown in the following table are used to construct email messages th To construct and send an email message by using , you must specify the following information: - The SMTP host server that you use to send email. See the and properties. -- Credentials for authentication, if required by the SMTP server. See the property. -- The email address of the sender. See the and methods that take a `from` parameter. Also see the property. -- The email address or addresses of the recipients. See the and methods that take a `recipient` parameter. Also see the property. -- The message content. See the and methods that take a `body` parameter. Also see the property. +- Credentials for authentication, if required by the SMTP server. See the property. +- The email address of the sender. See the and methods that take a `from` parameter. Also see the property. +- The email address or addresses of the recipients. See the and methods that take a `recipient` parameter. Also see the property. +- The message content. See the and methods that take a `body` parameter. Also see the property. -To include an attachment with an email message, first create the attachment by using the class, and then add it to the message by using the property. Depending on the email reader used by the recipients and the file type of the attachment, some recipients might not be able to read the attachment. For clients that cannot display the attachment in its original form, you can specify alternate views by using the property. +To include an attachment with an email message, first create the attachment by using the class, and then add it to the message by using the property. Depending on the email reader used by the recipients and the file type of the attachment, some recipients might not be able to read the attachment. For clients that cannot display the attachment in its original form, you can specify alternate views by using the property. In .NET Framework, you can use the application or machine configuration files to specify default host, port, and credentials values for all objects. For more information, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). .NET Core does not support setting defaults. As a workaround, you must set the relevant properties on directly. @@ -108,7 +108,7 @@ To include an attachment with an email message, first create the attachment by u When an SMTP session is finished and the client wishes to terminate the connection, it must send a QUIT message to the server to indicate that it has no more messages to send. This allows the server to free up resources associated with the connection from the client and process the messages which were sent by the client. - The class has no `Finalize` method, so an application must call to explicitly free up resources. The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the and optionally disposes of the managed resources. + The class has no `Finalize` method, so an application must call to explicitly free up resources. The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the and optionally disposes of the managed resources. Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. @@ -234,7 +234,7 @@ The following code example demonstrates sending an email message asynchronously. property. The and properties are initialized by using the settings in the application or machine configuration files. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. + The `host` parameter is used to initialize the value of the property. The and properties are initialized by using the settings in the application or machine configuration files. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. For more information about using the application and machine configuration files, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). If information is specified using constructors or properties, this information overrides the configuration file settings. @@ -294,7 +294,7 @@ The following code example demonstrates sending an email message asynchronously. and properties, respectively. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. If `port` is zero, is initialized using the settings in the application or machine configuration files. The property is initialized using the settings in the application or machine configuration files. + The `host` and `port` parameters set the value of the and properties, respectively. If `host` is `null` or equal to , is initialized using the settings in the application or machine configuration files. If `port` is zero, is initialized using the settings in the application or machine configuration files. The property is initialized using the settings in the application or machine configuration files. For more information about using the application and machine configuration files, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). If information is specified using constructors or properties, this information overrides the configuration file settings. @@ -419,9 +419,9 @@ The following code example demonstrates sending an email message asynchronously. to `true` instead of setting this property. If the property is set to `false,` then the value set in the property will be used for the credentials when connecting to the server. If the property is set to `false` and the property has not been set, then mail is sent to the server anonymously. + Some SMTP servers require that the client be authenticated before the server will send email on its behalf. To use your default network credentials, you can set the to `true` instead of setting this property. If the property is set to `false,` then the value set in the property will be used for the credentials when connecting to the server. If the property is set to `false` and the property has not been set, then mail is sent to the server anonymously. - Credentials information can also be specified using the application and machine configuration files. For more information, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). If information is specified using the property, this information overrides the configuration file settings. + Credentials information can also be specified using the application and machine configuration files. For more information, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). If information is specified using the property, this information overrides the configuration file settings. > [!CAUTION] > If you provide credentials for basic authentication, they are sent to the server in clear text. This can present a security issue because your credentials can be seen, and then used by others. @@ -538,7 +538,7 @@ The following code example demonstrates sending an email message asynchronously. - Moving the email to a directory specified by for later delivery by another application. - The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings. + The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings. ]]> @@ -626,7 +626,7 @@ The following code example demonstrates sending an email message asynchronously. The class has no `Finalize` method. So an application must call to explicitly free up resources. - The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the underlying . + The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the underlying . Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. @@ -694,7 +694,7 @@ The following code example demonstrates sending an email message asynchronously. The class has no `Finalize` method. So an application must call to explicitly free up resources. - The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the and optionally disposes of the managed resources. + The method iterates through all established connections to the SMTP server specified in the property and sends a QUIT message followed by gracefully ending the TCP connection. The method also releases the unmanaged resources used by the and optionally disposes of the managed resources. Call when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. @@ -750,18 +750,18 @@ The following code example demonstrates sending an email message asynchronously. property specifies whether SSL is used to access the specified SMTP mail server. + The property specifies whether SSL is used to access the specified SMTP mail server. - The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings. + The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings. The class only supports the SMTP Service Extension for Secure SMTP over Transport Layer Security as defined in RFC 3207. In this mode, the SMTP session begins on an unencrypted channel, then a STARTTLS command is issued by the client to the server to switch to secure communication using SSL. See RFC 3207 published by the Internet Engineering Task Force (IETF) for more information. An alternate connection method is where an SSL session is established up front before any protocol commands are sent. This connection method is sometimes called SMTP/SSL, SMTP over SSL, or SMTPS and by default uses port 465. This alternate connection method using SSL is not currently supported. - You can use to specify which client certificates should be used to establish the SSL connection. The allows you to reject the certificate provided by the SMTP server. The property allows you to specify the version of the SSL protocol to use. + You can use to specify which client certificates should be used to establish the SSL connection. The allows you to reject the certificate provided by the SMTP server. The property allows you to specify the version of the SSL protocol to use. > [!NOTE] -> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . +> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . @@ -829,7 +829,7 @@ The following code example demonstrates sending an email message asynchronously. property can also be set using constructors or the application or machine configuration file. For more information, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). + The value of the property can also be set using constructors or the application or machine configuration file. For more information, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). If information is specified using this property, this information overrides the configuration file settings. @@ -965,7 +965,7 @@ The following code example demonstrates sending an email message asynchronously. ## Remarks Mail messages in the pickup directory are automatically sent by a local SMTP server (if present), such as IIS. - The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings. + The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings. ]]> @@ -1023,7 +1023,7 @@ The following code example demonstrates sending an email message asynchronously. property can also be set using constructors or the application or machine configuration file. For more information about using configuration files, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). If information is specified using this property, this information overrides the configuration file settings. + The value of the property can also be set using constructors or the application or machine configuration file. For more information about using configuration files, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). If information is specified using this property, this information overrides the configuration file settings. @@ -1100,7 +1100,7 @@ The following code example demonstrates sending an email message asynchronously. property to ensure that the method returns after a specified amount of time elapses. + This method blocks while the email is transmitted. You can specify a time-out value using the property to ensure that the method returns after a specified amount of time elapses. Before calling this method, the and properties must be set either through the configuration files by setting the relevant properties, or by passing this information into the constructor. @@ -1108,12 +1108,12 @@ The following code example demonstrates sending an email message asynchronously. If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties. - If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. + If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. When sending email using to multiple recipients and the SMTP server accepts some recipients as valid and rejects others, sends email to the accepted recipients and then a is thrown (or a if only one recipient is rejected). A contains a list of the recipients that were rejected. > [!NOTE] -> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . +> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . ## Examples The following code example demonstrates using this method. @@ -1233,7 +1233,7 @@ The following code example demonstrates sending an email message asynchronously. property to ensure that the method returns after a specified amount of time elapses. + This method blocks while the email is transmitted. You can specify a time-out value using the property to ensure that the method returns after a specified amount of time elapses. Before calling this method, the and properties must be set either through the configuration files by setting the relevant properties, or by passing this information into the constructor. @@ -1241,12 +1241,12 @@ The following code example demonstrates sending an email message asynchronously. If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties. - If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. + If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. When sending email using to multiple recipients and the SMTP server accepts some recipients as valid and rejects others, sends email to the accepted recipients and then a is thrown (or a if only one recipient is rejected). A contains a list of the recipients that were rejected. > [!NOTE] -> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . +> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . ]]> @@ -1370,18 +1370,18 @@ The following code example demonstrates sending an email message asynchronously. If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or properties. - If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. + If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. When sending email using to multiple recipients, if the SMTP server accepts some recipients as valid and rejects others, a is thrown with a for the inner exception. If this occurs, fails to send email to any of the recipients. - Your application can detect a server certificate validation error by examining the property passed into the delegate. + Your application can detect a server certificate validation error by examining the property passed into the delegate. - The property does not have any effect on a call. + The property does not have any effect on a call. To send mail and block while it is transmitted to the SMTP server, use one of the methods. > [!NOTE] -> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . +> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . ## Examples The following code example demonstrates calling this method. @@ -1514,20 +1514,20 @@ The following code example demonstrates sending an email message asynchronously. Before calling this method, the and properties must be set either through the configuration files or by setting the properties or passing this information into the constructor. - If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or property. + If the SMTP host requires credentials, you must set them before calling this method. To specify credentials, use the or property. - If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. + If you receive an exception, check the property to find the reason the operation failed. The can also contain an inner exception that indicates the reason the operation failed. When sending email using to multiple recipients, if the SMTP server accepts some recipients as valid and rejects others, a is thrown with a for the inner exception. If this occurs, fails to send email to any of the recipients. - Your application can detect a server certificate validation error by examining the property passed into the delegate. + Your application can detect a server certificate validation error by examining the property passed into the delegate. - The property does not have any effect on a call. + The property does not have any effect on a call. To send mail and block while it is transmitted to the SMTP server, use one of the methods. > [!NOTE] -> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . +> If the property is set to `true`, and the SMTP mail server does not advertise STARTTLS in the response to the EHLO command, then a call to the or methods will throw an . ]]> @@ -2179,7 +2179,7 @@ The following code example demonstrates sending an email message asynchronously. property are created using defaults specified in the application or machine configuration files and the class. + The settings for the property are created using defaults specified in the application or machine configuration files and the class. ]]> @@ -2246,9 +2246,9 @@ The following code example demonstrates sending an email message asynchronously. property is used with integrated Windows authentication when an application is using extended protection. The can then provide extended protection to ensure that credential challenge responses contain service specific information (a SPN) and, if necessary, channel specific information (a channel binding token or CBT). With this information in the credential exchanges, services are able to better protect against malicious use of credential challenge responses that might have been improperly obtained. + The property is used with integrated Windows authentication when an application is using extended protection. The can then provide extended protection to ensure that credential challenge responses contain service specific information (a SPN) and, if necessary, channel specific information (a channel binding token or CBT). With this information in the credential exchanges, services are able to better protect against malicious use of credential challenge responses that might have been improperly obtained. - The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings. + The default value for this property can also be set in a machine or application configuration file. Any changes made to the property override the configuration file settings. ]]> @@ -2303,7 +2303,7 @@ The following code example demonstrates sending an email message asynchronously. method block until the operation completes. If you set the property to a positive value, and a operation cannot complete in the allotted time, the class throws an exception. + By default, calls to the method block until the operation completes. If you set the property to a positive value, and a operation cannot complete in the allotted time, the class throws an exception. To send a message and continue executing in the application thread, use the method. @@ -2367,7 +2367,7 @@ The following code example demonstrates sending an email message asynchronously. Credentials information can also be specified using the application and machine configuration files. For more information, see [<mailSettings> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/mailsettings-element-network-settings). - If the property is set to `false,` then the value set in the property will be used for the credentials when connecting to the server. If the property is set to `false` and the property has not been set, then mail is sent to the server anonymously. + If the property is set to `false,` then the value set in the property will be used for the credentials when connecting to the server. If the property is set to `false` and the property has not been set, then mail is sent to the server anonymously. > [!CAUTION] > If you provide credentials for basic authentication, they are sent to the server in clear text. This can present a security issue because your credentials can be seen, and then used by others. diff --git a/xml/System.Net.Mail/SmtpException.xml b/xml/System.Net.Mail/SmtpException.xml index 229a5ad06e0..4ffe9b94267 100644 --- a/xml/System.Net.Mail/SmtpException.xml +++ b/xml/System.Net.Mail/SmtpException.xml @@ -65,13 +65,13 @@ property contains the status code returned by the SMTP server. + The property contains the status code returned by the SMTP server. ## Examples The following code example displays an error message when the exception is thrown. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet27"::: ]]> @@ -132,7 +132,7 @@ property set to . + The exception returned by this constructor has its property set to . @@ -187,7 +187,7 @@ property. + This constructor uses the `statusCode` parameter to initialize the property. @@ -243,7 +243,7 @@ property. + This constructor uses the `message` parameter to initialize the property. @@ -301,7 +301,7 @@ property and uses the `message` parameter to initialize the property. + This constructor uses the `statusCode` parameter to initialize the property and uses the `message` parameter to initialize the property. @@ -419,7 +419,7 @@ property and the `innerException` parameter to initialize the property. + This constructor uses the `message` parameter to initialize the property and the `innerException` parameter to initialize the property. If `innerException` is not `null`, the current exception is raised in a catch block that handles `innerException`. diff --git a/xml/System.Net.Mail/SmtpFailedRecipientException.xml b/xml/System.Net.Mail/SmtpFailedRecipientException.xml index 87b2375897a..2f453355f94 100644 --- a/xml/System.Net.Mail/SmtpFailedRecipientException.xml +++ b/xml/System.Net.Mail/SmtpFailedRecipientException.xml @@ -163,11 +163,11 @@ A that contains the error message. Initializes a new instance of the class with the specified error message. - property. - + property. + ]]> @@ -220,11 +220,11 @@ A that contains the email address. Initializes a new instance of the class with the specified status code and email address. - property and uses the `failedRecipient` parameter to initialize the property. - + property and uses the `failedRecipient` parameter to initialize the property. + ]]> @@ -280,11 +280,11 @@ A that contains the source and destination of the serialized stream that is associated with the new instance. Initializes a new instance of the class from the specified instances of the and classes. - interface for the class. - + interface for the class. + ]]> @@ -383,11 +383,11 @@ A that contains the server response. Initializes a new instance of the class with the specified status code, email address, and server response. - property and uses the `failedRecipient` parameter to initialize the property. - + property and uses the `failedRecipient` parameter to initialize the property. + ]]> @@ -546,11 +546,11 @@ A that specifies the destination for this serialization. Populates a instance with the data that is needed to serialize the . - are automatically tracked and serialized by the formatter. - + are automatically tracked and serialized by the formatter. + ]]> diff --git a/xml/System.Net.Mail/SmtpFailedRecipientsException.xml b/xml/System.Net.Mail/SmtpFailedRecipientsException.xml index 48ceab5b411..4b46eccd5f5 100644 --- a/xml/System.Net.Mail/SmtpFailedRecipientsException.xml +++ b/xml/System.Net.Mail/SmtpFailedRecipientsException.xml @@ -65,13 +65,13 @@ property contains the exceptions received while attempting to send email. The email might have been successfully delivered to some of the recipients. + The property contains the exceptions received while attempting to send email. The email might have been successfully delivered to some of the recipients. ## Examples The following code example resends an email message that was not delivered because a mailbox was busy or unavailable. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet27"::: ]]> diff --git a/xml/System.Net.Mime/ContentDisposition.xml b/xml/System.Net.Mime/ContentDisposition.xml index 3289b533f28..35154929ed0 100644 --- a/xml/System.Net.Mime/ContentDisposition.xml +++ b/xml/System.Net.Mime/ContentDisposition.xml @@ -57,9 +57,9 @@ ## Remarks The information in the class accompanies an email message that contains attachments when the email message is sent to its destination. The information in can be used by software that displays email to present the email attachments in the manner intended by the sender. - Email messages are created using instances of the class. Instances of the class are used to add attachments to email messages. To modify the for an attachment, get the instance from the property. + Email messages are created using instances of the class. Instances of the class are used to add attachments to email messages. To modify the for an attachment, get the instance from the property. - Content to be displayed as part of the message body has the disposition type of . Content that is not displayed but is attached in a separate file has the disposition type of . Use the property to control the disposition type for the attachment associated with an instance of . + Content to be displayed as part of the message body has the disposition type of . Content that is not displayed but is attached in a separate file has the disposition type of . Use the property to control the disposition type for the attachment associated with an instance of . For file attachments, you can use the properties of the to set the file size, as well as the date the file was created, last read, and last modified. For all attachments, you can set a recommended file name in the event that the attachment is stored on the receiving computer. @@ -69,7 +69,7 @@ ## Examples The following code example creates an email message with an attachment to be displayed inline. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet12"::: ]]> @@ -124,7 +124,7 @@ property set to . + The instance returned by this constructor has the property set to . @@ -239,7 +239,7 @@ ## Remarks The property is used to send time stamp information with a file being sent in an email message. This value sets the Creation-Date parameter in the Content-Disposition header sent with the email. - The class is used to compose an email message. The class is used to attach a file to an email message. To set , get the for the attachment from the property. + The class is used to compose an email message. The class is used to attach a file to an email message. To set , get the for the attachment from the property. The Content-Disposition header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). @@ -302,7 +302,7 @@ property value can be used by software that displays email to determine the correct way to present the email attachments. attachments are usually displayed when the user opens the email. attachments are usually not opened until the user performs some action, such as clicking an icon that represents the attachment. + The property value can be used by software that displays email to determine the correct way to present the email attachments. attachments are usually displayed when the user opens the email. attachments are usually not opened until the user performs some action, such as clicking an icon that represents the attachment. The Content-Disposition header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). @@ -422,7 +422,7 @@ property allows the sender to suggest the name to be used to store an email attachment on the recipient's computer. This name is a suggestion only; the receiving system can ignore it. The name must not include path information; any such information is ignored by the receiving computer. + The property allows the sender to suggest the name to be used to store an email attachment on the recipient's computer. This name is a suggestion only; the receiving system can ignore it. The name must not include path information; any such information is ignored by the receiving computer. To remove file name information, you can set this property to `null` or the empty string (""). @@ -524,7 +524,7 @@ property sets the disposition type in the Content-Disposition header sent with the email message. The disposition type can be used by software that displays email to determine the correct way to present the email attachments. Attachments with a disposition type of are usually displayed when the user opens the email. Attachments with a disposition type of are usually not opened until the user performs some additional action, such as clicking an icon that represents the attachment. + The property sets the disposition type in the Content-Disposition header sent with the email message. The disposition type can be used by software that displays email to determine the correct way to present the email attachments. Attachments with a disposition type of are usually displayed when the user opens the email. Attachments with a disposition type of are usually not opened until the user performs some additional action, such as clicking an icon that represents the attachment. The Content-Disposition header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). @@ -587,9 +587,9 @@ property is used to send time stamp information with a file being sent in an email message. This value sets the Modification-Date parameter in the Content-Disposition header sent with the email message. + The property is used to send time stamp information with a file being sent in an email message. This value sets the Modification-Date parameter in the Content-Disposition header sent with the email message. - The class is used to compose an email message. The class is used to attach a file to an email message. To set the property, get the for the attachment using the property. + The class is used to compose an email message. The class is used to attach a file to an email message. To set the property, get the for the attachment using the property. The Content-Disposition header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). @@ -646,7 +646,7 @@ property. + Typically, the parameters are determined by the property values so you do not need to access them. If you need to add or change parameter information, modify the dictionary returned by the property. The Content-Disposition header is described in RFC 2183, available at [https://www.ietf.org](https://www.ietf.org/). @@ -709,9 +709,9 @@ property is used to send time stamp information with a file being sent in an email message. This value sets the Read-Date parameter in the Content-Disposition header sent with the email message. + The property is used to send time stamp information with a file being sent in an email message. This value sets the Read-Date parameter in the Content-Disposition header sent with the email message. - The class is used to compose an email message. The class is used to attach a file to an email message. To set , get the for the attachment by using the property. + The class is used to compose an email message. The class is used to attach a file to an email message. To set , get the for the attachment by using the property. The Content-Disposition header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). @@ -768,7 +768,7 @@ property is used to send time stamp information with a file being sent in an email message. The class is used to compose the message. The class is used to attach a file to an email message. + The property is used to send time stamp information with a file being sent in an email message. The class is used to compose the message. The class is used to attach a file to an email message. The Content-Disposition header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). diff --git a/xml/System.Net.Mime/ContentType.xml b/xml/System.Net.Mime/ContentType.xml index 3a8d840e6e4..c5701bb9f98 100644 --- a/xml/System.Net.Mime/ContentType.xml +++ b/xml/System.Net.Mime/ContentType.xml @@ -62,7 +62,7 @@ ## Examples The following code example sends an email message with an attachment and displays the properties for the attachment. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet6"::: ]]> @@ -119,7 +119,7 @@ property to `"application/octet-stream"`. + This constructor initializes the property to `"application/octet-stream"`. @@ -253,7 +253,7 @@ ## Examples - The following code example displays the value of the property. + The following code example displays the value of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet5"::: @@ -310,7 +310,7 @@ property is "`us-ascii`". + In the following example of a Content-Type header, the value of the property is "`us-ascii`". `content-type: application/x-myType; charset=us-ascii` @@ -467,7 +467,7 @@ property is `"application/x-myType"`. + In the following example of a Content-Type header, the value of the property is `"application/x-myType"`. `content-type: application/x-myType; name=data.xyz` @@ -531,7 +531,7 @@ property is `"data.xyz"`. + In the following example of a Content-Type header, the value of the property is `"data.xyz"`. `content-type: application/x-myType; name=data.xyz` @@ -592,7 +592,7 @@ object or you can add parameters to the returned by the property. + You can set the parameters by specifying the entire Content-Header value when constructing a object or you can add parameters to the returned by the property. When adding a parameter entry to the dictionary, the name of the parameter is the entry's key and the value of the parameter is the entry's value. diff --git a/xml/System.Net.Mime/DispositionTypeNames.xml b/xml/System.Net.Mime/DispositionTypeNames.xml index b84a264d290..5f32c7bb3f2 100644 --- a/xml/System.Net.Mime/DispositionTypeNames.xml +++ b/xml/System.Net.Mime/DispositionTypeNames.xml @@ -54,13 +54,13 @@ property for an email attachment. The information in the class represents the MIME Content-Disposition header. This header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). + The values in this enumeration can be used to set the property for an email attachment. The information in the class represents the MIME Content-Disposition header. This header is described in RFC 2183 available at [https://www.ietf.org](https://www.ietf.org/). ## Examples The following code example sets the disposition type for an attachment. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Mail/Attachment/Overview/mail.cs" id="Snippet26"::: ]]> diff --git a/xml/System.Net.NetworkInformation/GatewayIPAddressInformationCollection.xml b/xml/System.Net.NetworkInformation/GatewayIPAddressInformationCollection.xml index 622bda34987..bfcb7900a8d 100644 --- a/xml/System.Net.NetworkInformation/GatewayIPAddressInformationCollection.xml +++ b/xml/System.Net.NetworkInformation/GatewayIPAddressInformationCollection.xml @@ -408,7 +408,7 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . @@ -612,7 +612,7 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . diff --git a/xml/System.Net.NetworkInformation/IPAddressCollection.xml b/xml/System.Net.NetworkInformation/IPAddressCollection.xml index 2ca8165b880..08c8159a713 100644 --- a/xml/System.Net.NetworkInformation/IPAddressCollection.xml +++ b/xml/System.Net.NetworkInformation/IPAddressCollection.xml @@ -296,11 +296,11 @@ The zero-based index in at which the copy begins. Copies the elements in this collection to a one-dimensional array of type . - @@ -308,9 +308,9 @@ is less than zero. - is multidimensional. + is multidimensional. --or- +-or- The number of elements in this is greater than the available space from to the end of the destination . The elements in this cannot be cast automatically to the type of the destination . @@ -405,15 +405,15 @@ The number of elements in this interface and provides access to the types in this collection. - method before you can access the first element. To access the element at the current position, call the property. - - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - - For a detailed description of enumerators, see the documentation for the class and the method. - + method before you can access the first element. To access the element at the current position, call the property. + + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + + For a detailed description of enumerators, see the documentation for the class and the method. + ]]> @@ -609,15 +609,15 @@ The number of elements in this interface and provides access to the types in this collection. - method before you can access the first element. To access the element at the current position, call the property. - - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - - For a detailed description of enumerators, see the documentation for the class and the method. - + method before you can access the first element. To access the element at the current position, call the property. + + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + + For a detailed description of enumerators, see the documentation for the class and the method. + ]]> diff --git a/xml/System.Net.NetworkInformation/IPAddressInformationCollection.xml b/xml/System.Net.NetworkInformation/IPAddressInformationCollection.xml index 64d04d88363..6b9d3a8a433 100644 --- a/xml/System.Net.NetworkInformation/IPAddressInformationCollection.xml +++ b/xml/System.Net.NetworkInformation/IPAddressInformationCollection.xml @@ -65,11 +65,11 @@ Stores a set of types. - property returns a member of the collection. - + property returns a member of the collection. + ]]> @@ -265,11 +265,11 @@ The zero-based index in at which the copy begins. Copies the collection to the specified array. - @@ -277,10 +277,10 @@ is less than zero. - is multidimensional. - - -or- - + is multidimensional. + + -or- + The number of elements in this is greater than the available space from to the end of the destination . The elements in this cannot be cast automatically to the type of the destination . @@ -374,15 +374,15 @@ Returns an object that can be used to iterate through this collection. An object that implements the interface and provides access to the types in this collection. - method before you can access the first element. To access the element at the current position, call the property. - - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - - For a detailed description of enumerators, see the documentation for the class and the method. - + method before you can access the first element. To access the element at the current position, call the property. + + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + + For a detailed description of enumerators, see the documentation for the class and the method. + ]]> @@ -578,15 +578,15 @@ Returns an object that can be used to iterate through this collection. An object that implements the interface and provides access to the types in this collection. - method before you can access the first element. To access the element at the current position, call the property. - - Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . - - For a detailed description of enumerators, see the documentation for the class and the method. - + method before you can access the first element. To access the element at the current position, call the property. + + Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . + + For a detailed description of enumerators, see the documentation for the class and the method. + ]]> diff --git a/xml/System.Net.NetworkInformation/IPGlobalProperties.xml b/xml/System.Net.NetworkInformation/IPGlobalProperties.xml index d3d68ad0665..eeacc8ebbaf 100644 --- a/xml/System.Net.NetworkInformation/IPGlobalProperties.xml +++ b/xml/System.Net.NetworkInformation/IPGlobalProperties.xml @@ -61,7 +61,7 @@ ## Examples The following code example displays information about the local computer using an instance of this class. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.cs" id="Snippet15"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.vb" id="Snippet15"::: @@ -176,7 +176,7 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. @@ -351,7 +351,7 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method allows an application to asynchronously retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. The method ends a pending asynchronous request to retrieve the stable unicast IP address table. @@ -1220,7 +1220,7 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method will allow an application to retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method will allow an application to retrieve the list of stable unicast IP addresses. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. @@ -1281,7 +1281,7 @@ ## Remarks In order to support outbound connections or to accept incoming connections on a Teredo interface, applications need to ensure that the Teredo interface is up and ready for use. This is because Teredo can go into a dormant state when not used for some period of time. - The method will allow an application to retrieve the list of stable unicast IP addresses as asynchronous operation. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. + The method will allow an application to retrieve the list of stable unicast IP addresses as asynchronous operation. The property can be used to determine if an IP address is an IPv6 Teredo address with the prefix of 2001::/32. The method also returns non-Teredo addresses and provides a more convenient way to obtain the unicast IP addresses for a system than enumerating all the objects on a local computer and querying the associated IP addresses. diff --git a/xml/System.Net.NetworkInformation/IPStatus.xml b/xml/System.Net.NetworkInformation/IPStatus.xml index 363d59be71d..fcdd4c66586 100644 --- a/xml/System.Net.NetworkInformation/IPStatus.xml +++ b/xml/System.Net.NetworkInformation/IPStatus.xml @@ -48,7 +48,7 @@ class uses the values in this enumeration to set the property. The class returns objects when you call the or methods to check whether you can reach a computer across the network. + The class uses the values in this enumeration to set the property. The class returns objects when you call the or methods to check whether you can reach a computer across the network. > [!WARNING] > The DestinationProhibited and DestinationProtocolUnreachable enumeration values have the same numeric value. This is possible because DestinationProhibited applies only to IPv6 and DestinationProtocolUnreachable applies only to IPv4. @@ -57,7 +57,7 @@ ## Examples The following code example sends an ICMP echo message and checks the status. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IPStatus/Overview/syncping.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Net.NetworkInformation/IPStatus/Overview/syncping.fs" id="Snippet1"::: diff --git a/xml/System.Net.NetworkInformation/MulticastIPAddressInformation.xml b/xml/System.Net.NetworkInformation/MulticastIPAddressInformation.xml index f021ec88b59..35207d0cb16 100644 --- a/xml/System.Net.NetworkInformation/MulticastIPAddressInformation.xml +++ b/xml/System.Net.NetworkInformation/MulticastIPAddressInformation.xml @@ -46,11 +46,11 @@ Provides information about a network interface's multicast address. - property. - + property. + ]]> @@ -97,11 +97,11 @@ Initializes a new instance of the class. - class. - + class. + ]]> @@ -152,11 +152,11 @@ Gets the number of seconds remaining during which this address is the preferred address. An value that specifies the number of seconds left for this address to remain preferred. - to determine the preferred address. - + to determine the preferred address. + ]]> This property is not valid on computers running operating systems earlier than Windows XP. @@ -208,11 +208,11 @@ Gets the number of seconds remaining during which this address is valid. An value that specifies the number of seconds left for this address to remain assigned. - to determine the preferred address. - + to determine the preferred address. + ]]> This property is not valid on computers running operating systems earlier than Windows XP. @@ -264,13 +264,13 @@ Specifies the amount of time remaining on the Dynamic Host Configuration Protocol (DHCP) lease for this IP address. An value that contains the number of seconds remaining before the computer must release the instance. - property. Note that the computer can send requests to the DHCP server to extend its lease, so the lease lifetime can increase over time. - + property. Note that the computer can send requests to the DHCP server to extend its lease, so the lease lifetime can increase over time. + ]]> @@ -321,11 +321,11 @@ Gets a value that indicates the state of the duplicate address detection algorithm. One of the values that indicates the progress of the algorithm in determining the uniqueness of this IP address. - This property is not valid on computers running operating systems earlier than Windows XP. @@ -377,11 +377,11 @@ Gets a value that identifies the source of a Multicast Internet Protocol (IP) address prefix. One of the values that identifies how the prefix information was obtained. - This property is not valid on computers running operating systems earlier than Windows XP. @@ -433,11 +433,11 @@ Gets a value that identifies the source of a Multicast Internet Protocol (IP) address suffix. One of the values that identifies how the suffix information was obtained. - This property is not valid on computers running operating systems earlier than Windows XP. diff --git a/xml/System.Net.NetworkInformation/MulticastIPAddressInformationCollection.xml b/xml/System.Net.NetworkInformation/MulticastIPAddressInformationCollection.xml index 2e4ed26f56e..5db994d266e 100644 --- a/xml/System.Net.NetworkInformation/MulticastIPAddressInformationCollection.xml +++ b/xml/System.Net.NetworkInformation/MulticastIPAddressInformationCollection.xml @@ -408,7 +408,7 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . @@ -612,7 +612,7 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . diff --git a/xml/System.Net.NetworkInformation/NetBiosNodeType.xml b/xml/System.Net.NetworkInformation/NetBiosNodeType.xml index 89327edb2d0..67e65f8f67d 100644 --- a/xml/System.Net.NetworkInformation/NetBiosNodeType.xml +++ b/xml/System.Net.NetworkInformation/NetBiosNodeType.xml @@ -45,20 +45,20 @@ Specifies the Network Basic Input/Output System (NetBIOS) node type. - property. - + property. + ]]> diff --git a/xml/System.Net.NetworkInformation/NetworkInformationException.xml b/xml/System.Net.NetworkInformation/NetworkInformationException.xml index a6282a6eafe..dc0afa00ab8 100644 --- a/xml/System.Net.NetworkInformation/NetworkInformationException.xml +++ b/xml/System.Net.NetworkInformation/NetworkInformationException.xml @@ -59,11 +59,11 @@ The exception that is thrown when an error occurs while retrieving network information. - namespace throw this exception when a call to a `Win32` function fails. The property contains the result returned by the function. - + namespace throw this exception when a call to a `Win32` function fails. The property contains the result returned by the function. + ]]> @@ -114,11 +114,11 @@ Initializes a new instance of the class. - property to the most recent `Win32` error. - + property to the most recent `Win32` error. + ]]> @@ -169,11 +169,11 @@ A error code. Initializes a new instance of the class with the specified error code. - property to `errorCode`. - + property to `errorCode`. + ]]> @@ -233,11 +233,11 @@ A StreamingContext that contains contextual information about the serialized exception. Initializes a new instance of the class with serialized data. - instance from serialized data. - + instance from serialized data. + ]]> @@ -285,11 +285,11 @@ Gets the error code for this exception. An value that contains the error code. - diff --git a/xml/System.Net.NetworkInformation/NetworkInterface.xml b/xml/System.Net.NetworkInformation/NetworkInterface.xml index fdcdbd23715..fb5f38283d6 100644 --- a/xml/System.Net.NetworkInformation/NetworkInterface.xml +++ b/xml/System.Net.NetworkInformation/NetworkInterface.xml @@ -810,9 +810,9 @@ property to get the correct value. + The index of the loopback interface is usually 1, but you cannot rely on this. Use the property to get the correct value. - A network interface may have different interface indexes for the IPv4 and IPv6 loopback interface. The property only returns the IPv4 loopback interface. + A network interface may have different interface indexes for the IPv4 and IPv6 loopback interface. The property only returns the IPv4 loopback interface. ]]> diff --git a/xml/System.Net.NetworkInformation/NetworkInterfaceType.xml b/xml/System.Net.NetworkInformation/NetworkInterfaceType.xml index 51ee131e119..9ad0dc77d66 100644 --- a/xml/System.Net.NetworkInformation/NetworkInterfaceType.xml +++ b/xml/System.Net.NetworkInformation/NetworkInterfaceType.xml @@ -45,13 +45,13 @@ Specifies types of network interfaces. - property. - + property. + ]]> diff --git a/xml/System.Net.NetworkInformation/OperationalStatus.xml b/xml/System.Net.NetworkInformation/OperationalStatus.xml index c2f49de4e68..7657a54aa39 100644 --- a/xml/System.Net.NetworkInformation/OperationalStatus.xml +++ b/xml/System.Net.NetworkInformation/OperationalStatus.xml @@ -48,13 +48,13 @@ property. + This enumeration defines valid values for the property. ## Examples The following code example displays a summary for all interfaces on the local computer. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IcmpV4Statistics/Overview/netinfo.cs" id="Snippet16"::: ]]> diff --git a/xml/System.Net.NetworkInformation/Ping.xml b/xml/System.Net.NetworkInformation/Ping.xml index 93156723c0a..5f68576ef95 100644 --- a/xml/System.Net.NetworkInformation/Ping.xml +++ b/xml/System.Net.NetworkInformation/Ping.xml @@ -87,7 +87,7 @@ ||Contains the data associated with events, which are raised when a call completes or is canceled.| ||The delegate that provides the callback method invoked when a call completes or is canceled.| - The and methods return the reply in a object. The property returns an value to indicate the outcome of the request. + The and methods return the reply in a object. The property returns an value to indicate the outcome of the request. When sending the request, you must specify the remote computer. You can do this by providing a host name string, an IP address in string format, or an object. @@ -95,7 +95,7 @@ - Data to accompany the request. Specifying `buffer` allows you to learn the amount of time required for a packet of a particular size to travel to and from the remote host and the maximum transmission unit of the network path. (See the or overloads that take a `buffer` parameter.) -- Whether the ICMP Echo packet can be fragmented in transit. (See the property and the or overloads that take an `options` parameter.) +- Whether the ICMP Echo packet can be fragmented in transit. (See the property and the or overloads that take an `options` parameter.) - How many times routing nodes, such as routers or gateways, can forward the packet before it either reaches the destination computer or is discarded. (See and the or overloads that take an `options` parameter.) @@ -444,9 +444,9 @@ data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time, the method returns and the property is set to . + This method sends to the host that is specified by `address` a 32 data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time, the method returns and the property is set to . - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -510,9 +510,9 @@ data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time, the method returns and the property is set to . + This method sends a 32 data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time, the method returns and the property is set to . - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -578,14 +578,14 @@ property is set to . + If the ICMP echo reply message is not received within the time specified in the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -651,12 +651,12 @@ property is set to . + If the ICMP echo reply message is not received within the time specified in the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -730,14 +730,14 @@ property is set to . + If the ICMP echo reply message is not received within the time specified in the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -815,14 +815,14 @@ property is set to . + If the ICMP echo reply message is not received within the time specified in the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -906,14 +906,14 @@ property is set to . + If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1056,14 +1056,14 @@ property is set to . + If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1227,16 +1227,16 @@ method sends the echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call to this method executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call to this method executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. > [!NOTE] > If your application should block while waiting for a reply, use one of the methods; these methods are synchronous. - This method sends a 32 data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time, the method returns and the property is set to . + This method sends a 32 data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time, the method returns and the property is set to . - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1309,16 +1309,16 @@ method sends the echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call to this method executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call to this method executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. > [!NOTE] > If your application should block while waiting for a reply, use the methods; these methods are synchronous. - This method sends a 32 data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time the method returns and the property is set to . + This method sends a 32 data buffer with the ICMP echo message. The method waits five seconds for an ICMP echo reply message. If it does not receive a reply in that time the method returns and the property is set to . - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + The packet or packet fragments can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1393,16 +1393,16 @@ method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. If your application should block while waiting for a reply, use the methods; these methods are synchronous. - If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . + If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1479,16 +1479,16 @@ method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. If your application should block while waiting for a reply, use the methods; these methods are synchronous. - If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . + If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1573,17 +1573,17 @@ method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + This method sends the echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. To specify the method that is called when raises the event, you must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. > [!NOTE] > If your application blocks while waiting for a reply, use the methods; these methods are synchronous. - If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . + If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1670,16 +1670,16 @@ method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object containing a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application should not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object containing a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. If your application should block while waiting for a reply, use the methods; these methods are synchronous. - If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . + If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + This overload uses default settings for packet fragmentation and packet forwarding. The packet that contains the ICMP echo message can be fragmented in transit if the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers. To prevent fragmentation, use one of the methods that takes an `options` parameter, and set the property to `true`. When is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . The packet or packet fragments (if fragmented) can be forwarded by routing nodes 128 times before being discarded. To change this setting, use a overload that takes an `options` parameter, and set the property to the desired value. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1773,18 +1773,18 @@ method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application must not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application must not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. If your application blocks while waiting for a reply, use the methods; these methods are synchronous. - If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . + If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . @@ -1882,18 +1882,18 @@ method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application must not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. + The method sends the Echo message asynchronously and, when the operation completes (successfully or unsuccessfully), returns the status to your application. Call the method when your application must not block. Each call executes in a separate thread that is automatically allocated from the thread pool. When the asynchronous operation completes, it raises the event. Applications use a delegate to specify the method that is called when raises the event. You must add a delegate to the event before calling . The delegate's method receives a object that contains a object that describes the result of the call. The object inherits the property. This property contains the `userToken` object passed into the call. If your application should block while waiting for a reply, use the methods; these methods are synchronous. - If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . + If the ICMP echo reply message is not received within the time specified by the `timeout` parameter, the ICMP echo fails, and the property is set to . > [!NOTE] > When specifying very small numbers for `timeout`, the Ping reply can be received even if `timeout` milliseconds have elapsed. - If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . + If the property is `true` and the total packet size exceeds the maximum packet size that can be transmitted by one of the routing nodes between the local and remote computers, the ICMP echo request fails. When this happens, the is set to . - Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . + Use the property to specify the maximum number of times the ICMP echo message can be forwarded before reaching its destination. If the packet does not reach its destination after being forwarded the specified number of times, the packet is discarded and the ICMP echo request fails. When this happens, the is set to . diff --git a/xml/System.Net.NetworkInformation/PingCompletedEventArgs.xml b/xml/System.Net.NetworkInformation/PingCompletedEventArgs.xml index 847d0e24d50..15384d868fc 100644 --- a/xml/System.Net.NetworkInformation/PingCompletedEventArgs.xml +++ b/xml/System.Net.NetworkInformation/PingCompletedEventArgs.xml @@ -54,13 +54,13 @@ method that is called when a call completes. The methods send an Internet Control Message Protocol (ICMP) echo request asynchronously and wait for a corresponding ICMP echo reply message. The property contains the results of the ICMP echo request. + Instances of this class are passed to a method that is called when a call completes. The methods send an Internet Control Message Protocol (ICMP) echo request asynchronously and wait for a corresponding ICMP echo reply message. The property contains the results of the ICMP echo request. ## Examples The following code example demonstrates sending an ICMP echo request asynchronously. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/Ping/Overview/asyncping.cs" id="Snippet1"::: ]]> @@ -116,7 +116,7 @@ is not , you should not use the values that are returned by the , , and properties. The and properties will return zero, and the property will return `null`. + If the value of is not , you should not use the values that are returned by the , , and properties. The and properties will return zero, and the property will return `null`. diff --git a/xml/System.Net.NetworkInformation/PingCompletedEventHandler.xml b/xml/System.Net.NetworkInformation/PingCompletedEventHandler.xml index 46c6eaf3c4b..c8a1663cdae 100644 --- a/xml/System.Net.NetworkInformation/PingCompletedEventHandler.xml +++ b/xml/System.Net.NetworkInformation/PingCompletedEventHandler.xml @@ -56,13 +56,13 @@ call is available to the method invoked by this delegate in the property. + User data that is specified in a call is available to the method invoked by this delegate in the property. ## Examples The following code example demonstrates specifying a to respond to a event. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/Ping/Overview/asyncping.cs" id="Snippet1"::: ]]> diff --git a/xml/System.Net.NetworkInformation/PingException.xml b/xml/System.Net.NetworkInformation/PingException.xml index e95379fb302..37a23a5bf16 100644 --- a/xml/System.Net.NetworkInformation/PingException.xml +++ b/xml/System.Net.NetworkInformation/PingException.xml @@ -57,13 +57,13 @@ The exception that is thrown when a or method calls a method that throws an exception. - class throws this exception to indicate that while sending an Internet Control Message Protocol (ICMP) Echo request, a method called by the class threw an unhandled exception. Applications should check the inner exception of a object to identify the problem. - - The class does not throw this exception if the ICMP Echo request fails because of network, ICMP, or destination errors. For such errors, the class returns a object with the relevant value set in the property. - + class throws this exception to indicate that while sending an Internet Control Message Protocol (ICMP) Echo request, a method called by the class threw an unhandled exception. Applications should check the inner exception of a object to identify the problem. + + The class does not throw this exception if the ICMP Echo request fails because of network, ICMP, or destination errors. For such errors, the class returns a object with the relevant value set in the property. + ]]> @@ -125,11 +125,11 @@ A that describes the error. Initializes a new instance of the class using the specified message. - property with the text in the `message` parameter. The property is set to `null`. - + property with the text in the `message` parameter. The property is set to `null`. + ]]> @@ -189,11 +189,11 @@ A that specifies the contextual information about the source or destination for this serialization. Initializes a new instance of the class with serialized data. - object. - + object. + ]]> @@ -247,11 +247,11 @@ The exception that causes the current exception. Initializes a new instance of the class using the specified message and inner exception. - property with the text in the `message` parameter, and the property with the `innerException` parameter. - + property with the text in the `message` parameter, and the property with the `innerException` parameter. + ]]> diff --git a/xml/System.Net.NetworkInformation/PingOptions.xml b/xml/System.Net.NetworkInformation/PingOptions.xml index ed6051006ec..6983d99d737 100644 --- a/xml/System.Net.NetworkInformation/PingOptions.xml +++ b/xml/System.Net.NetworkInformation/PingOptions.xml @@ -51,11 +51,11 @@ ## Remarks The class provides the and properties to control how Internet Control Message Protocol (ICMP) echo request packets are transmitted. - The property specifies the Time to Live for packets sent by the class. This value indicates the number of routing nodes that can forward a packet before it is discarded. Setting this option is useful if you want to test the number of forwards, also known as hops, are required to send a packet from a source computer to a destination computer. + The property specifies the Time to Live for packets sent by the class. This value indicates the number of routing nodes that can forward a packet before it is discarded. Setting this option is useful if you want to test the number of forwards, also known as hops, are required to send a packet from a source computer to a destination computer. - The property controls whether data sent to a remote host can be divided into multiple packets. This option is useful if you want to test the maximum transmission unit (MTU) of the routers and gateways used to transmit the packet. + The property controls whether data sent to a remote host can be divided into multiple packets. This option is useful if you want to test the maximum transmission unit (MTU) of the routers and gateways used to transmit the packet. - Instances of the class are passed to the and methods, and the class returns instances of via the property. + Instances of the class are passed to the and methods, and the class returns instances of via the property. For a list of initial property values for an instance of , see the constructor. @@ -63,7 +63,7 @@ ## Examples The following code example uses the , and classes to send an ICMP echo request to the host specified on the command line. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IPStatus/Overview/syncping.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Net.NetworkInformation/IPStatus/Overview/syncping.fs" id="Snippet1"::: diff --git a/xml/System.Net.NetworkInformation/PingReply.xml b/xml/System.Net.NetworkInformation/PingReply.xml index a29cfbea044..6622cc934c4 100644 --- a/xml/System.Net.NetworkInformation/PingReply.xml +++ b/xml/System.Net.NetworkInformation/PingReply.xml @@ -57,15 +57,15 @@ ## Remarks The class attempts to send an Internet Control Message Protocol (ICMP) echo request to a remote computer and receive information back from the computer via an ICMP echo reply message. The class uses instances of the class to return information about the operation, such as its status and the time taken to send the request and receive the reply. - The methods return instances of the class directly. The methods return a in the method's parameter. The is accessed through the property. + The methods return instances of the class directly. The methods return a in the method's parameter. The is accessed through the property. - If the value of is not , you should not use the values returned by the , or properties. The property will return zero, the property will return an empty array, and the property will return `null`. + If the value of is not , you should not use the values returned by the , or properties. The property will return zero, the property will return an empty array, and the property will return `null`. ## Examples The following code example demonstrates using class to send an ICMP echo request synchronously and display the response. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IPStatus/Overview/syncping.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Net.NetworkInformation/IPStatus/Overview/syncping.fs" id="Snippet1"::: @@ -375,7 +375,7 @@ is not , you should not use the values returned by the , or properties. The and properties will return zero, and the property will return `null`. + If the value of is not , you should not use the values returned by the , or properties. The and properties will return zero, and the property will return `null`. diff --git a/xml/System.Net.NetworkInformation/TcpState.xml b/xml/System.Net.NetworkInformation/TcpState.xml index 0358717cbc0..a1001873513 100644 --- a/xml/System.Net.NetworkInformation/TcpState.xml +++ b/xml/System.Net.NetworkInformation/TcpState.xml @@ -48,13 +48,13 @@ property. TCP is a transport layer protocol responsible for reliably sending and receiving data packets. The TCP states in this enumeration are defined in IETF RFC 793 available at [https://www.ietf.org](https://www.ietf.org/). + This enumeration defines valid values for the property. TCP is a transport layer protocol responsible for reliably sending and receiving data packets. The TCP states in this enumeration are defined in IETF RFC 793 available at [https://www.ietf.org](https://www.ietf.org/). ## Examples The following code example counts the established TCP connections. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.NetworkInformation/DuplicateAddressDetectionState/Overview/networkexamples.vb" id="Snippet2"::: diff --git a/xml/System.Net.NetworkInformation/UdpStatistics.xml b/xml/System.Net.NetworkInformation/UdpStatistics.xml index 8953f293559..ef7ffd33450 100644 --- a/xml/System.Net.NetworkInformation/UdpStatistics.xml +++ b/xml/System.Net.NetworkInformation/UdpStatistics.xml @@ -57,7 +57,7 @@ ## Examples The following code example displays the UDP statistics for the specified address family. - + :::code language="csharp" source="~/snippets/csharp/System.Net.NetworkInformation/IcmpV4Statistics/Overview/netinfo.cs" id="Snippet3"::: ]]> @@ -265,7 +265,7 @@ property. + To find the total number of datagrams that could not be delivered, add the values that were returned by this property and the property. @@ -321,7 +321,7 @@ property. + To find the total number of datagrams that could not be delivered, add the values that were returned by this property and the property. diff --git a/xml/System.Net.NetworkInformation/UnicastIPAddressInformation.xml b/xml/System.Net.NetworkInformation/UnicastIPAddressInformation.xml index b12ed956225..b5236a5aac4 100644 --- a/xml/System.Net.NetworkInformation/UnicastIPAddressInformation.xml +++ b/xml/System.Net.NetworkInformation/UnicastIPAddressInformation.xml @@ -52,11 +52,11 @@ Provides information about a network interface's unicast address. - property. - + property. + ]]> @@ -103,11 +103,11 @@ Initializes a new instance of the class. - class. - + class. + ]]> @@ -158,11 +158,11 @@ Gets the number of seconds remaining during which this address is the preferred address. An value that specifies the number of seconds left for this address to remain preferred. - to determine the preferred address. - + to determine the preferred address. + ]]> This property is not valid on computers running operating systems earlier than Windows XP. @@ -214,11 +214,11 @@ Gets the number of seconds remaining during which this address is valid. An value that specifies the number of seconds left for this address to remain assigned. - to determine the preferred address. - + to determine the preferred address. + ]]> This property is not valid on computers running operating systems earlier than Windows XP. @@ -270,13 +270,13 @@ Specifies the amount of time remaining on the Dynamic Host Configuration Protocol (DHCP) lease for this IP address. An value that contains the number of seconds remaining before the computer must release the instance. - property. Note that the computer can send requests to the DHCP server to extend its lease, so the lease lifetime can increase over time. - + property. Note that the computer can send requests to the DHCP server to extend its lease, so the lease lifetime can increase over time. + ]]> @@ -327,11 +327,11 @@ Gets a value that indicates the state of the duplicate address detection algorithm. One of the values that indicates the progress of the algorithm in determining the uniqueness of this IP address. - This property is not valid on computers running operating systems earlier than Windows XP. @@ -466,11 +466,11 @@ Gets a value that identifies the source of a unicast Internet Protocol (IP) address prefix. One of the values that identifies how the prefix information was obtained. - This property is not valid on computers running operating systems earlier than Windows XP. @@ -522,11 +522,11 @@ Gets a value that identifies the source of a unicast Internet Protocol (IP) address suffix. One of the values that identifies how the suffix information was obtained. - This property is not valid on computers running operating systems earlier than Windows XP. diff --git a/xml/System.Net.NetworkInformation/UnicastIPAddressInformationCollection.xml b/xml/System.Net.NetworkInformation/UnicastIPAddressInformationCollection.xml index 1a2f5439969..4d914abbf7e 100644 --- a/xml/System.Net.NetworkInformation/UnicastIPAddressInformationCollection.xml +++ b/xml/System.Net.NetworkInformation/UnicastIPAddressInformationCollection.xml @@ -408,7 +408,7 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . @@ -612,7 +612,7 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerContact.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerContact.xml index 914f0d1738c..5ddf9c2a992 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerContact.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerContact.xml @@ -1622,7 +1622,7 @@ ## Examples - The following code example illustrates the proper usage of the property: + The following code example illustrates the proper usage of the property: :::code language="csharp" source="~/snippets/csharp/System.Net.PeerToPeer.Collaboration/ContactManager/Overview/NCLPNRPContacts.cs" id="Snippet7"::: @@ -1967,7 +1967,7 @@ specified the result is a no-op. A calling peer can verify whether it is subscribed to events for the peer identified by this instance with the property. + If the calling peer is not subscribed to the specified the result is a no-op. A calling peer can verify whether it is subscribed to events for the peer identified by this instance with the property. Calling this method requires a of . This state is created when the peer collaboration session begins. diff --git a/xml/System.Net.PeerToPeer.Collaboration/PeerNearMe.xml b/xml/System.Net.PeerToPeer.Collaboration/PeerNearMe.xml index c3679d1e817..fe09936c2bb 100644 --- a/xml/System.Net.PeerToPeer.Collaboration/PeerNearMe.xml +++ b/xml/System.Net.PeerToPeer.Collaboration/PeerNearMe.xml @@ -420,7 +420,7 @@ and methods as well as the property. The method only needs to be used if the caller is not subscribed to the specified , , or . + The data retrieved is stored in a cache accessed by the and methods as well as the property. The method only needs to be used if the caller is not subscribed to the specified , , or . This method blocks additional calls until the network operation is complete and the cache has been updated. @@ -729,7 +729,7 @@ and methods as well as the property. This method only needs to be used if the caller is not subscribed to the specified , , or . + The data retrieved is stored in a cache accessed by the and methods as well as the property. This method only needs to be used if the caller is not subscribed to the specified , , or . This method blocks additional calls until the network operation is complete and cache has been updated. @@ -772,7 +772,7 @@ and methods as well as the property. The method only needs to be used if the caller is not subscribed to the specified , , or . + The data retrieved is stored in a cache accessed by the and methods as well as the property. The method only needs to be used if the caller is not subscribed to the specified , , or . This method blocks additional calls until the network operation is complete and cache has been updated. diff --git a/xml/System.Net.PeerToPeer/Cloud.xml b/xml/System.Net.PeerToPeer/Cloud.xml index 692e1c3d720..59839b46c62 100644 --- a/xml/System.Net.PeerToPeer/Cloud.xml +++ b/xml/System.Net.PeerToPeer/Cloud.xml @@ -70,7 +70,7 @@ property contains the name of the cloud object. + The property contains the name of the cloud object. ]]> diff --git a/xml/System.Net.PeerToPeer/PeerName.xml b/xml/System.Net.PeerToPeer/PeerName.xml index 86301a179de..1d76c9a2321 100644 --- a/xml/System.Net.PeerToPeer/PeerName.xml +++ b/xml/System.Net.PeerToPeer/PeerName.xml @@ -259,7 +259,7 @@ ## Remarks The peer-to-peer host is the "seed node" responsible for initiating the peer-to-peer networking session, inviting peers to participate in applications for which this type of network connectivity is most appropriate for communications such as chat groups or game sessions. - This method can be used to create a object based on the property. This peer name is not associated with the identity of the calling node. + This method can be used to create a object based on the property. This peer name is not associated with the identity of the calling node. ]]> @@ -550,7 +550,7 @@ ## Remarks The peer-to-peer host is the "seed node" responsible for initiating the peer-to-peer networking session, inviting peers to participate in applications for which this type of network connectivity is most appropriate for communications such as chat groups or game sessions. - The property specifies the name of a peer that created the peer-to-peer networking session, and which is considered the host of the session. The host of a peer-to-peer networking session may collect peers into more than one . Also, a peer may simultaneously be hosted by more than one peer host. + The property specifies the name of a peer that created the peer-to-peer networking session, and which is considered the host of the session. The host of a peer-to-peer networking session may collect peers into more than one . Also, a peer may simultaneously be hosted by more than one peer host. ]]> diff --git a/xml/System.Net.PeerToPeer/PeerNameRegistration.xml b/xml/System.Net.PeerToPeer/PeerNameRegistration.xml index a937a4de538..f57bf494f4b 100644 --- a/xml/System.Net.PeerToPeer/PeerNameRegistration.xml +++ b/xml/System.Net.PeerToPeer/PeerNameRegistration.xml @@ -375,9 +375,9 @@ ## Remarks In the namespace, an represents a network endpoint as an IP address and a port number. For PNRP, an IP address and port value must be provided for each endpoint. The maximum number of endpoints that can be provided is ten. Automatic address selection is used when this parameter is `null`. - If a registration method is used that automatically selects the addresses to register, there is no method to determine the addresses for which the peer name was registered. That is, the property will not be updated to reflect the addresses selected. + If a registration method is used that automatically selects the addresses to register, there is no method to determine the addresses for which the peer name was registered. That is, the property will not be updated to reflect the addresses selected. - When a peer name is registered for more than one node, each is distinct and the property defined on each registration instance will be different. Also, when a is registered into more than one , each registration is distinct and the collection of endpoints will usually be different for each instance. + When a peer name is registered for more than one node, each is distinct and the property defined on each registration instance will be different. Also, when a is registered into more than one , each registration is distinct and the collection of endpoints will usually be different for each instance. ]]> @@ -463,7 +463,7 @@ instance is distinct. The property associated with each corresponding instance is different. Also, it is possible to register a peer name for more than one cloud that the node is connected to; each of these registrations is distinct. The peer name's will be different in each of these instances. + A peer name can be registered for more than one node; each instance is distinct. The property associated with each corresponding instance is different. Also, it is possible to register a peer name for more than one cloud that the node is connected to; each of these registrations is distinct. The peer name's will be different in each of these instances. ]]> @@ -532,9 +532,9 @@ property with all source addresses and the specified in the constructor. The default port is used by this method only when no endpoints are specified. + The method registers the peer name specified in the property with all source addresses and the specified in the constructor. The default port is used by this method only when no endpoints are specified. - If the property is `null`, this method registers the peer name specified in the property using the field, which initializes default values for the , , and . + If the property is `null`, this method registers the peer name specified in the property using the field, which initializes default values for the , , and . After a object has been started, the method is used to stop it. @@ -673,7 +673,7 @@ ## Remarks All information registered in cloud(s) for this prior to the call is completely discarded. The new data is not combined with the existing registration. To update a , first update the properties on this instance and then call this method. - After a is registered, the property cannot be updated. All other fields in the record may be updated. + After a is registered, the property cannot be updated. All other fields in the record may be updated. ]]> @@ -717,9 +717,9 @@ ## Remarks When auto endpoint selection is used (this property is set to `true`) with no endpoint information specified prior to the start of a , the system chooses individual endpoints and publishes them with the associated peer name into all available clouds. If the port is not specified, auto selection chooses zero as the . - When set to `false`, auto selection as described above is not performed. This enables the registration process to publish a peer name along with a data blob (as specified by the property). No endpoints are associated with the name. + When set to `false`, auto selection as described above is not performed. This enables the registration process to publish a peer name along with a data blob (as specified by the property). No endpoints are associated with the name. - If a registration method is used that automatically selects the addresses to register, there is no method to determine what addresses for which the object was registered. That is, the property will not be updated to reflect the addresses selected. + If a registration method is used that automatically selects the addresses to register, there is no method to determine what addresses for which the object was registered. That is, the property will not be updated to reflect the addresses selected. Updating this property after peer name registration has started has no effect. diff --git a/xml/System.Net.PeerToPeer/ResolveProgressChangedEventArgs.xml b/xml/System.Net.PeerToPeer/ResolveProgressChangedEventArgs.xml index 185d34bc556..fd86f814947 100644 --- a/xml/System.Net.PeerToPeer/ResolveProgressChangedEventArgs.xml +++ b/xml/System.Net.PeerToPeer/ResolveProgressChangedEventArgs.xml @@ -17,15 +17,15 @@ Used in conjunction with signaling the event. It is signaled whenever a object is found in response to a operation on a specific . - event is raised only once when all endpoints have been found. - - Normal process completion implies that either the Resolver object has reached the end of the cloud(s) to query for peer names, or it has reached the maximum number of record entries for the peer name record collection it is constructing. - - All references to this instance of the Resolver are coordinated with the token userState , which is a unique identifier for this asynchronous resolve request. - + event is raised only once when all endpoints have been found. + + Normal process completion implies that either the Resolver object has reached the end of the cloud(s) to query for peer names, or it has reached the maximum number of record entries for the peer name record collection it is constructing. + + All references to this instance of the Resolver are coordinated with the token userState , which is a unique identifier for this asynchronous resolve request. + ]]> @@ -52,13 +52,13 @@ The unique user state object supplied when a operation was started. Initializes a new instance of the class. - property. - - The user state is inherited from . - + property. + + The user state is inherited from . + ]]> @@ -81,15 +81,15 @@ Gets the object to resolve. - The peer name record object found in response to a operation on a specific . - + The peer name record object found in response to a operation on a specific . + Unless explicitly specified, the default value for all properties is for reference types and zero (0) for properties of type . - , and associated with different endpoints. Consequently, the class is used to resolve peer names to clouds or peer names to peer name records. The event to report progress is raised each time a peer name is found while the Resolver is querying clouds for the . - + , and associated with different endpoints. Consequently, the class is used to resolve peer names to clouds or peer names to peer name records. The event to report progress is raised each time a peer name is found while the Resolver is querying clouds for the . + ]]> diff --git a/xml/System.Net.Security/AuthenticationLevel.xml b/xml/System.Net.Security/AuthenticationLevel.xml index 6cb3d2b79d9..e159e0f45d8 100644 --- a/xml/System.Net.Security/AuthenticationLevel.xml +++ b/xml/System.Net.Security/AuthenticationLevel.xml @@ -48,7 +48,7 @@ property. + The values of this enumeration are used to set the property. > [!NOTE] > The MutualAuthRequired and MutualAuthRequested values are relevant for Kerberos authentication. Kerberos authentication can be supported directly, or can be used if the Negotiate security protocol is used to select the actual security protocol. For more information about authentication protocols, see [Internet Authentication](/dotnet/framework/network-programming/internet-authentication). @@ -57,7 +57,7 @@ ## Examples The following code example demonstrates setting the authentication flags for a request. - + :::code language="csharp" source="~/snippets/csharp/Microsoft.Win32/IntranetZoneCredentialPolicy/Overview/websample.cs" id="Snippet1"::: ]]> diff --git a/xml/System.Net.Security/NegotiateStream.xml b/xml/System.Net.Security/NegotiateStream.xml index b035ef36986..459a7b397ae 100644 --- a/xml/System.Net.Security/NegotiateStream.xml +++ b/xml/System.Net.Security/NegotiateStream.xml @@ -67,7 +67,7 @@ Authentication must be performed before transmitting information. Clients request authentication using the synchronous methods, which block until the authentication completes, or the asynchronous methods, which do not block while waiting for the authentication to complete. Servers request authentication using the synchronous or asynchronous methods. The client, and optionally the server, is authenticated using the Negotiate security protocol. The Kerberos protocol is used for authentication if both client and server support it; otherwise NTLM is used. The class performs the authentication using the Security Support Provider Interface (SSPI). - When authentication succeeds, you must check the and properties to determine what security services will be used by the to help secure your data during transmission. Check the property to determine whether mutual authentication occurred. You can get information about the remote client or server using the property. + When authentication succeeds, you must check the and properties to determine what security services will be used by the to help secure your data during transmission. Check the property to determine whether mutual authentication occurred. You can get information about the remote client or server using the property. If the authentication fails, you will receive an or a . In this case, you can retry the authentication with a different credential. @@ -285,7 +285,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks The authentication uses the client's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -356,7 +356,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. ]]> @@ -437,9 +437,9 @@ The following example demonstrates calling this constructor. This code example i ## Remarks The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . + The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. ]]> @@ -601,7 +601,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks Use the `requiredProtectionLevel` parameter to request security services for data transmitted using the authenticated stream. For example, to have the data encrypted and signed, specify the value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . - The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . + The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -682,7 +682,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks The authentication uses the client's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -750,7 +750,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. 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 . @@ -828,9 +828,9 @@ The following example demonstrates calling this constructor. This code example i ## Remarks The impersonation level is , the security level is , and mutual authentication is requested. The class will construct the SPN used for mutual authentication. - The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . + The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. 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 . @@ -992,7 +992,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks Use the `requiredProtectionLevel` parameter to request security services for data transmitted using the authenticated stream. For example, to have the data encrypted and signed, specify the value. Successful authentication does not guarantee that the requested has been granted. You must check the and properties to determine what security services are used by the . - The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . + The used for extended protection that is passed to this method in the `binding` parameter would be retrieved by an application from property on the associated . If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1082,7 +1082,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks The authentication uses the server's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. @@ -1146,7 +1146,7 @@ The following example demonstrates calling this constructor. This code example i If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. @@ -1219,7 +1219,7 @@ The following example demonstrates calling this constructor. This code example i and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. @@ -1303,7 +1303,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. This method blocks until the operation completes. To prevent blocking until the operation completes, use one of the method overloads. @@ -1385,7 +1385,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks The authentication uses the server's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , and the security level is . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1457,7 +1457,7 @@ The following example demonstrates calling this constructor. This code example i If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1525,7 +1525,7 @@ The following example demonstrates calling this constructor. This code example i and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -1610,7 +1610,7 @@ The following example demonstrates calling this constructor. This code example i ## Remarks If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -2228,7 +2228,7 @@ The following example demonstrates calling this method to begin an asynchronous ## Remarks The authentication uses the server's . No Service Principal Name (SPN) is specified for the server. The impersonation level is , the security level is . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. To block until the operation completes, use one of the method overloads. @@ -2303,7 +2303,7 @@ The following example demonstrates calling this method to begin an asynchronous If the `policy` parameter is `null`, then an extended protection policy is used that has set to . - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. To block until the operation completes, use one of the method overloads. @@ -2790,7 +2790,7 @@ The following method is called when the operation completes. property on the underlying stream. The underlying stream is specified when you create an instance of the class. + If successful authentication has occurred, this property returns the value returned by invoking the property on the underlying stream. The underlying stream is specified when you create an instance of the class. ## Examples @@ -2902,7 +2902,7 @@ The following code example demonstrates displaying the value of this property. property on the underlying stream. The underlying stream is specified when you create an instance of the class. + This property returns the value returned by invoking the property on the underlying stream. The underlying stream is specified when you create an instance of the class. @@ -2960,7 +2960,7 @@ The following code example demonstrates displaying the value of this property. property on the underlying stream. The underlying stream is specified when you create an instance of the class. + If successful authentication has occurred, this property returns the value returned by invoking the property on the underlying stream. The underlying stream is specified when you create an instance of the class. @@ -3124,7 +3124,7 @@ The following code example demonstrates displaying the value of this property. and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + If the operation has not completed, this method blocks until it does. When the authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -3188,7 +3188,7 @@ The following code example demonstrates displaying the value of this property. ## Remarks If the operation has not completed, this method blocks until it does. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive an or an . In this case, you can retry the authentication with a different credential. @@ -3834,7 +3834,7 @@ The following code example demonstrates displaying the value of this property. property on the underlying stream. If the underlying stream is not seekable, this property will typically throw an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. + This property returns the value returned by invoking the property on the underlying stream. If the underlying stream is not seekable, this property will typically throw an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. @@ -3892,7 +3892,7 @@ The following code example demonstrates displaying the value of this property. property on the underlying stream. If the underlying stream is not seekable, this property will typically throw an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. + This property returns the value returned by invoking the property on the underlying stream. If the underlying stream is not seekable, this property will typically throw an exception. The run-time type of the underlying stream determines the run-time type of the exception that is thrown. ]]> @@ -4118,7 +4118,7 @@ This method reads asynchronously as much data as is available into `buffer` and property on the underlying stream. When you set this property, the value on the underlying stream is set to the specified value. + This property returns the value returned by invoking the property on the underlying stream. When you set this property, the value on the underlying stream is set to the specified value. If the underlying stream is a , is in milliseconds and is set to by default so that read operations do not time out. @@ -4540,7 +4540,7 @@ The following code example demonstrates writing to a property on the underlying stream. For set operations, the specified value sets the value on the underlying stream. + This property returns the value returned by invoking the property on the underlying stream. For set operations, the specified value sets the value on the underlying stream. If the underlying stream is a , is in milliseconds and is set to by default so that write operations do not time out. diff --git a/xml/System.Net.Security/SslClientAuthenticationOptions.xml b/xml/System.Net.Security/SslClientAuthenticationOptions.xml index 06bb64f5656..7c768da9966 100644 --- a/xml/System.Net.Security/SslClientAuthenticationOptions.xml +++ b/xml/System.Net.Security/SslClientAuthenticationOptions.xml @@ -43,13 +43,13 @@ Represents a client authentication property bag for the . - and, in .NET 5 and later versions, for . - - The uses this property bag in the property. - + + The uses this property bag in the property. + ]]> @@ -276,7 +276,7 @@ Gets or sets an optional customized policy for remote certificate validation. To be added. - Gets or sets the certificate revocation mode for certificate validation. One of the values in . The default is . - . - + For more information, see [Working with Certificates](/dotnet/framework/wcf/feature-details/working-with-certificates). - + ]]> @@ -424,12 +424,12 @@ When this property isn't `null`, certain properties on `SslClientAuthenticationO A collection of certificates to be considered for the client's authentication to the server. To be added. - can be used to select a specific certificate to offer to the server. - + can be used to select a specific certificate to offer to the server. + ]]> diff --git a/xml/System.Net.Security/SslStream.xml b/xml/System.Net.Security/SslStream.xml index bdee6c63062..7fd56f0dd3e 100644 --- a/xml/System.Net.Security/SslStream.xml +++ b/xml/System.Net.Security/SslStream.xml @@ -72,10 +72,10 @@ |Element|Members| |-------------|-------------| -|The security protocol used to authenticate the server and, optionally, the client.|The property and the associated enumeration.| -|The key exchange algorithm.|The property and the associated enumeration.| -|The message integrity algorithm.|The property and the associated enumeration.| -|The message confidentiality algorithm.|The property and the associated enumeration.| +|The security protocol used to authenticate the server and, optionally, the client.|The property and the associated enumeration.| +|The key exchange algorithm.|The property and the associated enumeration.| +|The message integrity algorithm.|The property and the associated enumeration.| +|The message confidentiality algorithm.|The property and the associated enumeration.| |The strengths of the selected algorithms.|The , , and properties.| After a successful authentication, you can send data using the synchronous or asynchronous methods. You can receive data using the synchronous or asynchronous methods. @@ -611,7 +611,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] No client certificates are used in the authentication. The certificate revocation list is not checked during authentication. The value specified for `targetHost` must match the name on the server's certificate. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -679,7 +679,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] No client certificates are used in the authentication. The certificate revocation list is not checked during authentication. The value specified for `targetHost` must match the name on the server's certificate. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -756,7 +756,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -828,7 +828,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -897,7 +897,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] No client certificates are used in the authentication. The certificate revocation list is not checked during authentication. The value specified for `targetHost` must match the name on the server's certificate. - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -963,7 +963,7 @@ ## Remarks - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -1044,7 +1044,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -1130,7 +1130,7 @@ ## Remarks [!INCLUDE[sslprotocols-none](~/includes/sslprotocols-none-md.md)] - When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + When authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -2982,7 +2982,7 @@ is required for the property when the enumeration value is used to construct a instance. + A value of is required for the property when the enumeration value is used to construct a instance. Windows Server 2003 and Windows XP do not support the value. So even if the value is used to construct the instance, the property will be . The value is only returned on Windows Vista and later. @@ -3230,7 +3230,7 @@ and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + If the operation has not completed, this method blocks until it does. When the authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. @@ -3291,7 +3291,7 @@ and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. + If the operation has not completed, this method blocks until it does. When the authentication succeeds, you must check the and properties to determine what security services are used by the . Check the property to determine whether mutual authentication occurred. If the authentication fails, you receive a , and this is no longer useable. You should close this object and remove all references to it so that it can be collected by the garbage collector. diff --git a/xml/System.Net.Sockets/IOControlCode.xml b/xml/System.Net.Sockets/IOControlCode.xml index 681352f34fb..cbbca1b23bd 100644 --- a/xml/System.Net.Sockets/IOControlCode.xml +++ b/xml/System.Net.Sockets/IOControlCode.xml @@ -53,8 +53,8 @@ ## Examples - The following code example calls the method with a DataToRead parameter value and compares the result with accessing the. property. - + The following code example calls the method with a DataToRead parameter value and compares the result with accessing the. property. + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/IOControlCode/Overview/iocontrolcode.cs" id="Snippet1"::: ]]> diff --git a/xml/System.Net.Sockets/LingerOption.xml b/xml/System.Net.Sockets/LingerOption.xml index 99e61e976c8..cb0b36abc5b 100644 --- a/xml/System.Net.Sockets/LingerOption.xml +++ b/xml/System.Net.Sockets/LingerOption.xml @@ -50,15 +50,15 @@ or method. If you want to specify the amount of time that the will attempt to transmit unsent data after closing, create a with the `enable` parameter set to `true`, and the `seconds` parameter set to the desired amount of time. The `seconds` parameter is used to indicate how long you would like the to remain connected before timing out. If you do not want the to stay connected for any length of time after closing, create a instance with the `enable` parameter set to `true` and the `seconds` parameter set to zero. In this case, the will close immediately and any unsent data will be lost. Once created, pass the to the method. If you are sending and receiving data with a , then set the instance in the property. + There may still be data available in the outgoing network buffer after an application calls the or method. If you want to specify the amount of time that the will attempt to transmit unsent data after closing, create a with the `enable` parameter set to `true`, and the `seconds` parameter set to the desired amount of time. The `seconds` parameter is used to indicate how long you would like the to remain connected before timing out. If you do not want the to stay connected for any length of time after closing, create a instance with the `enable` parameter set to `true` and the `seconds` parameter set to zero. In this case, the will close immediately and any unsent data will be lost. Once created, pass the to the method. If you are sending and receiving data with a , then set the instance in the property. - The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a when the property is not set and for a when the property is not set. + The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a when the property is not set and for a when the property is not set. ## Examples The following example sets a previously created to linger one second after calling the method. - + :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/LingerOption/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/LingerOption/Overview/source.vb" id="Snippet1"::: @@ -115,7 +115,7 @@ ## Remarks There may still be data available in the outgoing network buffer after you close the . Use the `enable` parameter to specify whether you would like the to continue transmitting unsent data after the close method is called. Use the `seconds` parameter to indicate how long you would like the to attempt transferring unsent data before timing out. If you specify `true` for the `enable` parameter and 0 for the `seconds` parameter, the will attempt to send data until there is no data left in the outgoing network buffer. If you specify `false` for the `enable` parameter, the will close immediately and any unsent data will be lost. - The following table describes the behavior on the and methods based on the possible values of the `enable` and `seconds` parameters when an T:System.Net.Sockets.LingerOption instance is created and set in the or property. + The following table describes the behavior on the and methods based on the possible values of the `enable` and `seconds` parameters when an T:System.Net.Sockets.LingerOption instance is created and set in the or property. |`enable`|`seconds`|Behavior| |--------------|---------------|--------------| @@ -123,9 +123,9 @@ |`true` (enabled)|A nonzero time-out|Attempts to send pending data until the specified time-out expires, and if the attempt fails, then Winsock resets the connection.| |`true` (enabled)|A zero timeout.|Discards any pending data. For connection-oriented socket (TCP, for example), Winsock resets the connection.| - The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a socket when the property is not set. + The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a socket when the property is not set. - When the property stored in the property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override. + When the property stored in the property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override. @@ -194,9 +194,9 @@ property to determine whether the will linger after closing. Change this value to `true` or `false` and pass the altered to the method or set the or property.to disable or enable lingering. + You can use the property to determine whether the will linger after closing. Change this value to `true` or `false` and pass the altered to the method or set the or property.to disable or enable lingering. - The following table describes the behavior for the possible values of the property and the property stored in the property. + The following table describes the behavior for the possible values of the property and the property stored in the property. |`enable`|`seconds`|Behavior| |--------------|---------------|--------------| @@ -204,9 +204,9 @@ |`true` (enabled)|A nonzero time-out|Attempts to send pending data until the specified time-out expires, and if the attempt fails, then Winsock resets the connection.| |`true` (enabled)|A zero timeout.|Discards any pending data. For connection-oriented socket (TCP, for example), Winsock resets the connection.| - The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a socket when the property is not set. + The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a socket when the property is not set. - When the property stored in the property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override. + When the property stored in the property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override. ]]> @@ -328,9 +328,9 @@ ## Remarks Use this value if you want to determine how long a closed will attempt to transfer unsent data before timing out. You can also set this value to the desired time-out period, in seconds. - If the property is `true`, and you set to 0, the discards any pending data to send in the outgoing network buffer. If you change this value, you must pass the altered instance to the method or set the or property. + If the property is `true`, and you set to 0, the discards any pending data to send in the outgoing network buffer. If you change this value, you must pass the altered instance to the method or set the or property. - The following table describes the behavior for the possible values of the property and the property stored in the property. + The following table describes the behavior for the possible values of the property and the property stored in the property. |`enable`|`seconds`|Behavior| |--------------|---------------|--------------| @@ -338,9 +338,9 @@ |`true` (enabled)|A nonzero time-out|Attempts to send pending data until the specified time-out expires, and if the attempt fails, then Winsock resets the connection.| |`true` (enabled)|A zero timeout.|Discards any pending data. For connection-oriented socket (TCP, for example), Winsock resets the connection.| - The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a socket when the property is not set. + The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a socket when the property is not set. - When the property stored in the property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override. + When the property stored in the property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override. diff --git a/xml/System.Net.Sockets/MulticastOption.xml b/xml/System.Net.Sockets/MulticastOption.xml index 5bf0826dcb4..45685d999cb 100644 --- a/xml/System.Net.Sockets/MulticastOption.xml +++ b/xml/System.Net.Sockets/MulticastOption.xml @@ -420,7 +420,7 @@ property contains the IP address of the interface associated with the multicast group membership. If is set to , the default interface is used. + The property contains the IP address of the interface associated with the multicast group membership. If is set to , the default interface is used. ## Examples The following example displays the value of this property. diff --git a/xml/System.Net.Sockets/NetworkStream.xml b/xml/System.Net.Sockets/NetworkStream.xml index 0f8ed5ffa56..186a0b08f34 100644 --- a/xml/System.Net.Sockets/NetworkStream.xml +++ b/xml/System.Net.Sockets/NetworkStream.xml @@ -68,7 +68,7 @@ Use the and methods for simple single threaded synchronous blocking I/O. If you want to process your I/O asynchronously, consider using the or -based methods and . - The does not support random access to the network data stream. The value of the property, which indicates whether the stream supports seeking, is always `false`; reading the property, reading the property, or calling the method will throw a . + The does not support random access to the network data stream. The value of the property, which indicates whether the stream supports seeking, is always `false`; reading the property, reading the property, or calling the method will throw a . Read and write operations can be performed simultaneously on an instance of the class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required. @@ -438,14 +438,14 @@ > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. The operation reads as much data as is available, up to the number of bytes specified by the `count` parameter. > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. Read and write operations can be performed simultaneously on an instance of the class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required. @@ -558,12 +558,12 @@ > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (Begin / End) methods for new development. Instead, use the Task-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. Read and write operations can be performed simultaneously on an instance of the class without the need for synchronization. As long as there is one unique thread for the write operations and one unique thread for the read operations, there will be no cross-interference between read and write threads and no synchronization is required. @@ -650,7 +650,7 @@ If is `true`, allows calls to the method. Provide the appropriate enumerated value in the constructor to set the readability and writability of the . > [!NOTE] -> The property is set when the is initialized. +> The property is set when the is initialized. > Changes in the underlying 's state (eg. closure) do not affect the value of . ]]> @@ -807,7 +807,7 @@ If is `true`, allows calls to the method. Provide the appropriate enumerated value in the constructor to set the readability and writability of the . > [!NOTE] -> The property is set when the is initialized. +> The property is set when the is initialized. > Changes in the underlying 's state (eg. closure) do not affect the value of . ]]> @@ -1013,7 +1013,7 @@ The Close method frees both unmanaged and managed resources associated with the property to determine if data is queued to be immediately read. + Use the property to determine if data is queued to be immediately read. If is `true`, a call to returns immediately. If the remote host shuts down or closes the connection, may throw a . @@ -1148,7 +1148,7 @@ The Close method frees both unmanaged and managed resources associated with the The method completes the read operation started by the method. You need to pass the created by the matching call. will block the calling thread until the operation is completed. > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. ]]> @@ -1214,7 +1214,7 @@ The Close method frees both unmanaged and managed resources associated with the The method completes the read operation started by the method. You need to pass the created by the matching call. will block the calling thread until the operation is completed. > [!NOTE] -> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. +> If you receive an , check the property to determine if it was caused by a . If so, use the property to obtain the specific error code. ]]> @@ -1691,14 +1691,14 @@ There is a failure reading from the network. class to use the property. If is `true`, allows calls to the method. You can also determine whether a is readable by checking the publicly accessible property. + You must derive from the class to use the property. If is `true`, allows calls to the method. You can also determine whether a is readable by checking the publicly accessible property. - The property is set when the is initialized. + The property is set when the is initialized. ## Examples - In the following code example, the `CanCommunicate` property checks the property to determine if the is readable. + In the following code example, the `CanCommunicate` property checks the property to determine if the is readable. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/Readable/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/NetworkStream/Readable/source.vb" id="Snippet1"::: @@ -2105,7 +2105,7 @@ There is a failure reading from the network. can use this property to get the underlying . Use the underlying returned from the property if you require access beyond that which provides. + Classes deriving from can use this property to get the underlying . Use the underlying returned from the property if you require access beyond that which provides. > [!NOTE] > This property is accessible only through this class or a derived class. @@ -2373,14 +2373,14 @@ There was a failure while writing to the network. class to use the property. If is `true`, allows calls to the method. You can also determine whether a is writable by checking the publicly accessible property. + You must derive from the class to use the property. If is `true`, allows calls to the method. You can also determine whether a is writable by checking the publicly accessible property. - The property is set when the is initialized. + The property is set when the is initialized. ## Examples - In the following code example, the `CanCommunicate` property checks the property to determine if the is writable. + In the following code example, the `CanCommunicate` property checks the property to determine if the is writable. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/NetworkStream/Readable/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/NetworkStream/Readable/source.vb" id="Snippet1"::: diff --git a/xml/System.Net.Sockets/SendPacketsElement.xml b/xml/System.Net.Sockets/SendPacketsElement.xml index dc10793d0eb..f7e044b10aa 100644 --- a/xml/System.Net.Sockets/SendPacketsElement.xml +++ b/xml/System.Net.Sockets/SendPacketsElement.xml @@ -52,11 +52,11 @@ Represents an element in a array. - class is used to enhance the class for use by server applications that use asynchronous network I/O to achieve the highest performance. The class is used with the property to get or set a data buffer or file to be sent using the method. - + class is used to enhance the class for use by server applications that use asynchronous network I/O to achieve the highest performance. The class is used with the property to get or set a data buffer or file to be sent using the method. + ]]> Instances of this class are thread safe. @@ -114,11 +114,11 @@ A byte array of data to send using the method. Initializes a new instance of the class using the specified buffer. - class is used with the property to get or set a data buffer or file to be sent using the method. - + class is used with the property to get or set a data buffer or file to be sent using the method. + ]]> The parameter cannot be null. @@ -157,11 +157,11 @@ The file to be transmitted using the method. Initializes a new instance of the class using the specified object. - class is used with the property to get or set a data buffer or file to be sent using the method. - + class is used with the property to get or set a data buffer or file to be sent using the method. + ]]> @@ -197,11 +197,11 @@ A of bytes to send using the method. Initializes a new instance of the class using the specified buffer. - class is used with the property to get or set a data buffer or file to be sent using the method. - + class is used with the property to get or set a data buffer or file to be sent using the method. + ]]> @@ -252,13 +252,13 @@ The filename of the file to be transmitted using the method. Initializes a new instance of the class using the specified file. - class is used with the property to get or set a data buffer or file to be sent using the method. - - Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. - + class is used with the property to get or set a data buffer or file to be sent using the method. + + Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. + ]]> The parameter cannot be null. @@ -296,11 +296,11 @@ Specifies that this element should not be combined with the next element in a single send request from the sockets layer to the transport. This flag is used for granular control of the content of each message on a datagram or message-oriented socket. Initializes a new instance of the class using the specified buffer with an option to combine this element with the next element in a single send request from the sockets layer to the transport. - class is used with the property to get or set a data buffer or file to be sent using the method. - + class is used with the property to get or set a data buffer or file to be sent using the method. + ]]> @@ -355,16 +355,16 @@ The number of bytes to send starting from the parameter. If is zero, no bytes are sent. Initializes a new instance of the class using the specified range of the buffer. - class is used with the property to get or set a data buffer or file to be sent using the method. - + class is used with the property to get or set a data buffer or file to be sent using the method. + ]]> The parameter cannot be null. - The and parameters must be greater than or equal to zero. - + The and parameters must be greater than or equal to zero. + The and must be less than the size of the buffer. @@ -406,11 +406,11 @@ The number of bytes to send starting from the . If is zero, the entire file is sent. Initializes a new instance of the class using the specified range of a object. - class is used with the property to get or set a data buffer or file to be sent using the method. - + class is used with the property to get or set a data buffer or file to be sent using the method. + ]]> The parameter must have been opened for asynchronous reading and writing. @@ -468,13 +468,13 @@ The number of bytes to send starting from the parameter. If is zero, the entire file is sent. Initializes a new instance of the class using the specified range of the file. - class is used with the property to get or set a data buffer or file to be sent using the method. - - Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. - + class is used with the property to get or set a data buffer or file to be sent using the method. + + Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. + ]]> The parameter cannot be null. @@ -519,13 +519,13 @@ The number of bytes to send starting from the . If is zero, the entire file is sent. Initializes a new instance of the class using the specified range of the file. - class is used with the property to get or set a data buffer or file to be sent using the method. - - Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. - + class is used with the property to get or set a data buffer or file to be sent using the method. + + Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. + ]]> The parameter cannot be . @@ -584,16 +584,16 @@ A Boolean value that specifies that this element should not be combined with the next element in a single send request from the sockets layer to the transport. This flag is used for granular control of the content of each message on a datagram or message-oriented socket. Initializes a new instance of the class using the specified range of the buffer with an option to combine this element with the next element in a single send request from the sockets layer to the transport. - class is used with the property to get or set a data buffer or file to be sent using the method. - + class is used with the property to get or set a data buffer or file to be sent using the method. + ]]> The parameter cannot be null. - The and parameters must be greater than or equal to zero. - + The and parameters must be greater than or equal to zero. + The and must be less than the size of the buffer. @@ -637,11 +637,11 @@ Specifies that this element should not be combined with the next element in a single send request from the sockets layer to the transport. This flag is used for granular control of the content of each message on a datagram or message-oriented socket. Initializes a new instance of the class using the specified range of a object with an option to combine this element with the next element in a single send request from the sockets layer to the transport. - class is used with the property to get or set a data buffer or file to be sent using the method. - + class is used with the property to get or set a data buffer or file to be sent using the method. + ]]> The parameter must have been opened for asynchronous reading and writing. @@ -701,13 +701,13 @@ A Boolean value that specifies that this element should not be combined with the next element in a single send request from the sockets layer to the transport. This flag is used for granular control of the content of each message on a datagram or message-oriented socket. Initializes a new instance of the class using the specified range of the file with an option to combine this element with the next element in a single send request from the sockets layer to the transport. - class is used with the property to get or set a data buffer or file to be sent using the method. - - Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. - + class is used with the property to get or set a data buffer or file to be sent using the method. + + Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. + ]]> The parameter cannot be null. @@ -754,13 +754,13 @@ Specifies that this element should not be combined with the next element in a single send request from the sockets layer to the transport. This flag is used for granular control of the content of each message on a datagram or message-oriented socket. Initializes a new instance of the class using the specified range of the file with an option to combine this element with the next element in a single send request from the sockets layer to the transport. - class is used with the property to get or set a data buffer or file to be sent using the method. - - Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. - + class is used with the property to get or set a data buffer or file to be sent using the method. + + Universal Naming Convention (UNC) paths are supported by the `filepath` parameter. If the file is in the current working directory, no path information needs to be specified. + ]]> The parameter cannot be . @@ -818,13 +818,13 @@ Gets the buffer to be sent if the object was initialized with a parameter. The byte buffer to send if the object was initialized with a parameter. - property is `null` if the object was not initialized with a `buffer` parameter or `buffer` was passed as a of bytes. In the latter case, the buffer can be obtained using the property. - + ]]> @@ -875,13 +875,13 @@ Gets the count of bytes to be sent. The count of bytes to send if the class was initialized with a parameter. - property is zero if the class was not initialized with a `count` parameter. - - If is zero for a file, the entire file is sent. If is zero for a buffer, no bytes are sent. - + property is zero if the class was not initialized with a `count` parameter. + + If is zero for a file, the entire file is sent. If is zero for a buffer, no bytes are sent. + ]]> @@ -926,11 +926,11 @@ Gets a Boolean value that indicates if this element should not be combined with the next element in a single send request from the sockets layer to the transport. A Boolean value that indicates if this element should not be combined with the next element in a single send request. - property is false if the class was not initialized with an `endOfPacket` parameter set to true. - + property is false if the class was not initialized with an `endOfPacket` parameter set to true. + ]]> @@ -986,13 +986,13 @@ Gets the filename of the file to send if the object was initialized with a parameter. The filename of the file to send if the object was initialized with a parameter. - property. If the file is in the current working directory, no path information needs to be specified. - - The default value for the property is `null` if the object was not initialized with a `filepath` parameter. - + property. If the file is in the current working directory, no path information needs to be specified. + + The default value for the property is `null` if the object was not initialized with a `filepath` parameter. + ]]> @@ -1034,12 +1034,12 @@ Gets the object representation of the file to send if the object was initialized with a parameter. An object representation of the file to send if the object was initialized with a parameter. - property is `null` if the object was not initialized with a `fileStream` parameter. - + ]]> @@ -1077,12 +1077,12 @@ Gets the buffer to be sent if the object was initialized with a buffer parameter. The of bytes to be sent if the object was initialized with a buffer parameter. - property is `null` if the object was not initialized with a `buffer` parameter. If `buffer` was passed as a `byte[]`, returns the contents of as a of bytes. - + ]]> @@ -1133,12 +1133,12 @@ Gets the offset, in bytes, from the beginning of the data buffer or file to the location in the buffer or file to start sending the data. The offset, in bytes, from the beginning of the data buffer or file to the location in the buffer or file to start sending the data. - property is zero if the class was not initialized with an `offset` parameter. - - If is greater than , will throw a when you try to access it. + property is zero if the class was not initialized with an `offset` parameter. + + If is greater than , will throw a when you try to access it. ]]> @@ -1174,12 +1174,12 @@ Gets the offset, in bytes, from the beginning of the data buffer or file to the location in the buffer or file to start sending the data. The offset, in bytes, from the beginning of the data buffer or file to the location in the buffer or file to start sending the data. - property is zero if the class was not initialized with an `offset` parameter. - - If is greater than , will throw a when you try to access it. + property is zero if the class was not initialized with an `offset` parameter. + + If is greater than , will throw a when you try to access it. ]]> diff --git a/xml/System.Net.Sockets/Socket.xml b/xml/System.Net.Sockets/Socket.xml index dd3fffbb65f..8c9623c15c6 100644 --- a/xml/System.Net.Sockets/Socket.xml +++ b/xml/System.Net.Sockets/Socket.xml @@ -265,7 +265,7 @@ This method populates the instance with data ga The `socketType` parameter specifies the type of the class and the `protocolType` parameter specifies the protocol used by . The two parameters are not independent. Often the type is implicit in the protocol. If the combination of type and protocol type results in an invalid , this constructor throws a . > [!NOTE] -> If this constructor throws a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If this constructor throws a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -330,7 +330,7 @@ This method populates the instance with data ga The `addressFamily` parameter specifies the addressing scheme that the class uses, the `socketType` parameter specifies the type of the class, and the `protocolType` parameter specifies the protocol used by . The three parameters are not independent. Some address families restrict which protocols can be used with them, and often the type is implicit in the protocol. If the combination of address family, type, and protocol type results in an invalid , this constructor throws a . > [!NOTE] -> If this constructor throws a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If this constructor throws a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -404,7 +404,7 @@ This method populates the instance with data ga In blocking mode, blocks until an incoming connection attempt is queued. Once a connection is accepted, the original continues queuing incoming connection requests until you close it. - If you call this method using a non-blocking , and no connection requests are queued, throws a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you call this method using a non-blocking , and no connection requests are queued, throws a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > Before calling the method, you must first call the method to listen for and queue incoming connection requests. @@ -584,17 +584,17 @@ This method populates the instance with data ga - - The caller can optionally specify an existing to use for the incoming connection by specifying the to use with the property. + The caller can optionally specify an existing to use for the incoming connection by specifying the to use with the property. - If the property is null, a new is constructed with the same , , and as the current and set as the property. + If the property is null, a new is constructed with the same , , and as the current and set as the property. - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - Optionally, a buffer may be provided in which to receive the initial block of data on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to receive and the property needs to be set to the maximum number of bytes of data to receive in the buffer. These properties can be set using the method. Part of the buffer passed in will be consumed internally for use by the underlying Winsock AcceptEx call. This means that the amount of data returned will always be less than the value of the property on the instance provided. The amount of the buffer used internally varies based on the address family of the socket. The minimum buffer size required is 288 bytes. If a larger buffer size is specified, then the will expect some extra data other than the address data received by the Winsock AcceptEx call and will wait until this extra data is received. If a timeout occurs, the connection is reset. So if extra data is expected of a specific amount, then the buffer size should be set to the minimum buffer size plus this amount. + Optionally, a buffer may be provided in which to receive the initial block of data on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to receive and the property needs to be set to the maximum number of bytes of data to receive in the buffer. These properties can be set using the method. Part of the buffer passed in will be consumed internally for use by the underlying Winsock AcceptEx call. This means that the amount of data returned will always be less than the value of the property on the instance provided. The amount of the buffer used internally varies based on the address family of the socket. The minimum buffer size required is 288 bytes. If a larger buffer size is specified, then the will expect some extra data other than the address data received by the Winsock AcceptEx call and will wait until this extra data is received. If a timeout occurs, the connection is reset. So if extra data is expected of a specific amount, then the buffer size should be set to the minimum buffer size plus this amount. - The completion callback method should examine the property to determine if the operation was successful. + The completion callback method should examine the property to determine if the operation was successful. - The event can occur in some cases when no connection has been accepted and cause the property to be set to . This can occur as a result of port scanning using a half-open SYN type scan (a SYN -> SYN-ACK -> RST sequence). Applications using the method should be prepared to handle this condition. + The event can occur in some cases when no connection has been accepted and cause the property to be set to . This can occur as a result of port scanning using a half-open SYN type scan (a SYN -> SYN-ACK -> RST sequence). Applications using the method should be prepared to handle this condition. ]]> @@ -839,7 +839,7 @@ This method populates the instance with data ga ## Remarks If you are using a non-blocking , is a good way to determine whether data is queued for reading, before calling . The available data is the total amount of data queued in the network buffer for reading. If no data is queued in the network buffer, returns 0. - If the remote host shuts down or closes the connection, can throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If the remote host shuts down or closes the connection, can throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -934,17 +934,17 @@ This method populates the instance with data ga Connection-oriented protocols can use the method to start accepting incoming connection attempts. Before calling the method, you must call the method to listen for and queue incoming connection requests. - You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> You can use the property of the returned to identify the remote host's network address and port number. +> You can use the property of the returned to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1041,17 +1041,17 @@ This method populates the instance with data ga Connection-oriented protocols can use the method to start accepting incoming connection attempts. Before calling the method, you must call the method to listen for and queue incoming connection requests. - You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> You can use the property of the returned to identify the remote host's network address and port number. +> You can use the property of the returned to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1146,17 +1146,17 @@ This method populates the instance with data ga Connection-oriented protocols can use the method to start accepting incoming connection attempts. The resulting accept operation is represented by the returned even though it may complete synchronously. Before calling the method, you must call the method to listen for and queue incoming connection requests. - You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> You can use the property of the returned to identify the remote host's network address and port number. +> You can use the property of the returned to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1268,17 +1268,17 @@ This method populates the instance with data ga Connection-oriented protocols can use the method to start accepting incoming connection attempts. The resulting accept operation is represented by the returned even though it may complete synchronously. Before calling the method, you must call the method to listen for and queue incoming connection requests. - You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the accept operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> You can use the property of the returned to identify the remote host's network address and port number. +> You can use the property of the returned to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1378,7 +1378,7 @@ This method populates the instance with data ga If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the endpoit specified by the `remoteEP` parameter. If you are using a connectionless protocol, establishes a default remote host. - You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. @@ -1389,7 +1389,7 @@ This method populates the instance with data ga To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. @@ -1494,7 +1494,7 @@ This method populates the instance with data ga If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the endpoit specified by the `remoteEP` parameter. If you are using a connectionless protocol, establishes a default remote host. - You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. @@ -1505,7 +1505,7 @@ This method populates the instance with data ga To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. @@ -1610,7 +1610,7 @@ This method populates the instance with data ga If you are using a connection-oriented protocol, the method starts an asynchronous request for a connection to the endpoit specified by the `remoteEP` parameter. If you are using a connectionless protocol, establishes a default remote host. - You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the connect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. @@ -1621,7 +1621,7 @@ This method populates the instance with data ga To cancel a pending call to the method, close the . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > If this socket has previously been disconnected, then must be called on a thread that will not exit until the operation is complete. This is a limitation of the underlying provider. @@ -1715,12 +1715,12 @@ This method populates the instance with data ga If you are using a connection-oriented protocol, you can call the method to initiate disconnection from a remote endpoint. If `reuseSocket` is `true`, you can reuse the socket. - You can pass a callback that implements to in order to get notified about the completion of the disconnect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the disconnect operation. Note that if the underlying network stack completes the operation synchronously, the callback might be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. > [!NOTE] -> If you receive a exception, use the property to obtain the specific error code. +> If you receive a exception, use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1813,14 +1813,14 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -1918,14 +1918,14 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -2033,14 +2033,14 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -2156,14 +2156,14 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. Close the to cancel a pending . When the method is called while an asynchronous operation is in progress, the callback provided to the method is called. A subsequent call to the method will throw an (before .NET 7) or a (on .NET 7+) to indicate that the operation has been cancelled. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -2287,7 +2287,7 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. @@ -2304,7 +2304,7 @@ This method populates the instance with data ga To cancel a pending , call the method. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -2424,7 +2424,7 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. @@ -2433,7 +2433,7 @@ This method populates the instance with data ga This method reads data into the `buffer` parameter, and captures the remote host endpoint from which the data is sent, as well as information about the received packet. For information on how to retrieve this endpoint, refer to . This method is most useful if you intend to asynchronously receive connectionless datagrams from an unknown host or multiple hosts. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -2549,7 +2549,7 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. @@ -2558,7 +2558,7 @@ This method populates the instance with data ga If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -2659,7 +2659,7 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. @@ -2668,7 +2668,7 @@ This method populates the instance with data ga If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -2779,7 +2779,7 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. @@ -2788,7 +2788,7 @@ This method populates the instance with data ga If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -2905,7 +2905,7 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The asynchronous operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. @@ -2914,7 +2914,7 @@ This method populates the instance with data ga If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -3035,14 +3035,14 @@ This method populates the instance with data ga This overload sends the file `fileName` over the socket. If `fileName` is in the local directory, it may be identified with just the name of the file; otherwise, the full path and name of the file must be specified. Wildcards ("..\\\myfile.txt") and UNC share names ("\\\\\\\shared directory\\\myfile.txt") are supported. If the file is not found, the exception is thrown. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the delegate. will block the calling thread until the operation is completed. Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. With connectionless protocols, you must be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. > [!NOTE] -> If you receive a exception, use the property to obtain the specific error code. +> If you receive a exception, use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3131,14 +3131,14 @@ This method populates the instance with data ga The `flags` parameter provides additional information about the file transfer. For more information about how to use this parameter, see . - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. Although intended for connection-oriented protocols, also works for connectionless protocols, provided that you first call the or method to establish a default remote host. With connectionless protocols, you must be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. If it does, the datagram is not sent and throws a exception. > [!NOTE] -> If you receive a exception, use the property to obtain the specific error code. +> If you receive a exception, use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3238,20 +3238,20 @@ This method populates the instance with data ga > [!IMPORTANT] > This is a compatibility API. We don't recommend using the [APM](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-model-apm) (`Begin*` and `End*`) methods for new development. Instead, use the `Task`-based equivalents. - You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. + You can pass a callback that implements to in order to get notified about the completion of the operation. Note that if the underlying network stack completes the operation synchronously, the callback will be executed inline, during the call to . In this case, the property on the returned will be set to `true` to indicate that the method completed synchronously. Use the property of the to obtain the state object passed to the method. The operation must be completed by calling the method. Typically, the method is invoked by the provided delegate. will block the calling thread until the operation is completed. If you are using a connection-oriented protocol, you must first call the , , , or method, or will throw a . will ignore the `remoteEP` parameter and send data to the established in the , , , or method. - If you are using a connectionless protocol, you do not need to establish a default remote host with the or method prior to calling . You only need to do this if you intend to call the method. If you do call the or method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. + If you are using a connectionless protocol, you do not need to establish a default remote host with the or method prior to calling . You only need to do this if you intend to call the method. If you do call the or method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. If you want to send data to a broadcast address, you must first call the method and set the socket option to . -You must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3359,7 +3359,7 @@ This method populates the instance with data ga > You must call the method if you intend to receive connectionless datagrams using the method. > [!NOTE] -> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3440,12 +3440,12 @@ This method populates the instance with data ga property indicates whether a is in blocking mode. + The property indicates whether a is in blocking mode. - If you are in blocking mode, and you make a method call that does not complete immediately, your application will block execution until the requested operation completes. If you want execution to continue even though the requested operation is not complete, change the property to `false`. The property has no effect on asynchronous methods. If you are sending and receiving data asynchronously and want to block execution, use the class. + If you are in blocking mode, and you make a method call that does not complete immediately, your application will block execution until the requested operation completes. If you want execution to continue even though the requested operation is not complete, change the property to `false`. The property has no effect on asynchronous methods. If you are sending and receiving data asynchronously and want to block execution, use the class. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3571,14 +3571,14 @@ This method populates the instance with data ga method closes the remote host connection and releases all managed and unmanaged resources associated with the . Upon closing, the property is set to `false`. + The method closes the remote host connection and releases all managed and unmanaged resources associated with the . Upon closing, the property is set to `false`. For connection-oriented protocols, it is recommended that you call before calling the method. This ensures that all data is sent and received on the connected socket before it is closed. If you need to call without first calling , you can ensure that data queued for outgoing transmission will be sent by setting the option to `false` and specifying a non-zero time-out interval. will then block until this data is sent or until the specified time-out expires. If you set to `false` and specify a zero time-out interval, releases the connection and automatically discards outgoing queued data. > [!NOTE] -> To set the socket option to `false`, create a , set the enabled property to `true`, and set the property to the desired time out period. Use this along with the socket option to call the method. +> To set the socket option to `false`, create a , set the enabled property to `true`, and set the property to the desired time out period. Use this along with the socket option to call the method. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3645,14 +3645,14 @@ This method populates the instance with data ga method closes the remote host connection and releases all managed and unmanaged resources associated with the . Upon closing, the property is set to `false`. + The method closes the remote host connection and releases all managed and unmanaged resources associated with the . Upon closing, the property is set to `false`. For connection-oriented protocols, it is recommended that you call before calling . This ensures that all data is sent and received on the connected socket before it is closed. If you need to call without first calling , you can ensure that data queued for outgoing transmission will be sent by setting the option to `false` and specifying a non-zero time-out interval. will then block until this data is sent or until the specified time-out expires. If you set to `false` and specify a zero time-out interval, releases the connection and automatically discards outgoing queued data. > [!NOTE] -> To set the socket option to `false`, create a , set the enabled property to `true`, and set the property to the desired time-out period. Use this along with the socket option to call the method. +> To set the socket option to `false`, create a , set the enabled property to `true`, and set the property to the desired time-out period. Use this along with the socket option to call the method. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3733,9 +3733,9 @@ This method populates the instance with data ga ## Remarks If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call , you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - The method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + The method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. > [!NOTE] > If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. @@ -3825,9 +3825,9 @@ This method populates the instance with data ga ## Remarks If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. > [!NOTE] > If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. @@ -3908,9 +3908,9 @@ This method populates the instance with data ga ## Remarks This method is typically used immediately after a call to , which can return multiple IP addresses for a single host. If you are using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote endpoint. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. - If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + method will block, unless you specifically set the property to `false` prior to calling . If you are using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. > [!NOTE] > If you are using a connection-oriented protocol and did not call before calling , the underlying service provider will assign the local network address and port number. If you are using a connectionless protocol, the service provider will not assign a local network address and port number until you complete a send or receive operation. If you want to change the default remote host, call again with the desired endpoint. @@ -3991,9 +3991,9 @@ This method populates the instance with data ga ## Remarks If you're using a connection-oriented protocol such as TCP, the method synchronously establishes a network connection between and the specified remote host. If you are using a connectionless protocol, establishes a default remote host. After you call you can send data to the remote device with the method, or receive data from the remote device with the method. - If you're using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you're using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to synchronously communicate with a remote host. If you do call any datagrams that arrive from an address other than the specified default will be discarded. If you want to set your default remote host to a broadcast address, you must first call the method and set the socket option to , or will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. - The method will block, unless you specifically set the property to `false` prior to calling . If you're using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. + The method will block, unless you specifically set the property to `false` prior to calling . If you're using a connection-oriented protocol like TCP and you do disable blocking, will throw a because it needs time to make the connection. Connectionless protocols will not throw an exception because they simply establish a default remote host. You can use to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. If the error returned WSAEWOULDBLOCK, the remote host connection has been initiated by a connection-oriented , but has not yet completed successfully. Use the method to determine when the is finished connecting. If IPv6 is enabled and the method is called to connect to a host that resolves to both IPv6 and IPv4 addresses, the connection to the IPv6 address will be attempted first before the IPv4 address. This may have the effect of delaying the time to establish the connection if the host is not listening on the IPv6 address. @@ -4135,9 +4135,9 @@ This method populates the instance with data ga To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. - The caller must set the property to the of the remote host to connect to. + The caller must set the property to the of the remote host to connect to. - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to change the default remote host, call the method again with the desired endpoint. @@ -4149,7 +4149,7 @@ This method populates the instance with data ga - - Optionally, a buffer may be provided that will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. + Optionally, a buffer may be provided that will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. @@ -4158,7 +4158,7 @@ This method populates the instance with data ga The method throws if the address family of the and the are not the same address family. > [!NOTE] -> If you receive a when calling this method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a when calling this method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ]]> @@ -4558,9 +4558,9 @@ This method populates the instance with data ga To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. - The caller must set the property to the of the remote host to connect to. + The caller must set the property to the of the remote host to connect to. - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. If you are using a connectionless protocol such as UDP, you do not have to call before sending and receiving data. You can use and to communicate with a remote host. If you do call , any datagrams that arrive from an address other than the specified default will be discarded. If you want to change the default remote host, call the method again with the desired endpoint. @@ -4572,7 +4572,7 @@ This method populates the instance with data ga - - Optionally, a buffer may be provided that will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. + Optionally, a buffer may be provided that will atomically be sent on the socket after the method succeeds. In this case, the property needs to be set to the buffer containing the data to send and the property needs to be set to the number of bytes of data to send from the buffer. Once a connection is established, this buffer of data is sent. If you are using a connection-oriented protocol and do not call before calling , the underlying service provider will assign the most appropriate local network address and port number. @@ -4581,7 +4581,7 @@ This method populates the instance with data ga The method throws if the address family of the and the are not the same address family. > [!NOTE] -> If you receive a when calling this method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a when calling this method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ]]> @@ -4741,14 +4741,14 @@ This method populates the instance with data ga ## Remarks The `Connected` property gets the connection state of the as of the last I/O operation. When it returns `false`, the was either never connected, or is no longer connected. `Connected` is not thread-safe; it may return `true` after an operation is aborted when the is disconnected from another thread. - The value of the property reflects the state of the connection as of the most recent operation. If you need to determine the current state of the connection, make a nonblocking, zero-byte Send call. If the call returns successfully or throws a WAEWOULDBLOCK error code (10035), then the socket is still connected; otherwise, the socket is no longer connected. + The value of the property reflects the state of the connection as of the most recent operation. If you need to determine the current state of the connection, make a nonblocking, zero-byte Send call. If the call returns successfully or throws a WAEWOULDBLOCK error code (10035), then the socket is still connected; otherwise, the socket is no longer connected. - If you call on a User Datagram Protocol (UDP) socket, the property always returns `true`; however, this action does not change the inherent connectionless nature of UDP. + If you call on a User Datagram Protocol (UDP) socket, the property always returns `true`; however, this action does not change the inherent connectionless nature of UDP. ## Examples - The following code example connects to a remote endpoint, checks the property, and checks the current state of the connection. + The following code example connects to a remote endpoint, checks the property, and checks the current state of the connection. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/Connect/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/Socket/Connect/source.vb" id="Snippet1"::: @@ -4806,14 +4806,14 @@ This method populates the instance with data ga property to `false`. However, if `reuseSocket` is `true`, you can reuse the socket. + If you are using a connection-oriented protocol, you can use this method to close the socket. This method ends the connection and sets the property to `false`. However, if `reuseSocket` is `true`, you can reuse the socket. To ensure that all data is sent and received before the socket is closed, you should call before calling the method. If you need to call without first calling , you can set the option to `false` and specify a nonzero time-out interval to ensure that data queued for outgoing transmission is sent. then blocks until the data is sent or until the specified time-out expires. If you set to `false` and specify a zero time-out interval, releases the connection and automatically discards outgoing queued data. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -5130,7 +5130,7 @@ This method populates the instance with data ga Setting this property on a Transmission Control Protocol (TCP) socket has no effect. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet2"::: @@ -5318,7 +5318,7 @@ Duplication of the socket reference failed. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet2"::: @@ -5639,7 +5639,7 @@ Duplication of the socket reference failed. completes the operation started by . You need to pass the created by the matching call. will block the calling thread until the operation is completed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -5717,7 +5717,7 @@ Duplication of the socket reference failed. completes the operation started by . You need to pass the created by the matching call. will block the calling thread until the operation is completed. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -5807,7 +5807,7 @@ Duplication of the socket reference failed. The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -5895,7 +5895,7 @@ Duplication of the socket reference failed. The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -5984,7 +5984,7 @@ Duplication of the socket reference failed. The method will block until data is available. If you are using a connectionless protocol, will read the first enqueued datagram available in the incoming network buffer. If you are using a connection-oriented protocol, the method will read as much data as is available up to the number of bytes you specified in the `size` parameter of the method. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. To obtain the received data, call the method of the object, and extract the buffer contained in the resulting state object. To identify the originating host, extract the and cast it to an . Use the method to obtain the IP address and the method to obtain the port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6068,7 +6068,7 @@ Duplication of the socket reference failed. Examine `ipPacketInformation` if you need to know if the datagram was sent using a unicast, multicast, or broadcast address. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. ]]> @@ -6160,7 +6160,7 @@ Duplication of the socket reference failed. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -6253,7 +6253,7 @@ Duplication of the socket reference failed. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. +> If you receive a , use the property to obtain the specific error code. > [!NOTE] > All I/O initiated by a given thread is canceled when that thread exits. A pending asynchronous operation can fail if the thread exits before the operation completes. @@ -6341,7 +6341,7 @@ Duplication of the socket reference failed. If you are using a connectionless protocol, blocks until the datagram is sent. If you are using a connection-oriented protocol, blocks until the entire file is sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6421,7 +6421,7 @@ Duplication of the socket reference failed. If you are using a connectionless protocol, will block until the datagram is sent. If you are using a connection-oriented protocol, will block until the requested number of bytes are sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6496,7 +6496,7 @@ Duplication of the socket reference failed. This property must be set before is called; otherwise an will be thrown. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet1"::: @@ -6723,7 +6723,7 @@ In general, the `GetSocketOption` method should be used whenever getting a options determine the behavior of the current . Use this overload to get the , , and options. For the option, use for the `optionLevel` parameter. For and , use . If you want to set the value of any of the options listed above, use the method. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6805,7 +6805,7 @@ In general, the `GetSocketOption` method should be used whenever getting a options determine the behavior of the current . Upon successful completion of this method, the array specified by the `optionValue` parameter contains the value of the specified option. - When the length of the `optionValue` array is smaller than the number of bytes required to store the value of the specified option, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Use this overload for any sockets that are represented by Boolean values or integers. + When the length of the `optionValue` array is smaller than the number of bytes required to store the value of the specified option, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Use this overload for any sockets that are represented by Boolean values or integers. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6889,7 +6889,7 @@ In general, the `GetSocketOption` method should be used whenever getting a will throw a . Use this overload for any sockets that are represented by Boolean values or integers. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -7029,7 +7029,7 @@ In general, the `GetSocketOption` method should be used whenever getting a method provides low-level access to the operating system underlying the current instance of the class. For more information, see the [WSAIoctl](/windows/win32/api/winsock2/nf-winsock2-wsaioctl) documentation. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -7107,7 +7107,7 @@ In general, the `GetSocketOption` method should be used whenever getting a underlying the current instance of the class. For more, see the [WSAIoctl](/windows/win32/api/winsock2/nf-winsock2-wsaioctl) documentation. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -7115,7 +7115,7 @@ In general, the `GetSocketOption` method should be used whenever getting a with and the property. + The following code example compares the results of calling with and the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/IOControlCode/Overview/iocontrolcode.cs" id="Snippet1"::: @@ -7178,7 +7178,7 @@ In general, the `GetSocketOption` method should be used whenever getting a property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet1"::: @@ -7243,15 +7243,15 @@ In general, the `GetSocketOption` method should be used whenever getting a property changes the way method behaves. This property when set modifies the conditions under which the connection can be reset by Winsock. Connection resets can still occur based on the IP protocol behavior. + The property changes the way method behaves. This property when set modifies the conditions under which the connection can be reset by Winsock. Connection resets can still occur based on the IP protocol behavior. This property controls the length of time that a connection-oriented connection will remain open after a call to when data remains to be sent. When you call methods to send data to a peer, this data is placed in the outgoing network buffer. This property can be used to ensure that this data is sent to the remote host before the method drops the connection. - To enable lingering, create a instance containing the desired values, and set the property to this instance. + To enable lingering, create a instance containing the desired values, and set the property to this instance. - The following table describes the behavior of the method for the possible values of the property and the property stored in the property. + The following table describes the behavior of the method for the possible values of the property and the property stored in the property. |LingerState.Enabled|LingerState.LingerTime|Behavior| |-------------------------|----------------------------|--------------| @@ -7259,14 +7259,14 @@ In general, the `GetSocketOption` method should be used whenever getting a property is not set. + The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a socket when the property is not set. - When the property stored in the property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override. + When the property stored in the property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet1"::: @@ -7373,7 +7373,7 @@ The maximum length of the pending connections queue is determined automatically. ## Remarks causes a connection-oriented to listen for incoming connection attempts. The `backlog` parameter specifies the number of incoming connections that can be queued for acceptance. To determine the maximum number of connections you can specify, retrieve the value. does not block. - If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Use or to accept a connection from the queue. + If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. Use or to accept a connection from the queue. > [!NOTE] > You must call the method before calling , or will throw a . @@ -7456,12 +7456,12 @@ The maximum length of the pending connections queue is determined automatically. property gets an that contains the local IP address and port number to which your is bound. You must cast this to an before retrieving any information. You can then call the method to retrieve the local , and the method to retrieve the local port number. + The property gets an that contains the local IP address and port number to which your is bound. You must cast this to an before retrieving any information. You can then call the method to retrieve the local , and the method to retrieve the local port number. - The property is usually set after you make a call to the method. If you allow the system to assign your socket's local IP address and port number, the property will be set after the first I/O operation. For connection-oriented protocols, the first I/O operation would be a call to the or method. For connectionless protocols, the first I/O operation would be any of the send or receive calls. + The property is usually set after you make a call to the method. If you allow the system to assign your socket's local IP address and port number, the property will be set after the first I/O operation. For connection-oriented protocols, the first I/O operation would be a call to the or method. For connectionless protocols, the first I/O operation would be any of the send or receive calls. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -7535,7 +7535,7 @@ The maximum length of the pending connections queue is determined automatically. Setting this property on a Transmission Control Protocol (TCP) socket has no effect. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet2"::: @@ -7603,7 +7603,7 @@ The maximum length of the pending connections queue is determined automatically. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet1"::: @@ -7816,7 +7816,7 @@ The maximum length of the pending connections queue is determined automatically. The method checks the state of the . Specify for the `selectMode` parameter to determine if the is readable. Specify to determine if the is writable. Use to detect an error condition. will block execution until the specified time period, measured in `microseconds`, elapses or data becomes available. Set the `microSeconds` parameter to a negative integer if you would like to wait indefinitely for a response. If you want to check the status of multiple sockets, you might prefer to use the method. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This method cannot detect certain kinds of connection problems, such as a broken network cable, or that the remote host was shut down ungracefully. You must attempt to send or receive data to detect these kinds of errors. @@ -7938,7 +7938,7 @@ The maximum length of the pending connections queue is determined automatically. property is set when the is created, and specifies the protocol used by that . + The property is set when the is created, and specifies the protocol used by that . @@ -8019,14 +8019,14 @@ The maximum length of the pending connections queue is determined automatically. If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8122,14 +8122,14 @@ The maximum length of the pending connections queue is determined automatically. If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. **Note** This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8192,14 +8192,14 @@ This overload only requires you to provide a receive buffer. The buffer offset d If you're using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection before calling . The method will only read data that arrives from the remote host established in the or method. If you're using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. -If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there's no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. +If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there's no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you're using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you're using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost, and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). ]]> @@ -8273,14 +8273,14 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry your receive operation. + If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry your receive operation. If you are using a connection-oriented , the method will read as much data as is available up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8372,14 +8372,14 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first enqueued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8461,14 +8461,14 @@ This overload only requires you to provide a receive buffer. The buffer offset d If you're using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you're using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. -If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. +If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you're using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you're using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost, and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8551,14 +8551,14 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, The method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry your receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, The method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry your receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8654,14 +8654,14 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host connection established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call throws a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffers` parameter, `buffers` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8738,14 +8738,14 @@ This overload only requires you to provide a receive buffer. The buffer offset d If you're using a connection-oriented protocol, you must either call to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you're using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. -If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there's no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. +If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . When the time-out value is exceeded, the call will throw a . If you're in non-blocking mode, and there's no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you're using a connection-oriented , the method will read as much data as is available, up to the size of the buffer. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you're using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8823,14 +8823,14 @@ If you're using a connectionless , to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the size parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. If you are using a connectionless , will read the first queued datagram from the destination address you specify in the method. If the datagram you receive is larger than the size of the `buffer` parameter, `buffer` gets filled with the first part of the message, the excess data is lost and a is thrown. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8942,7 +8942,7 @@ If you're using a connectionless , to establish a remote host connection, or to accept an incoming connection prior to calling . The method will only read data that arrives from the remote host established in the or method. If you are using a connectionless protocol, you can also use the method. will allow you to receive data arriving from any host. - If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available, unless a time-out value was set by using . If the time-out value was exceeded, the call will throw a . If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . An error occurred when attempting to access the socket. See Remarks below. You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. If you are using a connection-oriented , the method will read as much data as is available, up to the number of bytes specified by the size parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. @@ -9130,7 +9130,7 @@ If you're using a connectionless , property on the `e` parameter provides the Window Sockets service provider with additional information about the read request. For more information about how to use this parameter, see . + The property on the `e` parameter provides the Window Sockets service provider with additional information about the read request. For more information about how to use this parameter, see . The following properties and events on the object are required to successfully call this method: @@ -9142,7 +9142,7 @@ If you're using a connectionless , - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. For byte stream-style sockets, incoming data is placed into the buffer until the buffer is filled, the connection is closed, or the internally buffered data is exhausted. @@ -9406,7 +9406,7 @@ If you're using a connectionless , property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet1"::: @@ -9489,14 +9489,14 @@ If you're using a connectionless , will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. - If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. With connection-oriented sockets, will read as much data as is available up to the size of `buffer`. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The of the used in needs to match the of the used in . @@ -9646,14 +9646,14 @@ If you're using a connectionless , will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. - If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. With connection-oriented sockets, will read as much data as is available up to the size of `buffer`. If the remote host shuts down the connection with the method, and all available data has been Received, the method will complete immediately and return zero bytes. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The of the used in needs to match the of the used in . @@ -9863,14 +9863,14 @@ If you're using a connectionless , will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. - If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. With connection-oriented sockets, will read as much data as is available up to the number of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been received, the method will complete immediately and return zero bytes. > [!NOTE] -> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The of the used in needs to match the of the used in . @@ -9983,14 +9983,14 @@ If you're using a connectionless , will read the first enqueued datagram received into the local network buffer. If the datagram you receive is larger than the size of `buffer`, the method will fill `buffer` with as much of the message as is possible, and throw a . If you are using an unreliable protocol, the excess data will be lost. If you are using a reliable protocol, the excess data will be retained by the service provider and you can retrieve it by calling the method with a large enough buffer. - If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. + If no data is available for reading, the method will block until data is available. If you are in non-blocking mode, and there is no data available in the protocol stack buffer, the method will complete immediately and throw a . You can use the property to determine if data is available for reading. When is non-zero, retry the receive operation. Although is intended for connectionless protocols, you can use a connection-oriented protocol as well. If you choose to do so, you must first either establish a remote host connection by calling the method or accept an incoming remote host connection by calling the method. If you do not establish or accept a connection before calling the method, you will get a . You can also establish a default remote host for a connectionless protocol prior to calling the method. With connection-oriented sockets, will read as much data as is available up to the amount of bytes specified by the `size` parameter. If the remote host shuts down the connection with the method, and all available data has been Received, the method will complete immediately and return zero bytes. > [!NOTE] -> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> Before calling , you must explicitly bind the to a local endpoint using the method. If you do not, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The of the used in needs to match the of the used in . @@ -10103,9 +10103,9 @@ If you're using a connectionless , method is used primarily to receive data on a connectionless socket. The socket's local address must be known. - The caller must set the property to an of the same type as the endpoint of the remote host. The property will be updated on successful receive to the actual remote endpoint. + The caller must set the property to an of the same type as the endpoint of the remote host. The property will be updated on successful receive to the actual remote endpoint. - The property on the `e` parameter provides the Window Sockets service provider with additional information about the read request. For more information about how to use this parameter, see . + The property on the `e` parameter provides the Window Sockets service provider with additional information about the read request. For more information about how to use this parameter, see . The following properties and events on the object are required to successfully call this method: @@ -10119,7 +10119,7 @@ If you're using a connectionless , - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer. The and properties determine where in the buffer the data is placed and the amount of data. @@ -10646,7 +10646,7 @@ You must call the Bind method before performing this operation. ## Remarks The method is used primarily to receive message data on a connectionless socket. The socket's local address must be known. This method can only be used with datagram and raw sockets. The socket must be initialized with the socket type set to or before calling this method. This can be done when the socket is constructed using . - The caller must set the property to an of the same type as the endpoint of the remote host. The property will be updated on successful receive to the actual remote endpoint. + The caller must set the property to an of the same type as the endpoint of the remote host. The property will be updated on successful receive to the actual remote endpoint. The following properties and events on the object are required to successfully call this method: @@ -10660,7 +10660,7 @@ You must call the Bind method before performing this operation. - - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. For message-oriented sockets, an incoming message is placed into the buffer up to the total size of the buffer. The and properties determine where in the buffer the data is placed and the amount of data. @@ -10949,7 +10949,7 @@ You must call the Bind method before performing this operation. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet1"::: @@ -11015,9 +11015,9 @@ You must call the Bind method before performing this operation. property gets the that contains the remote IP address and port number to which the is connected. If you are using a connectionless protocol, contains the default remote IP address and port number with which the will communicate. You must cast this to an before retrieving any information. You can then call the method to retrieve the remote , and the method to retrieve the remote port number. + If you are using a connection-oriented protocol, the property gets the that contains the remote IP address and port number to which the is connected. If you are using a connectionless protocol, contains the default remote IP address and port number with which the will communicate. You must cast this to an before retrieving any information. You can then call the method to retrieve the remote , and the method to retrieve the remote port number. - The is set after a call to either or . If you try to access this property earlier, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + The is set after a call to either or . If you try to access this property earlier, will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -11158,7 +11158,7 @@ You must call the Bind method before performing this operation. > This method cannot detect certain kinds of connection problems, such as a broken network cable, or that the remote host was shut down ungracefully. You must attempt to send or receive data to detect these kinds of errors. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -11300,7 +11300,7 @@ You must call the Bind method before performing this operation. If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -11402,7 +11402,7 @@ You must call the Bind method before performing this operation. If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -11477,7 +11477,7 @@ If you're using a connectionless protocol and plan to send data to several diffe If you're using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There's also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] ->If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +>If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -11558,7 +11558,7 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> You must ensure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> You must ensure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -11654,7 +11654,7 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In non-blocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -11802,7 +11802,7 @@ If you're using a connectionless protocol and plan to send data to several diffe With a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> You must ensure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram won't be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> You must ensure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram won't be sent and will throw a . If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -11905,7 +11905,7 @@ The following code example sends the data found in buffer, and specifies will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In non-blocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -11983,7 +11983,7 @@ If you're using a connectionless protocol and plan to send data to several diffe If you're using a connection-oriented protocol, will block until all of the bytes in the buffer are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes in the buffer. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the bytes in the buffer. There's also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] ->If you receive a , use the property to obtain the specific error code. After you've obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +>If you receive a , use the property to obtain the specific error code. After you've obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -12070,7 +12070,7 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -12188,7 +12188,7 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connection-oriented protocol, will block until the requested number of bytes are sent, unless a time-out was set by using . If the time-out value was exceeded, the call will throw a . In nonblocking mode, may complete successfully even if it sends less than the number of bytes you request. It is your application's responsibility to keep track of the number of bytes sent and to retry the operation until the application sends the requested number of bytes. There is also no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > The successful completion of a send does not indicate that the data was successfully delivered. If no buffer space is available within the transport system to hold the data to be transmitted, send will block unless the socket has been placed in nonblocking mode. @@ -12398,7 +12398,7 @@ This member outputs trace information when you enable network tracing in your ap - - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. The method will throw an exception if you do not first call , , , , or . @@ -12661,7 +12661,7 @@ This member outputs trace information when you enable network tracing in your ap ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet1"::: @@ -12742,7 +12742,7 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connection-oriented protocol, blocks until the file is sent. In nonblocking mode, may complete successfully before the entire file has been sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -12829,7 +12829,7 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connection-oriented protocol, blocks until the entire file is sent. In nonblocking mode, may complete successfully before the entire file has been sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the method means that the underlying system has had room to buffer your data for a network send. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -13070,7 +13070,7 @@ This member outputs trace information when you enable network tracing in your ap To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. - The property on the `e` parameter provides the Window Sockets service provider with additional information about the file transfer. For more information about how to use this parameter, see . + The property on the `e` parameter provides the Window Sockets service provider with additional information about the file transfer. For more information about how to use this parameter, see . The following properties and events on the object are required to successfully call this method: @@ -13078,7 +13078,7 @@ This member outputs trace information when you enable network tracing in your ap - - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. This method uses the TransmitPackets function found in the Windows Sockets 2 API. For more information about the TransmitPackets function and its flags, see the [Windows Sockets](/windows/desktop/WinSock/) documentation. @@ -13088,7 +13088,7 @@ This member outputs trace information when you enable network tracing in your ap On Windows client editions, the method is optimized for minimum memory and resource utilization. - Use of the flag in the property on the `e` parameter can deliver significant performance benefits. If the thread initiating the method call is being used for heavy computations, it is possible, though unlikely, that APCs could be prevented from launching. Note that there is a difference between kernel and user-mode APCs. Kernel APCs launch when a thread is in a wait state. User-mode APCs launch when a thread is in an alertable wait state + Use of the flag in the property on the `e` parameter can deliver significant performance benefits. If the thread initiating the method call is being used for heavy computations, it is possible, though unlikely, that APCs could be prevented from launching. Note that there is a difference between kernel and user-mode APCs. Kernel APCs launch when a thread is in a wait state. User-mode APCs launch when a thread is in an alertable wait state ]]> @@ -13153,7 +13153,7 @@ This member outputs trace information when you enable network tracing in your ap This option applies to synchronous calls only. If the time-out period is exceeded, the method will throw a . ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet1"::: @@ -13229,7 +13229,7 @@ This member outputs trace information when you enable network tracing in your ap ## Remarks In this overload, the buffer offset defaults to 0, the number of bytes to send defaults to the size of the `buffer` parameter, and the value defaults to 0. - If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. + If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. @@ -13238,7 +13238,7 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -13376,7 +13376,7 @@ This member outputs trace information when you enable network tracing in your ap ## Remarks In this overload, the buffer offset defaults to 0, and the number of bytes to send defaults to the size of the `buffer`. If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. - If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. + If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. @@ -13385,7 +13385,7 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -13585,7 +13585,7 @@ This member outputs trace information when you enable network tracing in your ap ## Remarks In this overload, the buffer offset defaults to 0. If you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. - If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. + If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. @@ -13594,7 +13594,7 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the number of bytes sent does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -13685,7 +13685,7 @@ This member outputs trace information when you enable network tracing in your ap ## Remarks In this overload, if you specify the flag as the `socketflags` parameter, the data you are sending will not be routed. - If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. + If you are using a connectionless protocol, you do not need to establish a default remote host with the method prior to calling . You only need to do this if you intend to call the method. If you do call the method prior to calling , the `remoteEP` parameter will override the specified default remote host for that send operation only. You are also not required to call the method, because the underlying service provider will assign the most appropriate local network address and port number. If you need to identify the assigned local network address and port number, you can use the property after the method successfully completes. Although intended for connectionless protocols, also works with connection-oriented protocols. If you are using a connection-oriented protocol, you must first establish a remote host connection by calling the method or accept an incoming connection request using the method. If you do not establish or accept a remote host connection, will throw a . You can also establish a default remote host for a connectionless protocol prior to calling the method. In either of these cases, will ignore the `remoteEP` parameter and only send data to the connected or default remote host. @@ -13694,7 +13694,7 @@ This member outputs trace information when you enable network tracing in your ap If you are using a connectionless protocol in blocking mode, will block until the datagram is sent. If you want to send data to a broadcast address, you must first call the method and set the socket option to . You must also be sure that the size does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -13797,7 +13797,7 @@ This member outputs trace information when you enable network tracing in your ap method starts an asynchronous send operation to the remote host specified in the property of the `e` parameter. Calling the method gives you the ability to send data within a separate execution thread. Although this method is intended for connectionless protocols, works with both connectionless and connection-oriented protocols. + The method starts an asynchronous send operation to the remote host specified in the property of the `e` parameter. Calling the method gives you the ability to send data within a separate execution thread. Although this method is intended for connectionless protocols, works with both connectionless and connection-oriented protocols. To be notified of completion, you must create a callback method that implements the EventHandler\ delegate and attach the callback to the event. @@ -13813,15 +13813,15 @@ This member outputs trace information when you enable network tracing in your ap - - The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. + The caller may set the property to any user state object desired before calling the method, so that the information will be retrievable in the callback method. If the callback needs more information than a single object, a small class can be created to hold the other required state information as members. - If you are using a connection-oriented protocol, you must first call the , , , , , or method. Otherwise will throw a . When using a connection-oriented protocol, the method will ignore the property and send data to the established in the , , , , , or method. + If you are using a connection-oriented protocol, you must first call the , , , , , or method. Otherwise will throw a . When using a connection-oriented protocol, the method will ignore the property and send data to the established in the , , , , , or method. - If you are using a connectionless protocol, you do not need to establish a default remote host with the , , or method prior to calling . You only need to do this if you intend to call the or methods. If you do call the , , or method prior to calling , the property will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network IP address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network IP address and port number, you can use the property after the event is signaled and the associated delegates are called. + If you are using a connectionless protocol, you do not need to establish a default remote host with the , , or method prior to calling . You only need to do this if you intend to call the or methods. If you do call the , , or method prior to calling , the property will override the specified default remote host for that send operation only. You are also not required to call the method. In this case, the underlying service provider will assign the most appropriate local network IP address and port number. Use a port number of zero if you want the underlying service provider to select a free port. If you need to identify the assigned local network IP address and port number, you can use the property after the event is signaled and the associated delegates are called. If you want to send data to a broadcast address, you must first call the method and set the socket option for to true. You must also be sure that the size of your buffer does not exceed the maximum packet size of the underlying service provider. If it does, the datagram will not be sent and will throw a . - If you specify the DontRoute flag in the property, the data you are sending will not be routed. + If you specify the DontRoute flag in the property, the data you are sending will not be routed. For message-oriented sockets, care must be taken not to exceed the maximum message size of the underlying transport. If the size of the buffer exceeds the maximum packet size of the underlying service provider, the datagram is not sent and will throw a . The successful completion of a method does not indicate that the data was successfully delivered. @@ -14345,7 +14345,7 @@ The enumeration. > [!NOTE] -> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a exception, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ## Examples The following code example opens a socket and enables the `DontLinger` and the `OutOfBandInline` socket options. @@ -14415,7 +14415,7 @@ The options determine the behavior of the current . Use this overload to set those options that require a byte array as an option value. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -14558,7 +14558,7 @@ The enumeration. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -14635,7 +14635,7 @@ The options determine the behavior of the current . Use this overload to set the , , and options. For the option, use for the `optionLevel` parameter. For and , use . If you want to get the current value of any of the options listed above, use the method. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ## Examples The following code example sets the and time out values. @@ -14730,7 +14730,7 @@ The disables both sends and receives as described above. > [!NOTE] -> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a when calling the method, use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -15050,10 +15050,10 @@ Call IDisposable.Dispose when you are finished using the , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. + If you receive a , use the property to obtain the specific error code. After you have obtained this code, refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. ## Examples - The following code example demonstrates the use of the property. + The following code example demonstrates the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/Socket/DontFragment/class1.cs" id="Snippet1"::: diff --git a/xml/System.Net.Sockets/SocketAsyncEventArgs.xml b/xml/System.Net.Sockets/SocketAsyncEventArgs.xml index 9a8b36c3219..0ee7a3a5437 100644 --- a/xml/System.Net.Sockets/SocketAsyncEventArgs.xml +++ b/xml/System.Net.Sockets/SocketAsyncEventArgs.xml @@ -160,11 +160,11 @@ - Properties that return an integer will return zero. -- The property will be equal to . +- The property will be equal to . -- The property will be equal to , which specifies no flags will be used. +- The property will be equal to , which specifies no flags will be used. -- The property will be equal to . +- The property will be equal to . The caller must set the appropriate properties prior to passing the object to the appropriate asynchronous socket (xxxAsync) method. @@ -411,13 +411,13 @@ ## Remarks This property is used with the and methods. - This property is used to provide multiple buffers of data to be sent or to provide multiple buffers in which to store received data for an asynchronous socket operation that can send or receive data. Multiple buffers using the property are supported by the and methods. + This property is used to provide multiple buffers of data to be sent or to provide multiple buffers in which to store received data for an asynchronous socket operation that can send or receive data. Multiple buffers using the property are supported by the and methods. - If the property is set to a non-null value, the property must be null and is ignored by the and methods. + If the property is set to a non-null value, the property must be null and is ignored by the and methods. - If the was set to a non-null value and an attempt is made to set the property to a non-null value, an exception is thrown. + If the was set to a non-null value and an attempt is made to set the property to a non-null value, an exception is thrown. - If the property is set to a non-null value, the and methods will throw an . + If the property is set to a non-null value, the and methods will throw an . The parameter is ignored by the and methods. @@ -614,11 +614,11 @@ was specified for the property, the property will contain the exception that indicates the detailed cause of the socket error. + In the case of a connection failure when a was specified for the property, the property will contain the exception that indicates the detailed cause of the socket error. - When an was specified for the property and a connection failure occurs, the property will be a `null` reference. + When an was specified for the property and a connection failure occurs, the property will be a `null` reference. - The property is always set in the case of a connection failure. The property contains more information about the failure if it was a failure connecting to a . If an application is only interested in whether the connect operation succeeded or failed, then the application only needs to check the property. + The property is always set in the case of a connection failure. The property contains more information about the failure if it was a failure connecting to a . If an application is only interested in whether the connect operation succeeded or failed, then the application only needs to check the property. ]]> @@ -1129,9 +1129,9 @@ This property is used with the property. This value is set by calling the method. + This property describes the starting byte offset of data in the property. This value is set by calling the method. - This property does not apply to the property. + This property does not apply to the property. This property is used with the , , , , , , and methods. @@ -1546,7 +1546,7 @@ This property is used with the property. This capability is useful for message protocols that place limitations on the size of individual send requests. + Set this property to zero to let the sockets layer select a default send size. Setting this property to 0xFFFFFFFF enables the caller to control the size and content of each send request, achieved by using the property. This capability is useful for message protocols that place limitations on the size of individual send requests. ]]> @@ -1565,7 +1565,7 @@ This property is used with the property to null and the and properties to zero. + This method sets the property to null and the and properties to zero. ]]> @@ -1617,7 +1617,7 @@ This property is used with the property to the `buffer` parameter, the property to the `buffer` length, and the property to zero. +This method sets the property to the `buffer` parameter, the property to the `buffer` length, and the property to zero. ]]> @@ -1675,11 +1675,11 @@ This method sets the property. + The `offset` and `count` parameters can't be negative numbers. The combination of the `offset` and `count` parameters must be in bounds of the buffer array in the property. - This method sets the property to the `count` parameter and the property to the `offset` parameter. If the property is null, this method ignores the `offset` and `count` parameters and sets the and properties to 0. + This method sets the property to the `count` parameter and the property to the `offset` parameter. If the property is null, this method ignores the `offset` and `count` parameters and sets the and properties to 0. - This method does not change the property. + This method does not change the property. ]]> @@ -1752,7 +1752,7 @@ This method sets the property to the `buffer` parameter, the property to the `count` parameter, and the property to the `offset` parameter. + This method sets the property to the `buffer` parameter, the property to the `count` parameter, and the property to the `offset` parameter. diff --git a/xml/System.Net.Sockets/SocketAsyncOperation.xml b/xml/System.Net.Sockets/SocketAsyncOperation.xml index fc2358f0976..cd70bc5edc8 100644 --- a/xml/System.Net.Sockets/SocketAsyncOperation.xml +++ b/xml/System.Net.Sockets/SocketAsyncOperation.xml @@ -50,13 +50,13 @@ The type of asynchronous socket operation most recently performed with this context object. - object. The value of the property is set to None until the instance is used to begin an asynchronous socket operation. The property will then be set to the type of asynchronous operation being performed. This type more easily facilitates using a single completion callback delegate for multiple kinds of asynchronous socket operations. This type is intended for use in the SocketAsyncCallback completion routine. - - The type is used by the property. - + object. The value of the property is set to None until the instance is used to begin an asynchronous socket operation. The property will then be set to the type of asynchronous operation being performed. This type more easily facilitates using a single completion callback delegate for multiple kinds of asynchronous socket operations. This type is intended for use in the SocketAsyncCallback completion routine. + + The type is used by the property. + ]]> diff --git a/xml/System.Net.Sockets/SocketException.xml b/xml/System.Net.Sockets/SocketException.xml index 384548a4965..b2647d8527d 100644 --- a/xml/System.Net.Sockets/SocketException.xml +++ b/xml/System.Net.Sockets/SocketException.xml @@ -73,7 +73,7 @@ ## Remarks A is thrown by the and classes when an error occurs with the network. - The parameterless constructor for the class sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. + The parameterless constructor for the class sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. ]]> @@ -133,7 +133,7 @@ constructor sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. + The constructor sets the property to the last operating system socket error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. ]]> @@ -192,7 +192,7 @@ constructor sets the property to `errorCode`. + The constructor sets the property to `errorCode`. ]]> @@ -348,9 +348,9 @@ property contains the error code that is associated with the error that caused the exception. + The property contains the error code that is associated with the error that caused the exception. - The parameterless constructor for sets the property to the last operating system error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. + The parameterless constructor for sets the property to the last operating system error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. ]]> @@ -447,9 +447,9 @@ property contains the error code that is associated with the error that caused the exception. + The property contains the error code that is associated with the error that caused the exception. - The parameterless constructor for sets the property to the last operating system error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. + The parameterless constructor for sets the property to the last operating system error that occurred. For more information about socket error codes, see the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation. ]]> diff --git a/xml/System.Net.Sockets/TcpClient.xml b/xml/System.Net.Sockets/TcpClient.xml index 233b7e9e8db..02f33d3943e 100644 --- a/xml/System.Net.Sockets/TcpClient.xml +++ b/xml/System.Net.Sockets/TcpClient.xml @@ -423,7 +423,7 @@ can use this property to determine if a connection attempt has succeeded. It does not monitor the ongoing connection state of `TcpClient`. If the remote host closes the connection, `Active` will not be updated. If you are deriving from `TcpClient` and require closer attention to the connection state, use the property of the returned by the property. + Classes deriving from can use this property to determine if a connection attempt has succeeded. It does not monitor the ongoing connection state of `TcpClient`. If the remote host closes the connection, `Active` will not be updated. If you are deriving from `TcpClient` and require closer attention to the connection state, use the property of the returned by the property. ]]> @@ -871,7 +871,7 @@ The `Available` property is a way to determine whether data is queued for readin close the TCP connection. Based on the property, the TCP connection may stay open for some time after the `Close` method is called when data remains to be sent. There is no notification provided when the underlying connection has completed closing. + The `Close` method marks the instance as disposed and requests that the associated close the TCP connection. Based on the property, the TCP connection may stay open for some time after the `Close` method is called when data remains to be sent. There is no notification provided when the underlying connection has completed closing. Calling this method will eventually result in the close of the associated `Socket` and will also close the associated that is used to send and receive data if one was created. @@ -2124,7 +2124,7 @@ The `Available` property is a way to determine whether data is queued for readin ## Remarks The `GetStream` method returns a that you can use to send and receive data. The `NetworkStream` class inherits from the class, which provides a rich collection of methods and properties used to facilitate network communications. - You must call the method first, or the method will throw an . After you have obtained the `NetworkStream`, call the method to send data to the remote host. Call the method to receive data arriving from the remote host. Both of these methods block until the specified operation is performed. You can avoid blocking on a read operation by checking the property. A `true` value means that data has arrived from the remote host and is available for reading. In this case, is guaranteed to complete immediately. If the remote host has shutdown its connection, will immediately return with zero bytes. + You must call the method first, or the method will throw an . After you have obtained the `NetworkStream`, call the method to send data to the remote host. Call the method to receive data arriving from the remote host. Both of these methods block until the specified operation is performed. You can avoid blocking on a read operation by checking the property. A `true` value means that data has arrived from the remote host and is available for reading. In this case, is guaranteed to complete immediately. If the remote host has shutdown its connection, will immediately return with zero bytes. > [!NOTE] > If you receive a , use to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -2209,7 +2209,7 @@ The `GetStream` method returns a that yo To enable lingering, create a instance containing the desired values, and set the `LingerState` property to this instance. - The following table describes the behavior of the method for the possible values of the property and the property stored in the `LingerState` property. + The following table describes the behavior of the method for the possible values of the property and the property stored in the `LingerState` property. |LingerState.Enabled|LingerState.LingerTime|Behavior| |-------------------------|----------------------------|--------------| @@ -2219,7 +2219,7 @@ The `GetStream` method returns a that yo The IP stack computes the default IP protocol time-out period to use based on the round trip time of the connection. In most cases, the time-out computed by the stack is more relevant than one defined by an application. This is the default behavior for a socket when the `LingerState` property is not set. - When the property stored in the `LingerState` property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override. + When the property stored in the `LingerState` property is set greater than the default IP protocol time-out, the default IP protocol time-out will still apply and override. @@ -2347,7 +2347,7 @@ The `GetStream` method returns a that yo ## Remarks The `ReceiveBufferSize` property gets or sets the number of bytes that you are expecting to store in the receive buffer for each read operation. This property actually manipulates the network buffer space allocated for receiving incoming data. - Your network buffer should be at least as large as your application buffer to ensure that the desired data will be available when you call the method. Use the property to set this size. If your application will be receiving bulk data, you should pass the `Read` method a very large application buffer. + Your network buffer should be at least as large as your application buffer to ensure that the desired data will be available when you call the method. Use the property to set this size. If your application will be receiving bulk data, you should pass the `Read` method a very large application buffer. If the network buffer is smaller than the amount of data you request in the `Read` method, you will not be able to retrieve the desired amount of data in one read operation. This incurs the overhead of additional calls to the `Read` method. @@ -2488,7 +2488,7 @@ The `GetStream` method returns a that yo ## Remarks The `SendBufferSize` property gets or sets the number of bytes that you are expecting to send in each call to the method. This property actually manipulates the network buffer space allocated for send operation. - Your network buffer should be at least as large as your application buffer to ensure that the desired data will be stored and sent in one operation. Use the property to set this size. If your application will be sending bulk data, you should pass the `Write` method a very large application buffer. + Your network buffer should be at least as large as your application buffer to ensure that the desired data will be stored and sent in one operation. Use the property to set this size. If your application will be sending bulk data, you should pass the `Write` method a very large application buffer. If the network buffer is smaller than the amount of data you provide the `Write` method, several network send operations will be performed for every call you make to the `Write` method. You can achieve greater data throughput by ensuring that your network buffer is at least as large as your application buffer. diff --git a/xml/System.Net.Sockets/TcpListener.xml b/xml/System.Net.Sockets/TcpListener.xml index dfd767e978b..c570051e5d0 100644 --- a/xml/System.Net.Sockets/TcpListener.xml +++ b/xml/System.Net.Sockets/TcpListener.xml @@ -65,7 +65,7 @@ class provides simple methods that listen for and accept incoming connection requests in blocking synchronous mode. You can use either a or a to connect with a . Create a using an , a Local IP address and port number, or just a port number. Specify for the local IP address and 0 for the local port number if you want the underlying service provider to assign those values for you. If you choose to do this, you can use the property to identify the assigned information, after the socket has connected. + The class provides simple methods that listen for and accept incoming connection requests in blocking synchronous mode. You can use either a or a to connect with a . Create a using an , a Local IP address and port number, or just a port number. Specify for the local IP address and 0 for the local port number if you want the underlying service provider to assign those values for you. If you choose to do this, you can use the property to identify the assigned information, after the socket has connected. Use the method to begin listening for incoming connection requests. will queue incoming connections until you either call the method or it has queued . Use either or to pull a connection from the incoming connection request queue. These two methods will block. If you want to avoid blocking, you can use the method first to determine if connection requests are available in the queue. @@ -162,7 +162,7 @@ > [!NOTE] > This constructor is obsolete. Use the or constructors. - This constructor allows you to specify the port number on which to listen for incoming connection attempts. With this constructor, the underlying service provider assigns the most appropriate network address. If you do not care which local port is used, you can specify 0 for the port number. In this case, the service provider will assign an available ephemeral port number. If you use this approach, you can discover what local network address and port number has been assigned by using the property. + This constructor allows you to specify the port number on which to listen for incoming connection attempts. With this constructor, the underlying service provider assigns the most appropriate network address. If you do not care which local port is used, you can specify 0 for the port number. In this case, the service provider will assign an available ephemeral port number. If you use this approach, you can discover what local network address and port number has been assigned by using the property. Call the method to begin listening for incoming connection attempts. @@ -219,7 +219,7 @@ ## Remarks This constructor allows you to specify the local IP address and port number on which to listen for incoming connection attempts. Before using this constructor, you must create an using the desired local IP address and port number. Pass this to the constructor as the `localEP` parameter. - If you do not care which local address is assigned, you can create an using as the address parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can create an using 0 for the port number. In this case, the service provider will assign an available ephemeral port number. If you use this approach, you can discover what local network address and port number has been assigned by using the property. + If you do not care which local address is assigned, you can create an using as the address parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can create an using 0 for the port number. In this case, the service provider will assign an available ephemeral port number. If you use this approach, you can discover what local network address and port number has been assigned by using the property. Call the method to begin listening for incoming connection attempts. @@ -288,7 +288,7 @@ using the desired local address. Pass this to the constructor as the `localaddr` parameter. If you do not care which local address is assigned, specify for the `localaddr` parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can specify 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 65535. If you use this approach, you can discover what local network address and port number has been assigned by using the property. + This constructor allows you to specify the local IP address and port number on which to listen for incoming connection attempts. Before calling this constructor you must first create an using the desired local address. Pass this to the constructor as the `localaddr` parameter. If you do not care which local address is assigned, specify for the `localaddr` parameter, and the underlying service provider will assign the most appropriate network address. This might help simplify your application if you have multiple network interfaces. If you do not care which local port is used, you can specify 0 for the port number. In this case, the service provider will assign an available port number between 1024 and 65535. If you use this approach, you can discover what local network address and port number has been assigned by using the property. Call the method to begin listening for incoming connection attempts. @@ -730,7 +730,7 @@ can use this property to determine if the is currently listening for incoming connection attempts. The property can be used to avoid redundant attempts. + Classes deriving from can use this property to determine if the is currently listening for incoming connection attempts. The property can be used to avoid redundant attempts. ]]> @@ -869,10 +869,10 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). > [!NOTE] -> You can call the property of the returned to identify the remote host's network address and port number. +> You can call the property of the returned to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -945,7 +945,7 @@ For detailed information about using the asynchronous programming model, see [Calling Synchronous Methods Asynchronously](/dotnet/standard/asynchronous-programming-patterns/calling-synchronous-methods-asynchronously). > [!NOTE] -> If you receive a , use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1081,10 +1081,10 @@ This method blocks until the operation is complete. To perform this operation synchronously, use the method. > [!NOTE] -> You can call the property of the returned to identify the remote host's network address and port number. +> You can call the property of the returned to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1149,10 +1149,10 @@ This method blocks until the operation is complete. To perform this operation synchronously, use the method. > [!NOTE] -> You can call the property of the underlying socket () to identify the remote host's network address and port number. +> You can call the property of the underlying socket () to identify the remote host's network address and port number. > [!NOTE] -> If you receive a , use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1206,14 +1206,14 @@ property to prevent multiple listeners from listening to a specific port. + By default, multiple listeners can listen to a specific port. However, only one of the listeners can perform operations on the network traffic sent to the port. If more than one listener attempts to bind to a particular port, then the one with the more specific IP address handles the network traffic sent to that port. You can use the property to prevent multiple listeners from listening to a specific port. Set this property before calling , or call the method and then set this property. ## Examples - The following code example gets and sets the property. + The following code example gets and sets the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/TcpListener/BeginAcceptSocket/tcpserver.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/TcpListener/ExclusiveAddressUse/tcpserver.vb" id="Snippet2"::: @@ -1303,7 +1303,7 @@ The class finalizer free resources associa property to identify the local network interface and port number being used to listen for incoming client connection requests, after a socket connection has been made. You must first cast this to an . You can then call the property to retrieve the local IP address, and the property to retrieve the local port number. + You can use the property to identify the local network interface and port number being used to listen for incoming client connection requests, after a socket connection has been made. You must first cast this to an . You can then call the property to retrieve the local IP address, and the property to retrieve the local port number. @@ -1436,15 +1436,15 @@ The class finalizer free resources associa creates a to listen for incoming client connection requests. Classes deriving from can use this property to get this . Use the underlying returned by the property if you require access beyond that which provides. + creates a to listen for incoming client connection requests. Classes deriving from can use this property to get this . Use the underlying returned by the property if you require access beyond that which provides. > [!NOTE] -> The property only returns the used to listen for incoming client connection requests. Use the method to accept a pending connection request and obtain a for sending and receiving data. You can also use the method to accept a pending connection request and obtain a for sending and receiving data. +> The property only returns the used to listen for incoming client connection requests. Use the method to accept a pending connection request and obtain a for sending and receiving data. You can also use the method to accept a pending connection request and obtain a for sending and receiving data. ## Examples - The following code example demonstrates the use of the property. The underlying is retrieved and the option is configured to time out after 10 seconds if data still remains in the network buffer after the connection is closed. + The following code example demonstrates the use of the property. The underlying is retrieved and the option is configured to time out after 10 seconds if data still remains in the network buffer after the connection is closed. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/TcpListener/Server/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/TcpListener/Server/source.vb" id="Snippet1"::: @@ -1595,7 +1595,7 @@ The class finalizer free resources associa Use the method to close the and stop listening. You are responsible for closing your accepted connections separately. > [!NOTE] -> Use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> Use the property to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). diff --git a/xml/System.Net.Sockets/UdpAnySourceMulticastClient.xml b/xml/System.Net.Sockets/UdpAnySourceMulticastClient.xml index 38a16bc99ba..def45065849 100644 --- a/xml/System.Net.Sockets/UdpAnySourceMulticastClient.xml +++ b/xml/System.Net.Sockets/UdpAnySourceMulticastClient.xml @@ -63,15 +63,15 @@ The local port for this receiver to bind to. Creates a new UDP client that can subscribe to a group address and receive datagrams from any source. - constructor associates a UDP multicast socket with a group address and port, but does not bind or otherwise use the socket. - - The `groupAddress` parameter may be either an IPv6 or IPv4 multicast address. - - The `localPort` parameter must not specify a port less than 1,024. - + constructor associates a UDP multicast socket with a group address and port, but does not bind or otherwise use the socket. + + The `groupAddress` parameter may be either an IPv6 or IPv4 multicast address. + + The `localPort` parameter must not specify a port less than 1,024. + ]]> @@ -115,15 +115,15 @@ Binds the socket and begins a join operation to the multicast group to allow datagrams to be received from any group participant. An that references this operation. - method binds a UDP multicast socket to a local port and joins a multicast group to allow datagrams to be received from any multicast group participant. The local port and multicast group address are specified in the constructor. - - The method specified in the `callback` parameter is invoked when the operation to join the multicast group has completed. - - If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . - + method binds a UDP multicast socket to a local port and joins a multicast group to allow datagrams to be received from any multicast group participant. The local port and multicast group address are specified in the constructor. + + The method specified in the `callback` parameter is invoked when the operation to join the multicast group has completed. + + If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . + ]]> The multicast group has already been joined or a join operation is currently in progress. @@ -172,32 +172,32 @@ Begins the operation of receiving a packet from the joined multicast group and invokes the specified callback when a packet has arrived on the group from any sender. An that references this operation. - method begins an operation of receiving a UDP packet from the joined multicast group from any sender. The local port and multicast group address are specified in the constructor. The multicast client must also have completed a join to the multicast group. - - The method specified in the `callback` parameter is invoked when a packet has received. - - It is possible to have a socket failure if a receive operation fails synchronously, although this is uncommon with UDP. If a socket failure occurs, a is thrown. The error received is specified as a member of the enumeration. - + method begins an operation of receiving a UDP packet from the joined multicast group from any sender. The local port and multicast group address are specified in the constructor. The multicast client must also have completed a join to the multicast group. + + The method specified in the `callback` parameter is invoked when a packet has received. + + It is possible to have a socket failure if a receive operation fails synchronously, although this is uncommon with UDP. If a socket failure occurs, a is thrown. The error received is specified as a member of the enumeration. + ]]> is a null reference (Nothing in Visual Basic). - is less than 0 - - -or- - - is greater than the length of the . - - -or- - - is less than 0 - - -or- - + is less than 0 + + -or- + + is greater than the length of the . + + -or- + + is less than 0 + + -or- + plus the count is greater than the length of the . The multicast group has not yet been joined. The has been disposed. @@ -247,38 +247,38 @@ Begins the operation of sending a unicast packet to the specified destination. An that references this operation. - method begins an operation of sending a UDP packet to the joined multicast group. - - The client must have completed a join to the multicast group. The destination address specified in the `remoteEndPoint` parameter must have already sent a multicast packet to this receiver. Some protocols use this information to pass along flow control, quality of service statistics, or recovery messages. - - The method specified in the `callback` parameter is invoked when a packet has received. - - The transmission is only allowed if the address specified in the `remoteEndPoint` parameter has already sent a multicast packet to this receiver. If the client is not allowed access, a is thrown with . - - If the destination port specified in the `remoteEndPoint` parameter is less than 1,024, a is thrown with . - - It is possible to have a socket failure if a receive operation fails synchronously, although this is uncommon with UDP. If a socket failure occurs, a is thrown. The error received is specified as a member of the enumeration. - + method begins an operation of sending a UDP packet to the joined multicast group. + + The client must have completed a join to the multicast group. The destination address specified in the `remoteEndPoint` parameter must have already sent a multicast packet to this receiver. Some protocols use this information to pass along flow control, quality of service statistics, or recovery messages. + + The method specified in the `callback` parameter is invoked when a packet has received. + + The transmission is only allowed if the address specified in the `remoteEndPoint` parameter has already sent a multicast packet to this receiver. If the client is not allowed access, a is thrown with . + + If the destination port specified in the `remoteEndPoint` parameter is less than 1,024, a is thrown with . + + It is possible to have a socket failure if a receive operation fails synchronously, although this is uncommon with UDP. If a socket failure occurs, a is thrown. The error received is specified as a member of the enumeration. + ]]> is a null reference (Nothing in Visual Basic). - is less than 0 - - -or- - - is greater than the length of the . - - -or- - - is less than 0 - - -or- - + is less than 0 + + -or- + + is greater than the length of the . + + -or- + + is less than 0 + + -or- + plus the count is greater than the length of the . The multicast group has not yet been joined. The has been disposed. @@ -326,34 +326,34 @@ Begins the operation of sending a packet to a joined multicast group and invokes the specified callback when a packet has been sent to the group. An that references this operation. - method begins an operation of sending a UDP packet to the joined multicast group. - - The client must have completed a join to the multicast group. - - The method specified in the `callback` parameter is invoked when a packet has received. - - It is possible to have a socket failure if a receive operation fails synchronously, although this is uncommon with UDP. If a socket failure occurs, a is thrown. The error received is specified as a member of the enumeration. - + method begins an operation of sending a UDP packet to the joined multicast group. + + The client must have completed a join to the multicast group. + + The method specified in the `callback` parameter is invoked when a packet has received. + + It is possible to have a socket failure if a receive operation fails synchronously, although this is uncommon with UDP. If a socket failure occurs, a is thrown. The error received is specified as a member of the enumeration. + ]]> is a null reference (Nothing in Visual Basic). - is less than 0 - - -or- - - is greater than the length of the . - - -or- - - is less than 0 - - -or- - + is less than 0 + + -or- + + is greater than the length of the . + + -or- + + is less than 0 + + -or- + plus the count is greater than the length of the . The multicast group has not yet been joined. The has been disposed. @@ -392,17 +392,17 @@ The address of the source to block. Blocks a source so that multicast packets originating from it are no longer received. - method blocks multicast packets originating from a specified source address from being received. The client must have completed a join to the multicast group. - - The `sourceAddress` parameter may be either an IPv6 or IPv4 address, but the `sourceAddress` parameter must match the address family of the multicast group that the client joined. - - The method specified in the `callback` parameter is invoked when a packet has received. - - If there is a socket failure while performing the block source operation, a is thrown. The error received is specified as a member of the enumeration. - + method blocks multicast packets originating from a specified source address from being received. The client must have completed a join to the multicast group. + + The `sourceAddress` parameter may be either an IPv6 or IPv4 address, but the `sourceAddress` parameter must match the address family of the multicast group that the client joined. + + The method specified in the `callback` parameter is invoked when a packet has received. + + If there is a socket failure while performing the block source operation, a is thrown. The error received is specified as a member of the enumeration. + ]]> The multicast group has not yet been joined. @@ -442,13 +442,13 @@ Leaves the multicast group and releases all resources used by the current instance of the class and the underlying the . - when you are finished using the . The Dispose method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - - Always call 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 method. - + when you are finished using the . The Dispose method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + + Always call 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 method. + ]]> @@ -485,15 +485,15 @@ The result of the asynchronous join operation. Completes the asynchronous join group operation to a multicast group. - method completes an asynchronous bind to a socket and join operation to a multicast group. - - If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . - - If there is a socket failure while performing the join group operation, a is thrown. The error received is specified as a member of the enumeration. - + method completes an asynchronous bind to a socket and join operation to a multicast group. + + If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . + + If there is a socket failure while performing the join group operation, a is thrown. The error received is specified as a member of the enumeration. + ]]> @@ -537,13 +537,13 @@ Completes the asynchronous operation of receiving a packet from the joined multicast group and provides the information received. The length, in bytes, of the message stored in the buffer parameter passed to the method. - method completes an asynchronous operation to receive a packet from a multicast group. - - If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. - + method completes an asynchronous operation to receive a packet from a multicast group. + + If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. + ]]> @@ -585,13 +585,13 @@ The result of the asynchronous send operation. Completes the operation of sending a unicast packet to the specified destination. - method completes an asynchronous operation to send a packet to specified destination address. - - If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. - + method completes an asynchronous operation to send a packet to specified destination address. + + If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. + ]]> @@ -633,13 +633,13 @@ The result of the asynchronous send operation. Completes the operation of sending a packet to a multicast group. - method completes an asynchronous operation to send a packet to a multicast group. - - If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. - + method completes an asynchronous operation to send a packet to a multicast group. + + If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. + ]]> @@ -676,15 +676,15 @@ Gets or sets a value that specifies whether outgoing multicast packets are delivered to the sending application. - Returns . - + Returns . + A value that indicates if outgoing packets to a multicast group are delivered to the sending application. - property controls whether any process on the local computer receives multicast packets sent by this client to the multicast group. - + property controls whether any process on the local computer receives multicast packets sent by this client to the multicast group. + ]]> The multicast group has not yet been joined. @@ -718,17 +718,17 @@ Gets or sets the size, in bytes, of the receive buffer of the used for multicast receive operations on this instance. - Returns . - + Returns . + The size, in bytes, of the receive buffer. - property gets or sets the size, in bytes, of the receive buffer of the underlying used for multicast receive operations on this instance. Specifically, the property controls the size of the buffer used by the stack when a packet arrives, but the application has not yet called the method. If this buffer gets filled up and packets keep coming before the application calls the and methods, old packets will get dropped. The application will never be able to receive the old packets, and will instead receive newer packets when it calls the method. - - The default size of the receive buffer on Windows is 8,192 bytes. - + property gets or sets the size, in bytes, of the receive buffer of the underlying used for multicast receive operations on this instance. Specifically, the property controls the size of the buffer used by the stack when a packet arrives, but the application has not yet called the method. If this buffer gets filled up and packets keep coming before the application calls the and methods, old packets will get dropped. The application will never be able to receive the old packets, and will instead receive newer packets when it calls the method. + + The default size of the receive buffer on Windows is 8,192 bytes. + ]]> The buffer size specified is less than 0. @@ -763,19 +763,19 @@ Gets or sets the size, in bytes, of the send buffer of the used for multicast send operations on this instance. - Returns . - + Returns . + The size, in bytes, of the send buffer. - property gets or sets the size, in bytes, of the send buffer of the underlying Socket used for multicast send operations on this instance. - - calls to the or methods will take longer to call the callback depending on the value of the property if the send buffer is full. The property only controls whether the user's buffer stays locked in physical memory until the send completes. - - The default size of the send buffer on Windows is 8,192 bytes. - + property gets or sets the size, in bytes, of the send buffer of the underlying Socket used for multicast send operations on this instance. + + calls to the or methods will take longer to call the callback depending on the value of the property if the send buffer is full. The property only controls whether the user's buffer stays locked in physical memory until the send completes. + + The default size of the send buffer on Windows is 8,192 bytes. + ]]> The buffer size specified is less than 0. @@ -815,19 +815,19 @@ The address of the source to unblock. Unblocks a source that was previously blocked by a call to the method so that multicast packets originating from it can be received. - method unblocks multicast packets originating from a specified source address so they can be received. The specified source address must have previously been blocked by a call to the method. - - The client must have completed a join to the multicast group. - - The `sourceAddress` parameter may be either an IPv6 or IPv4 multicast address. - - If the specified source address in the `sourceAddress` parameter was not previously blocked by a call to the method, a is thrown with . - - If there is a socket failure while performing the unblock source operation, a is thrown. The error received is specified as a member of the enumeration. - + method unblocks multicast packets originating from a specified source address so they can be received. The specified source address must have previously been blocked by a call to the method. + + The client must have completed a join to the multicast group. + + The `sourceAddress` parameter may be either an IPv6 or IPv4 multicast address. + + If the specified source address in the `sourceAddress` parameter was not previously blocked by a call to the method, a is thrown with . + + If there is a socket failure while performing the unblock source operation, a is thrown. The error received is specified as a member of the enumeration. + ]]> The multicast group has not yet been joined. diff --git a/xml/System.Net.Sockets/UdpClient.xml b/xml/System.Net.Sockets/UdpClient.xml index f79db89e3fe..259fdad80bd 100644 --- a/xml/System.Net.Sockets/UdpClient.xml +++ b/xml/System.Net.Sockets/UdpClient.xml @@ -676,9 +676,9 @@ property is used to determine the amount of data queued in the network buffer for reading. If data is available, call to get the data. If no data is available, the property returns 0. + The property is used to determine the amount of data queued in the network buffer for reading. If data is available, call to get the data. If no data is available, the property returns 0. - If the remote host shuts down or closes the connection, the property throws a . + If the remote host shuts down or closes the connection, the property throws a . > [!NOTE] > If you receive a , use to obtain the specific error code and refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -686,7 +686,7 @@ ## Examples - The following code example shows the use of the property. + The following code example shows the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet1"::: @@ -1108,7 +1108,7 @@ ## Examples - The following example demonstrates the use of the property. In this example, broadcasting is enabled for the underlying . + The following example demonstrates the use of the property. In this example, broadcasting is enabled for the underlying . :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Client/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net.Sockets/UdpClient/Client/source.vb" id="Snippet1"::: @@ -1587,7 +1587,7 @@ ## Examples - The following code example shows the use of the property. + The following code example shows the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet2"::: @@ -1728,7 +1728,7 @@ The method withdraws the from the multicast group identified by the specified . After calling the method, the underlying sends an Internet Group Management Protocol (IGMP) packet to the router, removing the router from the multicast group. After a withdraws from the group, it will no longer be able to receive datagrams sent to that group. > [!NOTE] -> If you receive a , use the property to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. +> If you receive a , use the property to obtain the specific error code. After you have obtained this code, you can refer to the [Windows Sockets version 2 API error code](/windows/desktop/winsock/windows-sockets-error-codes-2) documentation for a detailed description of the error. @@ -1797,7 +1797,7 @@ ## Examples - The following code example shows the use of the property. + The following code example shows the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet3"::: @@ -1997,14 +1997,14 @@ property to prevent multiple clients from using a specific port. + By default, multiple clients can use a specific port; however, only one of the clients can perform operations on the network traffic sent to the port. You can use the property to prevent multiple clients from using a specific port. - This property must be set before the underlying socket is bound to a client port. If you call , , , or , the client port is bound as a side effect of the constructor, and you cannot subsequently set the property + This property must be set before the underlying socket is bound to a client port. If you call , , , or , the client port is bound as a side effect of the constructor, and you cannot subsequently set the property ## Examples - The following code example creates a , and gets and sets the property. + The following code example creates a , and gets and sets the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet4"::: @@ -2371,7 +2371,7 @@ ## Examples - The following code example shows the use of the property. + The following code example shows the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet7"::: @@ -2782,7 +2782,7 @@ method sends datagrams to the specified endpoint and returns the number of bytes successfully sent. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to the method as the `endPoint` parameter. + The method sends datagrams to the specified endpoint and returns the number of bytes successfully sent. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to the method as the `endPoint` parameter. If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. @@ -3114,7 +3114,7 @@ using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to this method as the `endPoint` parameter. + This method sends datagrams to the specified endpoint. Before calling this overload, you must first create an using the IP address and port number of the remote host to which your datagrams will be delivered. You can send datagrams to the default broadcast address, 255.255.255.255, by specifying for the property of the . After you have created this , pass it to this method as the `endPoint` parameter. If you want to send datagrams to any other broadcast address, use the method to obtain the underlying , and set the socket option to . You can also revert to using the class. @@ -3406,7 +3406,7 @@ Call IDisposable.Dispose when you are finished using the property. + The following code example shows the use of the property. :::code language="csharp" source="~/snippets/csharp/System.Net.Sockets/UdpClient/Available/newudpclient.cs" id="Snippet5"::: diff --git a/xml/System.Net.Sockets/UdpSingleSourceMulticastClient.xml b/xml/System.Net.Sockets/UdpSingleSourceMulticastClient.xml index 2bebd33e1f8..0f0873ef581 100644 --- a/xml/System.Net.Sockets/UdpSingleSourceMulticastClient.xml +++ b/xml/System.Net.Sockets/UdpSingleSourceMulticastClient.xml @@ -30,15 +30,15 @@ A client receiver for multicast traffic from a single source, also known as Source Specific Multicast (SSM). - client can also send unicast data back to the sender. - - To receive multicast from multiple sources, or when the sources aren't known in advance, use the class instead. - + client can also send unicast data back to the sender. + + To receive multicast from multiple sources, or when the sources aren't known in advance, use the class instead. + ]]> @@ -76,30 +76,30 @@ The local port for this receiver to bind to. Creates a new UDP client that can subscribe to a group address and receive datagrams from a single source. - constructor associates a UDP multicast socket with a group address and port, but does not bind or otherwise use the socket. - - The `groupAddress` parameter may be either an IPv6 or IPv4 multicast address. However, the address family of the `sourceAddress` and `groupAddress` parameters must the same. - - The `localPort` parameter must not specify a port less than 1,024. - + constructor associates a UDP multicast socket with a group address and port, but does not bind or otherwise use the socket. + + The `groupAddress` parameter may be either an IPv6 or IPv4 multicast address. However, the address family of the `sourceAddress` and `groupAddress` parameters must the same. + + The `localPort` parameter must not specify a port less than 1,024. + ]]> and must be the same address family. - is a null reference (Nothing in Visual Basic). - - -or- - + is a null reference (Nothing in Visual Basic). + + -or- + is a null reference (Nothing in Visual Basic). - is less than 0 - - -or- - + is less than 0 + + -or- + is greater than 65,535. is less than 1024 @@ -140,15 +140,15 @@ Binds the socket and begins a join operation to the multicast group to allow datagrams to be received from a single source address. An that references this operation. - method binds a UDP multicast socket to a local port and joins a multicast group to allow datagrams to be received from a single source address. The multicast group address, single source address, and local port to bind to are specified in the constructor. - - The method specified in the `callback` parameter is invoked when the operation to join the multicast group has completed. - - If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . - + method binds a UDP multicast socket to a local port and joins a multicast group to allow datagrams to be received from a single source address. The multicast group address, single source address, and local port to bind to are specified in the constructor. + + The method specified in the `callback` parameter is invoked when the operation to join the multicast group has completed. + + If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . + ]]> The multicast group has already been joined or a join operation is currently in progress. @@ -197,32 +197,32 @@ Begins the operation of receiving a packet from the joined multicast group and invokes the specified callback when a packet has arrived on the group from a specified sender. An that references this operation. - method begins an operation of receiving a UDP packet from the joined multicast group from a single sender. The local port, multicast group, and sender source address are specified in the constructor. The multicast client must also have completed a join to the multicast group. - - The method specified in the `callback` parameter is invoked when a packet has received. - - It is possible to have a socket failure if a receive operation fails synchronously, although this is uncommon with UDP. If a socket failure occurs, a is thrown. The error received is specified as a member of the enumeration. - + method begins an operation of receiving a UDP packet from the joined multicast group from a single sender. The local port, multicast group, and sender source address are specified in the constructor. The multicast client must also have completed a join to the multicast group. + + The method specified in the `callback` parameter is invoked when a packet has received. + + It is possible to have a socket failure if a receive operation fails synchronously, although this is uncommon with UDP. If a socket failure occurs, a is thrown. The error received is specified as a member of the enumeration. + ]]> is a null reference (Nothing in Visual Basic). - is less than 0 - - -or- - - is greater than the length of the . - - -or- - - is less than 0 - - -or- - + is less than 0 + + -or- + + is greater than the length of the . + + -or- + + is less than 0 + + -or- + plus the count is greater than the length of the . The multicast group has not yet been joined. The has been disposed. @@ -272,42 +272,42 @@ Begins the operation of sending a unicast packet to the source previously specified. An that references this operation. - method begins an operation of sending a UDP packet to the source previously specified. - - Some protocols use this information to pass along flow control, quality of service statistics, or recovery messages. - - The method specified in the `callback` parameter is invoked when a packet has been sent. - - The client must have completed a join to the multicast group. - - If the destination port specified in the `remotePort` parameter is less than 1,024, a is thrown with . - - It is possible to have a socket failure if a send operation fails synchronously, although this is uncommon with UDP. If a socket failure occurs, a is thrown. The error received is specified as a member of the enumeration. - + method begins an operation of sending a UDP packet to the source previously specified. + + Some protocols use this information to pass along flow control, quality of service statistics, or recovery messages. + + The method specified in the `callback` parameter is invoked when a packet has been sent. + + The client must have completed a join to the multicast group. + + If the destination port specified in the `remotePort` parameter is less than 1,024, a is thrown with . + + It is possible to have a socket failure if a send operation fails synchronously, although this is uncommon with UDP. If a socket failure occurs, a is thrown. The error received is specified as a member of the enumeration. + ]]> is a null reference (Nothing in Visual Basic). - is less than 0 - - -or- - - is greater than the length of the . - - -or- - - is less than 0 - - -or- - - plus the count is greater than the length of the . - - -or- - + is less than 0 + + -or- + + is greater than the length of the . + + -or- + + is less than 0 + + -or- + + plus the count is greater than the length of the . + + -or- + is less than 0 or greater than 65,535. The multicast group has not yet been joined. The has been disposed. @@ -346,13 +346,13 @@ Leaves the multicast group and releases all resources used by the current instance of the class and the underlying the . - when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - - Always call 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 method. - + when you are finished using the . The method leaves the in an unusable state. After calling , you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + + Always call 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 method. + ]]> @@ -389,15 +389,15 @@ The result of the asynchronous join operation. Completes the asynchronous join group operation to a multicast group. - method completes an asynchronous bind to a socket and join operation to a multicast group. - - If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . - - If there is a socket failure while performing the join group operation, a is thrown. The error received is specified as a member of the enumeration. - + method completes an asynchronous bind to a socket and join operation to a multicast group. + + If required by the runtime, the method also performs a policy check to verify that the client is allowed to access the multicast group. If the client is not allowed access, a is thrown with . + + If there is a socket failure while performing the join group operation, a is thrown. The error received is specified as a member of the enumeration. + ]]> @@ -441,13 +441,13 @@ Completes the asynchronous operation of receiving a packet from the joined multicast group and provides the information received. The length, in bytes, of the message stored in the parameter passed to the method. - method completes an asynchronous operation to receive a packet from a single source in a multicast group. - - If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. - + method completes an asynchronous operation to receive a packet from a single source in a multicast group. + + If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. + ]]> @@ -489,13 +489,13 @@ The result of the asynchronous send operation. Completes the operation of sending a unicast packet to a single source. - method completes an asynchronous operation to send a packet to single source previously specified. - - If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. - + method completes an asynchronous operation to send a packet to single source previously specified. + + If there is a socket failure while performing the receive operation, a is thrown. The error received is specified as a member of the enumeration. + ]]> @@ -532,17 +532,17 @@ Gets or sets the size, in bytes, of the receive buffer of the used for multicast receive operations on this instance. - Returns . - + Returns . + The size, in bytes, of the receive buffer. - used for multicast receive operations on this instance. Specifically, the `ReceiveBufferSize` property controls the size of the buffer used by the stack when a packet arrives, but the application has not yet called the method. If this buffer gets filled up and packets keep coming before the application calls the and methods, old packets will get dropped. The application will never be able to receive the old packets, and will instead receive newer packets when it calls the method. - - The default size of the receive buffer on Windows is 8,192. - + used for multicast receive operations on this instance. Specifically, the `ReceiveBufferSize` property controls the size of the buffer used by the stack when a packet arrives, but the application has not yet called the method. If this buffer gets filled up and packets keep coming before the application calls the and methods, old packets will get dropped. The application will never be able to receive the old packets, and will instead receive newer packets when it calls the method. + + The default size of the receive buffer on Windows is 8,192. + ]]> The buffer size specified is less than 0. @@ -577,21 +577,21 @@ Gets or sets the size, in bytes, of the send buffer of the used for multicast send operations on this instance. - Returns . - + Returns . + The size, in bytes, of the send buffer. - used for multicast send operations on this instance. - - On Mac OS X, the property controls how many bytes can be in the network stack's waiting-to-be-sent buffer before additional calls to the method start failing. Applications on Mac OS X may need to be concerned with this property if they are sending a large number of UDP packets in a short timeframe. - - On Windows, calls to the method will take longer to call the callback depending on the value of the property if the send buffer is full. The property only controls whether the user's buffer stays locked in physical memory until the send completes. - - The default size of the send buffer on Windows is 8,192. - + used for multicast send operations on this instance. + + On Mac OS X, the property controls how many bytes can be in the network stack's waiting-to-be-sent buffer before additional calls to the method start failing. Applications on Mac OS X may need to be concerned with this property if they are sending a large number of UDP packets in a short timeframe. + + On Windows, calls to the method will take longer to call the callback depending on the value of the property if the send buffer is full. The property only controls whether the user's buffer stays locked in physical memory until the send completes. + + The default size of the send buffer on Windows is 8,192. + ]]> The buffer size specified is less than 0. diff --git a/xml/System.Net.WebSockets/WebSocketReceiveResult.xml b/xml/System.Net.WebSockets/WebSocketReceiveResult.xml index 2478a31dd00..63020c0d1f4 100644 --- a/xml/System.Net.WebSockets/WebSocketReceiveResult.xml +++ b/xml/System.Net.WebSockets/WebSocketReceiveResult.xml @@ -280,15 +280,15 @@ Indicates the number of bytes that the WebSocket received. Returns . - property is None. - -2. The WebSocket received a close message from the remote endpoint. In this case, the property is set to a value other than None. - + property is None. + +2. The WebSocket received a close message from the remote endpoint. In this case, the property is set to a value other than None. + ]]> diff --git a/xml/System.Net/AuthenticationManager.xml b/xml/System.Net/AuthenticationManager.xml index 5740702aa8c..67aea2e5332 100644 --- a/xml/System.Net/AuthenticationManager.xml +++ b/xml/System.Net/AuthenticationManager.xml @@ -65,7 +65,7 @@ Modules that provide the basic, digest, negotiate, NTLM, and Kerberos authentication types are registered with the by default. Additional authentication modules that implement the interface can be added using the method. Authentication modules are called in the order in which they were added to the list. -## Examples +## Examples :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationManager/Overview/custombasicauthentication.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationManager/Overview/custombasicauthentication.vb" id="Snippet1"::: @@ -287,7 +287,7 @@ > [!NOTE] > When Kerberos authentication is performed through a proxy, both the proxy and the ultimate host name need to be resolved to an SPN. The proxy name resolution is protected by a timeout. Resolution of the ultimate host name to a SPN requires a DNS lookup, and there is no timeout associated directly with this operation. Therefore synchronous operations may take longer to timeout. To overcome this, add the ultimate host's URI prefix to the SPN cache prior to making requests to it. - Version 3.5 SP1 now defaults to specifying the host name used in the request URL in the SPN in the NTLM (NT LAN Manager) authentication exchange when the property is not set. The host name used in the request URL may be different from the Host header specified in the in the client request. The host name used in the request URL may be different from the actual host name of the server, the machine name of the server, the computer's IP address, or the loopback address. In these cases, Windows will fail the authentication request. To address the issue, you may need to notify Windows that the host name used in the request URL in the client request ("contoso", for example) is actually an alternate name for the local computer. + Version 3.5 SP1 now defaults to specifying the host name used in the request URL in the SPN in the NTLM (NT LAN Manager) authentication exchange when the property is not set. The host name used in the request URL may be different from the Host header specified in the in the client request. The host name used in the request URL may be different from the actual host name of the server, the machine name of the server, the computer's IP address, or the loopback address. In these cases, Windows will fail the authentication request. To address the issue, you may need to notify Windows that the host name used in the request URL in the client request ("contoso", for example) is actually an alternate name for the local computer. @@ -365,7 +365,7 @@ ## Remarks If the authentication module can preauthenticate the request, the method returns an Authentication instance and sends the authorization information to the server preemptively instead of waiting for the resource to issue a challenge. This behavior is outlined in section 3.3 of RFC 2617 (HTTP Authentication: Basic and Digest Access Authentication). Authentication modules that support preauthentication allow clients to improve server efficiency by avoiding extra round trips caused by authentication challenges. - Authorization modules that can preauthenticate requests set the property to `true`. + Authorization modules that can preauthenticate requests set the property to `true`. ]]> @@ -479,12 +479,12 @@ property provides an instance that enables the list of registered authentication modules to be read. The method adds modules to the list, and the method removes modules from it. + The property provides an instance that enables the list of registered authentication modules to be read. The method adds modules to the list, and the method removes modules from it. ## Examples - The following example uses the property to get a list of authentication modules that are registered with the authentication manager. For a complete example, refer to the class. + The following example uses the property to get a list of authentication modules that are registered with the authentication manager. For a complete example, refer to the class. :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationManager/Overview/custombasicauthentication.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationManager/Overview/custombasicauthentication.vb" id="Snippet8"::: diff --git a/xml/System.Net/AuthenticationSchemeSelector.xml b/xml/System.Net/AuthenticationSchemeSelector.xml index 0b0c870099a..b6f70f07201 100644 --- a/xml/System.Net/AuthenticationSchemeSelector.xml +++ b/xml/System.Net/AuthenticationSchemeSelector.xml @@ -52,26 +52,26 @@ Selects the authentication scheme for an instance. One of the values that indicates the method of authentication to use for the specified client request. - instances to select an authentication scheme based on the characteristics of a request. - - An delegate is passed an object for each incoming request that has not provided authentication information. The method invoked by the delegate uses the object and any other available information to decide which authentication scheme to require. The delegate is specified by using the property. - - - -## Examples - The following example uses an instance of this type to set the property. - + instances to select an authentication scheme based on the characteristics of a request. + + An delegate is passed an object for each incoming request that has not provided authentication information. The method invoked by the delegate uses the object and any other available information to decide which authentication scheme to require. The delegate is specified by using the property. + + + +## Examples + The following example uses an instance of this type to set the property. + :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationSchemes/Overview/sample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationSchemes/Overview/sample.vb" id="Snippet2"::: - - The following example shows the implementation of the method invoked by the delegate in the previous example. - + :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationSchemes/Overview/sample.vb" id="Snippet2"::: + + The following example shows the implementation of the method invoked by the delegate in the previous example. + :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationSchemes/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationSchemes/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationSchemes/Overview/sample.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Net/BindIPEndPoint.xml b/xml/System.Net/BindIPEndPoint.xml index 2f13fad2bac..439d16d7365 100644 --- a/xml/System.Net/BindIPEndPoint.xml +++ b/xml/System.Net/BindIPEndPoint.xml @@ -62,15 +62,15 @@ Represents the method that specifies a local Internet Protocol address and port number for a . The local to which the is bound. - delegate is used by a by setting the property with the delegate as an argument. This delegate should specify a local IP address and port number in the returned . - - If the .NET Framework cannot bind the returned to the after attempts, an is thrown. - - If you want the delegate to give the service point control of the connection binding, the delegate should return `null`. If you want to abort the connection, the delegate must throw an exception. - + delegate is used by a by setting the property with the delegate as an argument. This delegate should specify a local IP address and port number in the returned . + + If the .NET Framework cannot bind the returned to the after attempts, an is thrown. + + If you want the delegate to give the service point control of the connection binding, the delegate should return `null`. If you want to abort the connection, the delegate must throw an exception. + ]]> diff --git a/xml/System.Net/Cookie.xml b/xml/System.Net/Cookie.xml index 1e642b6a33e..24be2ca285f 100644 --- a/xml/System.Net/Cookie.xml +++ b/xml/System.Net/Cookie.xml @@ -145,7 +145,7 @@ property must be initialized before using an instance of the class. + The parameterless constructor initializes all fields to their default values, using empty strings ("") for `name`, `value`, `path`, and `domain`. Note that at least the property must be initialized before using an instance of the class. ]]> @@ -1149,7 +1149,7 @@ property must be initialized before using an instance of the class. + The property must be initialized before using an instance of the class. The following characters are reserved and cannot be used for this attribute value: equal sign, semicolon, comma, new line (\n), return (\r), tab (\t), and space character. The dollar sign ($) character cannot be the first character. @@ -1226,7 +1226,7 @@ property specifies the subset of URIs on the origin server to which this applies. If this property is not specified, then this will be sent to all pages on the origin server or servers. + The property specifies the subset of URIs on the origin server to which this applies. If this property is not specified, then this will be sent to all pages on the origin server or servers. @@ -1658,9 +1658,9 @@ property is 0, complying with the original Netscape specification. If the value is explicitly set to 1, then this must conform to RFC 2109. Note that if a was created automatically by receiving a Set-Cookie2 HTTP response header, the conformance is set to RFC 2965. + The default value for the property is 0, complying with the original Netscape specification. If the value is explicitly set to 1, then this must conform to RFC 2109. Note that if a was created automatically by receiving a Set-Cookie2 HTTP response header, the conformance is set to RFC 2965. - An attempt to set the property to a value less than zero will throw an exception. + An attempt to set the property to a value less than zero will throw an exception. diff --git a/xml/System.Net/CookieCollection.xml b/xml/System.Net/CookieCollection.xml index 4da4183ba63..e95f9c6cfa6 100644 --- a/xml/System.Net/CookieCollection.xml +++ b/xml/System.Net/CookieCollection.xml @@ -1040,7 +1040,7 @@ The comparison for is case-sensitive. property returns an object that can be used to synchronize access to the . + The property returns an object that can be used to synchronize access to the . ]]> @@ -1238,7 +1238,7 @@ This member is an explicit interface member implementation. It can be used only property returns an object that can be used to synchronize access to the . + The property returns an object that can be used to synchronize access to the . ]]> diff --git a/xml/System.Net/CookieContainer.xml b/xml/System.Net/CookieContainer.xml index 1c81f5559a0..d15875deb32 100644 --- a/xml/System.Net/CookieContainer.xml +++ b/xml/System.Net/CookieContainer.xml @@ -80,7 +80,7 @@ The has three properties that govern the volume of the content of the container: , , and . These values have the default settings of 300, 4096, and 20 respectively. When a is added to the container, these properties are used to determine whether a already contained in the should be discarded to make room for the new one. The keeps track of each addition to ensure that neither the nor the limits are exceeded. If one or both are exceeded, then instances held by the are removed. First, any expired is removed. If further capacity must be recaptured, then the least-recently used is purged. ## Thread Safety - + The methods for adding and retrieving instances to and from a are thread-safe and can be used concurrently from multiple threads. > [!NOTE] @@ -348,7 +348,7 @@ property equals or exceeds the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in the given scope, they are cleaned up. If not, then the least recently used is found and removed from the container. + If the property equals or exceeds the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in the given scope, they are cleaned up. If not, then the least recently used is found and removed from the container. ]]> @@ -416,7 +416,7 @@ property equals the property, one or more instances are removed from the container before adding the contents of the `cookies` parameter. Enough instances are removed to make room for `cookies` as follows: if there are expired instances, they are cleaned up. If not, or if more room is needed, then the least recently used is found and removed from the container. + If the property equals the property, one or more instances are removed from the container before adding the contents of the `cookies` parameter. Enough instances are removed to make room for `cookies` as follows: if there are expired instances, they are cleaned up. If not, or if more room is needed, then the least recently used is found and removed from the container. ]]> @@ -482,13 +482,13 @@ instance for just one specific host, do not set the property of the instance. This is set automatically, based on the URI. + If you add a instance for just one specific host, do not set the property of the instance. This is set automatically, based on the URI. If your URI corresponds to your local domain and sends to all the hosts on the local domain, set the property equal to ".local". Otherwise, make sure it matches the host name used in the URI. - If the property of a is Netscape, the property of the , if not set explicitly, is derived from the URI and is the complete path from the URI, including the page name. + If the property of a is Netscape, the property of the , if not set explicitly, is derived from the URI and is the complete path from the URI, including the page name. - If the property equals the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. + If the property equals the property, one or more instances are removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope, they are cleaned up. If not, then the least recently used is found and removed from the container. ]]> @@ -560,9 +560,9 @@ instance for just one specific host, do not set the property of the instance. This is set automatically, based on the URI. + If you add a instance for just one specific host, do not set the property of the instance. This is set automatically, based on the URI. - If your URI corresponds to your local domain and sends to all the hosts on the local domain, set the property equal to ".local". Otherwise, make sure it matches the host name used in the URI. + If your URI corresponds to your local domain and sends to all the hosts on the local domain, set the property equal to ".local". Otherwise, make sure it matches the host name used in the URI. If equals , one or more instances is removed from the container before adding the `cookie` parameter. Enough instances are removed to bring below as follows: if there are expired instances in scope they are cleaned up. If not, then the least recently used is found and removed from the container. @@ -1190,7 +1190,7 @@ value is less than the current value, and if any of the domain collections contain more instances than the new value, the collections are pruned to fit. This uses the same basic rules as described in the property. However, this does the cleanup only on the collection for this domain. + If the new value is less than the current value, and if any of the domain collections contain more instances than the new value, the collections are pruned to fit. This uses the same basic rules as described in the property. However, this does the cleanup only on the collection for this domain. ]]> diff --git a/xml/System.Net/CookieException.xml b/xml/System.Net/CookieException.xml index 75145932ff5..e79f70f0ff1 100644 --- a/xml/System.Net/CookieException.xml +++ b/xml/System.Net/CookieException.xml @@ -79,7 +79,7 @@ This exception is thrown when an attempt is made to add a with length greater than to a . The default maximum cookie size is 4096 bytes. **When setting the Name property for a cookie, make sure the value is not a null reference or empty string.** - The property must be initialized before using an instance of the class. The following characters are reserved and cannot be used for this attribute value: equal sign, semicolon, comma, new line (\n), carriage return (\r), tab (\t). The dollar sign ($) character cannot be the first character. + The property must be initialized before using an instance of the class. The following characters are reserved and cannot be used for this attribute value: equal sign, semicolon, comma, new line (\n), carriage return (\r), tab (\t). The dollar sign ($) character cannot be the first character. **When setting the Port property for a cookie, make sure the value is valid and enclosed in double quotes.** The attribute restricts the ports to which a cookie may be sent. The default value means no restriction. Setting the property to an empty string ("") restricts the port to the one used in the HTTP response. Otherwise the value must be a string in quotation marks that contains port values delineated with commas. diff --git a/xml/System.Net/CredentialCache.xml b/xml/System.Net/CredentialCache.xml index 3e439430392..d449874226c 100644 --- a/xml/System.Net/CredentialCache.xml +++ b/xml/System.Net/CredentialCache.xml @@ -76,7 +76,7 @@ ## Remarks The class stores credentials for multiple Internet resources. Applications that need to access multiple resources can store the credentials for those resources in a instance that then provides the proper set of credentials to the Internet resource when required. When the method is called, it compares the Uniform Resource Identifier (URI) and authentication type provided with those stored in the cache and returns the first set of credentials that match. - The property contains the system credentials of the current security context. For client applications, these represent the user name, password, and domain of the user who is currently logged in. For ASP.NET applications, the default credentials are the user credentials of the logged-in user or the user being impersonated. + The property contains the system credentials of the current security context. For client applications, these represent the user name, password, and domain of the user who is currently logged in. For ASP.NET applications, the default credentials are the user credentials of the logged-in user or the user being impersonated. @@ -353,17 +353,17 @@ property applies only to NTLM, negotiate, and Kerberos-based authentication. + The property applies only to NTLM, negotiate, and Kerberos-based authentication. represents the system credentials for the current security context in which the application is running. For a client-side application, these are usually the Windows credentials (user name, password, and domain) of the user running the application. For ASP.NET applications, the default credentials are the user credentials of the logged-in user, or the user being impersonated. - To get the credentials as a instance, use the property. + To get the credentials as a instance, use the property. > [!NOTE] > The instance returned by cannot be used to view the user name, password, or domain of the current security context. ## Examples - The following code example uses the property to get the system credentials of the application. + The following code example uses the property to get the system credentials of the application. :::code language="csharp" source="~/snippets/csharp/System.Net/CredentialCache/DefaultCredentials/credentialcache_defaultcredentials.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/CredentialCache/DefaultCredentials/credentialcache_defaultcredentials.vb" id="Snippet1"::: @@ -416,7 +416,7 @@ property is applicable only for NTLM, negotiate, and Kerberos-based authentication. + The credentials returned by the property is applicable only for NTLM, negotiate, and Kerberos-based authentication. The credentials returned by represents the authentication credentials for the current security context in which the application is running. For a client-side application, these are usually the Windows credentials (user name, password, and domain) of the user running the application. For ASP.NET applications, the default network credentials are the user credentials of the logged-in user, or the user being impersonated. diff --git a/xml/System.Net/Dns.xml b/xml/System.Net/Dns.xml index f089753f9de..33c9ed49da6 100644 --- a/xml/System.Net/Dns.xml +++ b/xml/System.Net/Dns.xml @@ -675,7 +675,7 @@ To perform this operation synchronously, use the method. - If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. + If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -735,7 +735,7 @@ ## Remarks This method blocks until the operation is complete. - The property of the instance returned is not populated by this method and will always be empty. + The property of the instance returned is not populated by this method and will always be empty. To perform this operation synchronously, use a method. @@ -811,7 +811,7 @@ ## Remarks This method blocks until the operation is complete. - If the is set to `true`, the property of the instance returned is not populated by this method and will always be empty. + If the is set to `true`, the property of the instance returned is not populated by this method and will always be empty. To perform this operation synchronously, use the method. @@ -1291,7 +1291,7 @@ For asynchronous access to DNS information, use the and methods. - If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. + If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1364,7 +1364,7 @@ IPv6 addresses are filtered from the results of the method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results were available for the `address` parameter. - The property of the instance returned is not populated by this method and will always be empty. + The property of the instance returned is not populated by this method and will always be empty. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1442,19 +1442,19 @@ 1. The method tries to parse the address. If the `hostNameOrAddress` parameter contains a legal IP string literal, then the first phase succeeds. -2. A reverse lookup using the IP address of the IP string literal is attempted to obtain the host name. This result is set as the property. +2. A reverse lookup using the IP address of the IP string literal is attempted to obtain the host name. This result is set as the property. -3. The host name from this reverse lookup is used again to obtain all the possible IP addresses associated with the name and set as the property. +3. The host name from this reverse lookup is used again to obtain all the possible IP addresses associated with the name and set as the property. For an IPv4 string literal, all three steps above may succeed. But it is possible for a stale DNS record for an IPv4 address that actually belongs to a different host to be returned. This may cause step #3 to fail and throw an exception (there is a DNS PTR record for the IPv4 address, but no DNS A record for the IPv4 address). - For IPv6, step #2 above may fail, since most IPv6 deployments do not register the reverse (PTR) record for an IPv6 address. So this method may return the string IPv6 literal as the fully-qualified domain (FQDN) host name in the property. + For IPv6, step #2 above may fail, since most IPv6 deployments do not register the reverse (PTR) record for an IPv6 address. So this method may return the string IPv6 literal as the fully-qualified domain (FQDN) host name in the property. The method has different behavior with respect to IP literals. If step #1 above succeeds (it successfully parses as an IP address), that address is immediately returned as the result. There is no attempt at a reverse lookup. IPv6 addresses are filtered from the results of the method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results where available for the `hostNameOrAddress`.parameter. - The property of the instance returned is not populated by this method and will always be empty. + The property of the instance returned is not populated by this method and will always be empty. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1572,7 +1572,7 @@ IPv6 addresses are filtered from the results of this method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results where available for the `address` parameter. - The property of the instance returned is not populated by this method and will always be empty. + The property of the instance returned is not populated by this method and will always be empty. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1648,19 +1648,19 @@ 1. The method tries to parse the address. If the `hostNameOrAddress` parameter contains a legal IP string literal, then the first phase succeeds. -2. A reverse lookup using the IP address of the IP string literal is attempted to obtain the host name. This result is set as the property. +2. A reverse lookup using the IP address of the IP string literal is attempted to obtain the host name. This result is set as the property. -3. The host name from this reverse lookup is used again to obtain all the possible IP addresses associated with the name and set as the property. +3. The host name from this reverse lookup is used again to obtain all the possible IP addresses associated with the name and set as the property. For an IPv4 string literal, all three steps above may succeed. But it is possible for a stale DNS record for an IPv4 address that actually belongs to a different host to be returned. This may cause step #3 to fail and throw an exception (there is a DNS PTR record for the IPv4 address, but no DNS A record for the IPv4 address). - For IPv6, step #2 above may fail, since most IPv6 deployments do not register the reverse (PTR) record for an IPv6 address. So this method may return the string IPv6 literal as the fully-qualified domain (FQDN) host name in the property. + For IPv6, step #2 above may fail, since most IPv6 deployments do not register the reverse (PTR) record for an IPv6 address. So this method may return the string IPv6 literal as the fully-qualified domain (FQDN) host name in the property. The method has different behavior with respect to IP literals. If step #1 above succeeds (it successfully parses as an IP address), that address is immediately returned as the result. There is no attempt at a reverse lookup. IPv6 addresses are filtered from the results of this method if the local computer does not have IPv6 installed. As a result, it is possible to get back an empty instance if only IPv6 results where available for the `hostNameOrAddress`.parameter. - The property of the instance returned is not populated by this method and will always be empty. + The property of the instance returned is not populated by this method and will always be empty. This method is implemented using the underlying operating system's name resolution APIs (such as the Win32 API getaddrinfo on Windows, and equivalent APIs on other platforms). If a host is described in the `hosts` file, the IP address or addresses there will be returned without querying the DNS server. @@ -1870,7 +1870,7 @@ When `hostName` is a DNS-style host name associated with multiple IP addresses, only the first IP address that resolves to that host name is returned. - If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. + If the property is set to `true`, the property of the instance returned is not populated by this method and will always be empty. > [!NOTE] > This member emits trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). diff --git a/xml/System.Net/DnsEndPoint.xml b/xml/System.Net/DnsEndPoint.xml index fef463924c2..68225fd0428 100644 --- a/xml/System.Net/DnsEndPoint.xml +++ b/xml/System.Net/DnsEndPoint.xml @@ -55,11 +55,11 @@ Represents a network endpoint as a host name or a string representation of an IP address and a port number. - class contains a host name or an IP address and remote port information needed by an application to connect to a service on a host. By combining the host name or IP address and port number of a service, the class forms a connection point to a service. - + class contains a host name or an IP address and remote port information needed by an application to connect to a service on a host. By combining the host name or IP address and port number of a service, the class forms a connection point to a service. + ]]> @@ -124,22 +124,22 @@ The port number associated with the address, or 0 to specify any available port. is in host order. Initializes a new instance of the class with the host name or string representation of an IP address and a port number. - constructor can be used to initialize a class using either a host name or a string that represents an IP address and a port. This constructor sets the property to . - - When using this constructor with a host name rather than a string representation of an IP address, the address family of the will remain even after use. The property of any that is created by calls to the method will be the address family of the first address to which a connection can be successfully established (not necessarily the first address to be resolved). - + constructor can be used to initialize a class using either a host name or a string that represents an IP address and a port. This constructor sets the property to . + + When using this constructor with a host name rather than a string representation of an IP address, the address family of the will remain even after use. The property of any that is created by calls to the method will be the address family of the first address to which a connection can be successfully established (not necessarily the first address to be resolved). + ]]> The parameter contains an empty string. The parameter is a . - is less than . - - -or- - + is less than . + + -or- + is greater than . @@ -189,26 +189,26 @@ One of the values. Initializes a new instance of the class with the host name or string representation of an IP address, a port number, and an address family. - constructor can be used to initialize a class using either a host name or a string that represents an IP address, a port, and an address family. - - When using the constructor with a host name rather than a string representation of an IP address, the address family restricts DNS resolution to prefer addresses of the specified address family value. When using the constructor with the address family specified as , the address family of the will remain even after use. The property of any that is created by calls to the method will be the address family of the first address to which a connection can be successfully established (not necessarily the first address to be resolved). - + constructor can be used to initialize a class using either a host name or a string that represents an IP address, a port, and an address family. + + When using the constructor with a host name rather than a string representation of an IP address, the address family restricts DNS resolution to prefer addresses of the specified address family value. When using the constructor with the address family specified as , the address family of the will remain even after use. The property of any that is created by calls to the method will be the address family of the first address to which a connection can be successfully established (not necessarily the first address to be resolved). + ]]> - The parameter contains an empty string. - - -or- - + The parameter contains an empty string. + + -or- + is . The parameter is a . - is less than . - - -or- - + is less than . + + -or- + is greater than . @@ -260,11 +260,11 @@ Gets the Internet Protocol (IP) address family. One of the values. - property indicates the address family for an instance of the class. - + property indicates the address family for an instance of the class. + ]]> @@ -324,11 +324,11 @@ if the two instances are equal; otherwise, . - method compares the current instance with the `comparand` parameter and returns `true` if the two instances contain the same endpoint. - + method compares the current instance with the `comparand` parameter and returns `true` if the two instances contain the same endpoint. + ]]> @@ -376,11 +376,11 @@ Returns a hash value for a . An integer hash value for the . - method returns a hash code of the . This value can be used as a key in hash tables. - + method returns a hash code of the . This value can be used as a key in hash tables. + ]]> @@ -433,11 +433,11 @@ Gets the host name or string representation of the Internet Protocol (IP) address of the host. A host name or string representation of an IP address. - property indicates the host name or string representation of the IP address for an instance of the class. - + property indicates the host name or string representation of the IP address for an instance of the class. + ]]> @@ -535,11 +535,11 @@ Returns the host name or string representation of the IP address and port number of the . A string containing the address family, host name or IP address string, and the port number of the specified . - method returns a string that contains the address family, the host name or IP address string, and the port number. - + method returns a string that contains the address family, the host name or IP address string, and the port number. + ]]> diff --git a/xml/System.Net/DownloadDataCompletedEventArgs.xml b/xml/System.Net/DownloadDataCompletedEventArgs.xml index b6bf552750a..18a7410d705 100644 --- a/xml/System.Net/DownloadDataCompletedEventArgs.xml +++ b/xml/System.Net/DownloadDataCompletedEventArgs.xml @@ -60,7 +60,7 @@ ## Examples The following code example demonstrates downloading a user-specified resource. - + :::code language="csharp" source="~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs" id="Snippet21"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb" id="Snippet21"::: @@ -115,7 +115,7 @@ and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/DownloadProgressChangedEventArgs.xml b/xml/System.Net/DownloadProgressChangedEventArgs.xml index aa1129b93b6..6c3c70abde6 100644 --- a/xml/System.Net/DownloadProgressChangedEventArgs.xml +++ b/xml/System.Net/DownloadProgressChangedEventArgs.xml @@ -117,7 +117,7 @@ The following code example demonstrates setting an event handler for the property. + To determine what percentage of the transfer has occurred, use the property. ## Examples The following code example shows an implementation of a handler for the event. The method displays the value of the `BytesReceived` property. @@ -180,9 +180,9 @@ The following code example demonstrates setting an event handler for the property. + To determine the number of bytes already received, use the property. - To determine what percentage of the transfer has occurred, use the property. + To determine what percentage of the transfer has occurred, use the property. ## Examples The following code example shows an implementation of a handler for the event. The method displays the value of the `TotalBytesToReceive` property. diff --git a/xml/System.Net/DownloadStringCompletedEventArgs.xml b/xml/System.Net/DownloadStringCompletedEventArgs.xml index e5d72e1df58..3b9371181e7 100644 --- a/xml/System.Net/DownloadStringCompletedEventArgs.xml +++ b/xml/System.Net/DownloadStringCompletedEventArgs.xml @@ -64,7 +64,7 @@ ## Examples The following code example demonstrates downloading a string asynchronously. - + :::code language="csharp" source="~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs" id="Snippet28"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb" id="Snippet28"::: @@ -122,7 +122,7 @@ and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/EndPoint.xml b/xml/System.Net/EndPoint.xml index a9d4334e996..69d15e8df1a 100644 --- a/xml/System.Net/EndPoint.xml +++ b/xml/System.Net/EndPoint.xml @@ -62,11 +62,11 @@ Identifies a network address. This is an class. - class provides an `abstract` base class that represents a network resource or service. Descendant classes combine network connection information to form a connection point to a service. - + class provides an `abstract` base class that represents a network resource or service. Descendant classes combine network connection information to form a connection point to a service. + ]]> @@ -164,11 +164,11 @@ Gets the address family to which the endpoint belongs. One of the values. - property specifies the addressing scheme that is used by the endpoint's underlying network protocol. - + property specifies the addressing scheme that is used by the endpoint's underlying network protocol. + ]]> Any attempt is made to get or set the property when the property is not overridden in a descendant class. diff --git a/xml/System.Net/FileWebRequest.xml b/xml/System.Net/FileWebRequest.xml index 35eaa56086e..cf783bb96f7 100644 --- a/xml/System.Net/FileWebRequest.xml +++ b/xml/System.Net/FileWebRequest.xml @@ -71,7 +71,7 @@ Do not use the constructor. Use the method to initialize new instances of the class. If the URI scheme is `file://`, the method returns a object. - The method makes a synchronous request for the file specified in the property and returns a object that contains the response. You can make an asynchronous request for the file using the and methods. + The method makes a synchronous request for the file specified in the property and returns a object that contains the response. You can make an asynchronous request for the file using the and methods. When you want to write data to a file, the method returns a instance to write to. The and methods provide asynchronous access to the write data stream. @@ -202,7 +202,7 @@ method cancels a request to a resource. After a request is canceled, calling the , , , , , or method causes a with the property set to . + The method cancels a request to a resource. After a request is canceled, calling the , , , , , or method causes a with the property set to . **Note** This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -420,7 +420,7 @@ property is currently not used by the class. + The property is currently not used by the class. ]]> @@ -536,7 +536,7 @@ property contains the media type of the data being sent. This is typically the MIME encoding of the content. The property is currently not used by the class. + The property contains the media type of the data being sent. This is typically the MIME encoding of the content. The property is currently not used by the class. ]]> @@ -600,7 +600,7 @@ class does not authenticate requests for files from the local file system, it ignores the contents, if any, of the property. Authentication for is handled by the access control lists for the file resource in the underlying file system. + Because the class does not authenticate requests for files from the local file system, it ignores the contents, if any, of the property. Authentication for is handled by the access control lists for the file resource in the underlying file system. ]]> @@ -1069,7 +1069,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property is currently not used by the class. + The property is currently not used by the class. ]]> @@ -1124,7 +1124,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property is currently not used by the class. + The property is currently not used by the class. @@ -1197,7 +1197,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property is currently not used by the class. + The property is currently not used by the class. ]]> @@ -1261,7 +1261,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property is currently not used by the class. + The property is currently not used by the class. ]]> @@ -1316,7 +1316,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property to get the URI of the request. + The following code example uses the property to get the URI of the request. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebRequest/RequestUri/filewebrequest_contentlength.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebRequest/RequestUri/filewebrequest_contentlength.vb" id="Snippet2"::: @@ -1435,7 +1435,7 @@ This method stores in the task it returns all non-usage exceptions that the meth ## Examples - The following code example sets the property. Refer to the complete example in the class. + The following code example sets the property. Refer to the complete example in the class. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebRequest/Overview/getrequeststream.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebRequest/Overview/getrequeststream.vb" id="Snippet3"::: @@ -1487,7 +1487,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + The property is provided only for compatibility with other implementations of the and classes. There is no reason to use . ]]> diff --git a/xml/System.Net/FileWebResponse.xml b/xml/System.Net/FileWebResponse.xml index 8c85eca6b3a..aa9bea7f538 100644 --- a/xml/System.Net/FileWebResponse.xml +++ b/xml/System.Net/FileWebResponse.xml @@ -260,12 +260,12 @@ property contains the length, in bytes, of the file system resource. + The property contains the length, in bytes, of the file system resource. ## Examples - The following example uses the property to obtain the content length of the file system resource. + The following example uses the property to obtain the content length of the file system resource. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebResponse/ContentLength/filewebresponse_contentlength_contenttype.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebResponse/ContentLength/filewebresponse_contentlength_contenttype.vb" id="Snippet1"::: @@ -317,12 +317,12 @@ property contains the content type of the file system resource. The value of is always "binary/octet-stream". + The property contains the content type of the file system resource. The value of is always "binary/octet-stream". ## Examples - The following example uses the property to obtain the content type of the file system resource. + The following example uses the property to obtain the content type of the file system resource. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebResponse/ContentLength/filewebresponse_contentlength_contenttype.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebResponse/ContentLength/filewebresponse_contentlength_contenttype.vb" id="Snippet1"::: @@ -525,12 +525,12 @@ property contains two name/value pairs, one for content length and one for content type, both of which are also exposed as properties, and . + The property contains two name/value pairs, one for content length and one for content type, both of which are also exposed as properties, and . ## Examples - The following example uses the property to retrieve the name/value pairs associated with the response. + The following example uses the property to retrieve the name/value pairs associated with the response. :::code language="csharp" source="~/snippets/csharp/System.Net/FileWebResponse/Headers/filewebresponse_headers.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/FileWebResponse/Headers/filewebresponse_headers.vb" id="Snippet1"::: @@ -582,7 +582,7 @@ property contains the URI of the file system resource that provided the response. This is always the file system resource that was requested. + The property contains the URI of the file system resource that provided the response. This is always the file system resource that was requested. diff --git a/xml/System.Net/FtpStatusCode.xml b/xml/System.Net/FtpStatusCode.xml index fd9cd503d07..a63d6396718 100644 --- a/xml/System.Net/FtpStatusCode.xml +++ b/xml/System.Net/FtpStatusCode.xml @@ -47,7 +47,7 @@ enumeration defines the values returned in the property. + The enumeration defines the values returned in the property. For additional information about FTP server status codes, see [RFC 959: "File Transfer Protocol", Section 4.2: "FTP Replies"](https://www.ietf.org/rfc/rfc959.txt). @@ -55,7 +55,7 @@ ## Examples The following code example sends an FTP request to make a new directory on an FTP server and checks the status code returned in the response. - + :::code language="csharp" source="~/snippets/csharp/System.Net/FtpStatusCode/Overview/ftptests.cs" id="Snippet22"::: ]]> diff --git a/xml/System.Net/FtpWebRequest.xml b/xml/System.Net/FtpWebRequest.xml index 80f877ba418..ef3da3ed733 100644 --- a/xml/System.Net/FtpWebRequest.xml +++ b/xml/System.Net/FtpWebRequest.xml @@ -60,28 +60,28 @@ To obtain an instance of , use the method. You can also use the class to upload and download information from an FTP server. Using either of these approaches, when you specify a network resource that uses the FTP scheme (for example, `"ftp://contoso.com"`) the class provides the ability to programmatically interact with FTP servers. - The URI may be relative or absolute. If the URI is of the form `"ftp://contoso.com/%2fpath"` (%2f is an escaped '/'), then the URI is absolute, and the current directory is `/path`. If, however, the URI is of the form `"ftp://contoso.com/path"`, first the .NET Framework logs into the FTP server (using the user name and password set by the property), then the current directory is set to `/path`. + The URI may be relative or absolute. If the URI is of the form `"ftp://contoso.com/%2fpath"` (%2f is an escaped '/'), then the URI is absolute, and the current directory is `/path`. If, however, the URI is of the form `"ftp://contoso.com/path"`, first the .NET Framework logs into the FTP server (using the user name and password set by the property), then the current directory is set to `/path`. - You must have a valid user name and password for the server or the server must allow anonymous logon. You can specify the credentials used to connect to the server by setting the property or you can include them in the portion of the URI passed to the method. If you include information in the URI, the property is set to a new network credential with the specified user name and password information. + You must have a valid user name and password for the server or the server must allow anonymous logon. You can specify the credentials used to connect to the server by setting the property or you can include them in the portion of the URI passed to the method. If you include information in the URI, the property is set to a new network credential with the specified user name and password information. > [!CAUTION] -> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports Secure Sockets Layer (SSL), you should set to `true`. +> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports Secure Sockets Layer (SSL), you should set to `true`. You must have to access the FTP resource; otherwise, a exception is thrown. - Specify the FTP command to send to the server by setting the property to a value defined in the structure. To transmit text data, change the property from its default value (`true`) to `false`. For details and restrictions, see . + Specify the FTP command to send to the server by setting the property to a value defined in the structure. To transmit text data, change the property from its default value (`true`) to `false`. For details and restrictions, see . When using an object to upload a file to a server, you must write the file content to the request stream obtained by calling the method or its asynchronous counterparts, the and methods. You must write to the stream and close the stream before sending the request. Requests are sent to the server by calling the method or its asynchronous counterparts, the and methods. When the requested operation completes, an object is returned. The object provides the status of the operation and any data downloaded from the server. - You can set a time-out value for reading or writing to the server by using the property. If the time-out period is exceeded, the calling method throws a with set to . + You can set a time-out value for reading or writing to the server by using the property. If the time-out period is exceeded, the calling method throws a with set to . When downloading a file from an FTP server, if the command was successful, the contents of the requested file are available in the response object's stream. You can access this stream by calling the method. For more information, see . - If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. If the specified proxy is an HTTP proxy, only the , , and commands are supported. + If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. If the specified proxy is an HTTP proxy, only the , , and commands are supported. - Only downloaded binary content is cached; that is, content received using the command with the property set to `true`. + Only downloaded binary content is cached; that is, content received using the command with the property set to `true`. Multiple s reuse existing connections, if possible. @@ -320,7 +320,7 @@ ## Remarks You must complete the asynchronous operation by calling the method. Typically, is called by the method referenced by `callback`. To determine the state of the operation, check the properties in the object returned by the method. - If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. + If the property is set, either directly or in a configuration file, communications with the FTP server are made through the specified proxy. does not block while waiting for the response from the server. To block, call the method in place of . @@ -470,7 +470,7 @@ Using connection groups can improve performance because this allows all of the requests for a user to reuse the connection authenticated with the user's credentials. - Changing the property after calling the , , , or method causes an exception. + Changing the property after calling the , , , or method causes an exception. @@ -543,7 +543,7 @@ property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + The property is provided only for compatibility with other implementations of the and classes. There is no reason to use . ]]> @@ -597,7 +597,7 @@ property when downloading a file from an FTP server. This offset indicates the position in the server's file that marks the start of the data to be downloaded. The offset is specified as the number of bytes from the start of the file; the offset of the first byte is zero. + Set the property when downloading a file from an FTP server. This offset indicates the position in the server's file that marks the start of the data to be downloaded. The offset is specified as the number of bytes from the start of the file; the offset of the first byte is zero. Setting causes the to send a restart (`REST`) command to the server. This command is ignored by most FTP server implementations if you are uploading data to the server. @@ -665,7 +665,7 @@ property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + The property is provided only for compatibility with other implementations of the and classes. There is no reason to use . ]]> @@ -721,10 +721,10 @@ property by using a credential of type ; this ensures that the user name and password can be read and sent to the server. + You are not required to specify credentials when connecting using anonymous logon. You must set the property by using a credential of type ; this ensures that the user name and password can be read and sent to the server. > [!CAUTION] -> Credentials information is not encrypted when transmitted to the server unless the property is set to `true`. +> Credentials information is not encrypted when transmitted to the server unless the property is set to `true`. Changing after calling the , , , or method causes an exception. @@ -864,7 +864,7 @@ ## Remarks > [!CAUTION] -> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports SSL, you should set to `true`. +> Unless the property is `true`, all data and commands, including your user name and password information, are sent to the server in clear text. Anyone monitoring network traffic can view your credentials and use them to connect to the server. If you are connecting to an FTP server that requires credentials and supports SSL, you should set to `true`. The `"AUTH TLS"` command is sent to the server to request an encrypted session. If the server does not recognize this command, you receive a exception. @@ -932,7 +932,7 @@ method blocks until the operation completes. To determine whether the operation has completed, check the property before calling . + If the operation has not completed, the method blocks until the operation completes. To determine whether the operation has completed, check the property before calling . In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while opening the stream for writing. @@ -1007,7 +1007,7 @@ method is called, blocks until the operation completes. To prevent blocking, check the property before calling . + If the operation has not completed at the time the method is called, blocks until the operation completes. To prevent blocking, check the property before calling . In addition to the exceptions noted in "Exceptions," rethrows exceptions that were thrown while communicating with the server. @@ -1086,7 +1086,7 @@ ## Remarks Set the request properties before calling the method. After writing the data to the stream, you must close the stream prior to sending the request. - If you have not set the property to or , you cannot get the stream. + If you have not set the property to or , you cannot get the stream. blocks while waiting for the stream. To prevent this, call the method in place of . @@ -1168,7 +1168,7 @@ causes a control connection to be established, and might also create a data connection. blocks until the response is received. To prevent this, you can perform this operation asynchronously by calling the and methods in place of . - If the property is set, either directly or in a configuration file, communications with the FTP server are made through the proxy. + If the property is set, either directly or in a configuration file, communications with the FTP server are made through the proxy. If a is thrown, use the and properties of the exception to determine the response from the server. @@ -1257,7 +1257,7 @@ property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + The property is provided only for compatibility with other implementations of the and classes. There is no reason to use . ]]> @@ -1312,7 +1312,7 @@ property is set to `false`, the control connection is closed when you call the method. + When the property is set to `false`, the control connection is closed when you call the method. Changing after calling the , , , or method causes an exception. @@ -1382,7 +1382,7 @@ property determines which command is sent to the server. You set the by using the strings defined in the public field members of the class. Note that the strings defined in the class are the only supported options for the property. Setting the property to any other value will result in an exception. + The property determines which command is sent to the server. You set the by using the strings defined in the public field members of the class. Note that the strings defined in the class are the only supported options for the property. Setting the property to any other value will result in an exception. When setting to , you must do so before calling the method. Failure to call these members in the correct order causes a exception when you attempt to get the request stream. @@ -1459,7 +1459,7 @@ property is provided only for compatibility with other implementations of the and classes. + The property is provided only for compatibility with other implementations of the and classes. ]]> @@ -1582,9 +1582,9 @@ The following code example displays this property value. ## Remarks The is used when writing to the stream returned by the method or reading from the stream returned by the method. - Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. If the time-out period is exceeded, the calling method throws a with set to . + Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. If the time-out period is exceeded, the calling method throws a with set to . - To specify the amount of time to wait for the request to complete, use the property. + To specify the amount of time to wait for the request to complete, use the property. ]]> @@ -1694,7 +1694,7 @@ The following code example displays this property value. property is the URI specified when the method was called to obtain this instance. + The value of the property is the URI specified when the method was called to obtain this instance. @@ -1761,7 +1761,7 @@ The following code example displays this property value. object exists, one is created for the FTP server. To set the maximum number of connections that can be open for an FTP server, set the property of the instance returned by this property. + If no object exists, one is created for the FTP server. To set the maximum number of connections that can be open for an FTP server, set the property of the instance returned by this property. @@ -1828,9 +1828,9 @@ The following code example displays this property value. property to (-1). This is the default value. + To specify an infinite value, set the property to (-1). This is the default value. - is the number of milliseconds that a synchronous request made with the method waits for a response and that the method waits for a stream. If a resource does not respond within the time-out period, the request throws a with the property set to . + is the number of milliseconds that a synchronous request made with the method waits for a response and that the method waits for a stream. If a resource does not respond within the time-out period, the request throws a with the property set to . Changing after calling the , , , or method causes an exception. @@ -1968,7 +1968,7 @@ The following code example displays this property value. property is provided only for compatibility with other implementations of the and classes. There is no reason to use . + The property is provided only for compatibility with other implementations of the and classes. There is no reason to use . ]]> @@ -2024,7 +2024,7 @@ The following code example displays this property value. property to `true` sends the "`PASV"` command to the server. This command requests the server to listen on a data port and to wait for a connection rather than initiate one upon receipt of a transfer command. + Setting the property to `true` sends the "`PASV"` command to the server. This command requests the server to listen on a data port and to wait for a connection rather than initiate one upon receipt of a transfer command. For a description of the behaviors that are specified using , see [RFC 959: "File Transfer Protocol", Section 3.2: "Establishing Data Connections" and Section 4.1.2: "Transfer Parameter Commands"](https://www.ietf.org/rfc/rfc959.txt). diff --git a/xml/System.Net/FtpWebResponse.xml b/xml/System.Net/FtpWebResponse.xml index f8422dd9142..7ce89b07059 100644 --- a/xml/System.Net/FtpWebResponse.xml +++ b/xml/System.Net/FtpWebResponse.xml @@ -63,9 +63,9 @@ ## Remarks Instances of are obtained by calling the method. The returned object must be cast to an . When your application no longer needs the object, call the method to free the resources held by the . - The property contains the status code returned by the server, and the property returns the status code and a message that describes the status. The values returned by these properties change as the messages are returned by the server. + The property contains the status code returned by the server, and the property returns the status code and a message that describes the status. The values returned by these properties change as the messages are returned by the server. - Any data returned by the request, such as the list of file names returned for a request, is available in the stream returned by the method. The length of the stream data can be obtained from the property. + Any data returned by the request, such as the list of file names returned for a request, is available in the stream returned by the method. The length of the stream data can be obtained from the property. @@ -189,7 +189,7 @@ method closes the data stream returned by the method if the property is `false`. During the close, data might be sent to the server on the control connection. + The method closes the data stream returned by the method if the property is `false`. During the close, data might be sent to the server on the control connection. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -253,7 +253,7 @@ property contains the number of bytes in the stream. returns −1 if no data was returned in the response or if the server did not send content length information. The return value is greater than or equal to zero if data was or should have been returned. For example, for requests that use the field, the property always returns −1. For requests that use the method, the property is always zero. For requests that use the method, the property is greater than zero if the downloaded file contained data and is zero if it was empty. + When a response stream is returned by the FTP server, the property contains the number of bytes in the stream. returns −1 if no data was returned in the response or if the server did not send content length information. The return value is greater than or equal to zero if data was or should have been returned. For example, for requests that use the field, the property always returns −1. For requests that use the method, the property is always zero. For requests that use the method, the property is greater than zero if the downloaded file contained data and is zero if it was empty. For requests that use the method, returns the size of the specified file on the server. @@ -362,7 +362,7 @@ This property is provided only for compatibility with other implementations of t property is not available until the connection to the server is closed or reused. If the property is `true`, the connection used by this request is not closed, which prevents the server from sending an exit message. + The property is not available until the connection to the server is closed or reused. If the property is `true`, the connection used by this request is not closed, which prevents the server from sending an exit message. @@ -497,7 +497,7 @@ This property is provided only for compatibility with other implementations of t property is provided only for compatibility with other implementations of the and classes. + The property is provided only for compatibility with other implementations of the and classes. ]]> @@ -551,7 +551,7 @@ This property is provided only for compatibility with other implementations of t property returns the data requested by the method. For requests sent using any other method, returns . + The property returns the data requested by the method. For requests sent using any other method, returns . @@ -618,7 +618,7 @@ This property is provided only for compatibility with other implementations of t property is not always the same as the value returned by the property. + Because of server- and resource-specific behaviors, such as redirection, the value returned by the property is not always the same as the value returned by the property. For requests that use the method, returns the name of the file on the server. @@ -681,7 +681,7 @@ This property is provided only for compatibility with other implementations of t property is included in the property. When you are downloading data, the value of changes as status codes are returned by the FTP server. After you call the method, contains an intermediate status code. When you call the method, contains the final status. + The value returned by the property is included in the property. When you are downloading data, the value of changes as status codes are returned by the FTP server. After you call the method, contains an intermediate status code. When you call the method, contains the final status. @@ -743,7 +743,7 @@ This property is provided only for compatibility with other implementations of t property includes the 3-digit property value. When downloading data, the value of changes as status codes are returned by the FTP server. After you call the method, contains an intermediate status code. When you call the method, contains the final status. + The text returned by the property includes the 3-digit property value. When downloading data, the value of changes as status codes are returned by the FTP server. After you call the method, contains an intermediate status code. When you call the method, contains the final status. @@ -860,7 +860,7 @@ This property is provided only for compatibility with other implementations of t property is set to `true`), the property returns the first welcome message received with the connection. + If the connection is being reused (the property is set to `true`), the property returns the first welcome message received with the connection. diff --git a/xml/System.Net/GlobalProxySelection.xml b/xml/System.Net/GlobalProxySelection.xml index 20701082c60..fba45dacd01 100644 --- a/xml/System.Net/GlobalProxySelection.xml +++ b/xml/System.Net/GlobalProxySelection.xml @@ -67,9 +67,9 @@ stores the proxy settings for the default proxy that instances use to contact Internet sites beyond the local network. The default proxy setting is initialized from the global or application configuration file, and can be overridden for individual requests or disabled by setting the property to the result of the method. + The stores the proxy settings for the default proxy that instances use to contact Internet sites beyond the local network. The default proxy setting is initialized from the global or application configuration file, and can be overridden for individual requests or disabled by setting the property to the result of the method. - The proxy settings stored in are used by any derived objects that support proxies and have their property value set to `null` (the default). Proxies are currently supported by , , and . + The proxy settings stored in are used by any derived objects that support proxies and have their property value set to `null` (the default). Proxies are currently supported by , , and . **Note** Changes to the after a request is made are not reflected in a . @@ -218,7 +218,7 @@ Instead of calling the `GetEmptyWebProxy` method, you can assign `null` to membe property sets the proxy that all instances use if the request supports proxies and no proxy is set explicitly using the property. Proxies are currently supported by and . + The property sets the proxy that all instances use if the request supports proxies and no proxy is set explicitly using the property. Proxies are currently supported by and . ]]> diff --git a/xml/System.Net/HttpListener.xml b/xml/System.Net/HttpListener.xml index 2def209175b..3b732f08766 100644 --- a/xml/System.Net/HttpListener.xml +++ b/xml/System.Net/HttpListener.xml @@ -232,9 +232,9 @@ ## Remarks The 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. + 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. + 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 , . @@ -242,7 +242,7 @@ ## Examples - The following code example demonstrates using the property to specify an authentication scheme. + 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/System.Net/HttpListener/Overview/test.vb" id="Snippet14"::: @@ -303,11 +303,11 @@ ## Remarks > [!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 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. + 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). + 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 , . @@ -385,7 +385,7 @@ 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 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. @@ -518,11 +518,11 @@ The following code example demonstrates calling the `Close` method: 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 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 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: + 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: @@ -542,7 +542,7 @@ The following code example demonstrates calling the `Close` method: `"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. + 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. @@ -604,7 +604,7 @@ The following code example demonstrates calling the `Close` method: ## Remarks The 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. + 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). @@ -682,9 +682,9 @@ The following code example demonstrates calling the `Close` method: 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 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. + The property must be `null`. The instance gets the Channel Binding Token (CBT) directly from its own TLS session if there is one. ]]> @@ -754,13 +754,13 @@ The following code example demonstrates calling the `Close` method: 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 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. + 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 that the property set to . + If a delegate returns `null` for this property, this represents a that the property set to . ]]> @@ -820,7 +820,7 @@ The following code example demonstrates calling the `Close` method: 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. + 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 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. @@ -890,7 +890,7 @@ The following code example demonstrates calling the `Close` method: ## Remarks This operation will not block. The returned 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. + 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 . @@ -1063,7 +1063,7 @@ The following code example demonstrates calling the `Close` method: property to detect whether an object can be used with the current operating system. + The following code example demonstrates the use of the 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/System.Net/HttpListener/Overview/test.vb" id="Snippet2"::: @@ -1119,7 +1119,7 @@ The following code example demonstrates calling the `Close` method: ## Examples - The following code example demonstrates using the property to obtain and print the URI prefixes that are handled. + 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/System.Net/HttpListener/Overview/test.vb" id="Snippet1"::: @@ -1189,7 +1189,7 @@ The following code example demonstrates calling the `Close` method: ## Examples - The following code example demonstrates setting the property. + 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/System.Net/HttpListener/Overview/test.vb" id="Snippet10"::: diff --git a/xml/System.Net/HttpListenerContext.xml b/xml/System.Net/HttpListenerContext.xml index 154a7124dee..ead27f62f80 100644 --- a/xml/System.Net/HttpListenerContext.xml +++ b/xml/System.Net/HttpListenerContext.xml @@ -56,7 +56,7 @@ ## Remarks This class provides the information related to a client's Hypertext Transfer Protocol (HTTP) request being processed by an object. This class also has methods that allow an object to accept a WebSocket connection. - The method returns instances of the class. To get the object that represents the client request, use the property. To get the object that represents the response that will be sent to the client by the , use the property. To get user information about the client sending the request, such as its login name and whether it has been authenticated, you can query the properties in the object returned by the property. + The method returns instances of the class. To get the object that represents the client request, use the property. To get the object that represents the response that will be sent to the client by the , use the property. To get user information about the client sending the request, such as its login name and whether it has been authenticated, you can query the properties in the object returned by the property. Closing an object sends the response to the client and frees any resources used by the . Aborting an object discards the response to the client if it has not already been sent, and frees any resources used by the . After closing or aborting an object, you cannot reference its methods or properties. If you do so, you will receive an exception. @@ -573,9 +573,9 @@ indicates that it requires authentication using the property or by specifying an delegate using the property. + An indicates that it requires authentication using the property or by specifying an delegate using the property. - To determine the client's login name and authentication information, check the property in the object returned by this property. + To determine the client's login name and authentication information, check the property in the object returned by this property. diff --git a/xml/System.Net/HttpListenerException.xml b/xml/System.Net/HttpListenerException.xml index 2bc0e55a90b..0f7c33ed5e4 100644 --- a/xml/System.Net/HttpListenerException.xml +++ b/xml/System.Net/HttpListenerException.xml @@ -56,22 +56,22 @@ The exception that is thrown when an error occurs processing an HTTP request. - class and its associated classes when an error occurs during initialization of the or while creating or sending a response to an HTTP request. For example, this exception is thrown if the attempts to register a Uniform Resource Identifier (URI) prefix that is already registered. - - **Associated Tips** - - Make sure you are not attempting to register a URI prefix that is already registered. - If the URI prefix is already registered, this exception will occur. - - Make sure your HTTP request is valid. - This exception is thrown by the class and its associated classes when an error occurs during the initialization of the or while creating or sending a response to an HTTP request. - - If you are using the `HttpListenerPrefixCollection.Add` method, make sure the `uriPrefix` has not been already added. - This exception will be thrown if another has already added the prefix `uriPrefix`. - + class and its associated classes when an error occurs during initialization of the or while creating or sending a response to an HTTP request. For example, this exception is thrown if the attempts to register a Uniform Resource Identifier (URI) prefix that is already registered. + + **Associated Tips** + + Make sure you are not attempting to register a URI prefix that is already registered. + If the URI prefix is already registered, this exception will occur. + + Make sure your HTTP request is valid. + This exception is thrown by the class and its associated classes when an error occurs during the initialization of the or while creating or sending a response to an HTTP request. + + If you are using the `HttpListenerPrefixCollection.Add` method, make sure the `uriPrefix` has not been already added. + This exception will be thrown if another has already added the prefix `uriPrefix`. + ]]> @@ -125,11 +125,11 @@ Initializes a new instance of the class. - and properties using the most recent Windows error. - + and properties using the most recent Windows error. + ]]> @@ -179,11 +179,11 @@ A value that identifies the error that occurred. Initializes a new instance of the class using the specified error code. - property. - + property. + ]]> @@ -235,11 +235,11 @@ A that describes the error that occurred. Initializes a new instance of the class using the specified error code and message. - property. The `message` parameter is used to set the property. - + property. The `message` parameter is used to set the property. + ]]> @@ -341,11 +341,11 @@ Gets a value that identifies the error that occurred. A value. - diff --git a/xml/System.Net/HttpListenerPrefixCollection.xml b/xml/System.Net/HttpListenerPrefixCollection.xml index 07e0845cfc0..b3fbea003df 100644 --- a/xml/System.Net/HttpListenerPrefixCollection.xml +++ b/xml/System.Net/HttpListenerPrefixCollection.xml @@ -67,7 +67,7 @@ property returns instances of this collection. + The property returns instances of this collection. @@ -548,7 +548,7 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . @@ -776,7 +776,7 @@ method before you can access the first element. To access the element at the current position, call the property. + The object that is returned by this method is initially positioned before the first element in this collection. You must call the method before you can access the first element. To access the element at the current position, call the property. Do not modify the collection while using the enumerator. If the collection is modified while an enumerator is in use, an attempt to set the position by calling or causes an . diff --git a/xml/System.Net/HttpListenerRequest.xml b/xml/System.Net/HttpListenerRequest.xml index bf020633e5f..d0297082406 100644 --- a/xml/System.Net/HttpListenerRequest.xml +++ b/xml/System.Net/HttpListenerRequest.xml @@ -54,11 +54,11 @@ object, the provides a object that contains information about the sender, the request, and the response that is sent to the client. The property returns the object that describes the request. + When a client makes a request to a Uniform Resource Identifier (URI) handled by an object, the provides a object that contains information about the sender, the request, and the response that is sent to the client. The property returns the object that describes the request. - The object contains information about the request, such as the request string, string, and request body data (see the property). + The object contains information about the request, such as the request string, string, and request body data (see the property). - To reply to the request, you must get the associated response using the property. + To reply to the request, you must get the associated response using the property. @@ -308,7 +308,7 @@ ## Examples - The following code example demonstrates using the property. + The following code example demonstrates using the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet16"::: @@ -369,7 +369,7 @@ ## Examples - The following code example uses the property while processing body data. + The following code example uses the property while processing body data. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet16"::: @@ -971,14 +971,14 @@ or property. + Your application requests client authentication using the or property. Your application does not receive an for requests from clients that are not successfully authenticated. ## Examples - The following code example displays the value of the property. + The following code example displays the value of the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet17"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet17"::: @@ -1044,7 +1044,7 @@ ## Examples - The following code example demonstrates using the property. + The following code example demonstrates using the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet17"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet17"::: @@ -1104,7 +1104,7 @@ ## Examples - The following code example demonstrates using the property. + The following code example demonstrates using the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet17"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet17"::: @@ -1390,13 +1390,13 @@ property value from the object returned by . + In a URL, the query information is separated from the path information by a question mark (?). Name/value pairs are separated by an equals sign (=). To access the query data as a single string, get the property value from the object returned by . > [!NOTE] > Queries without an equals sign (for example, `http://www.contoso.com/query.htm?Name`) are added to the `null` key in the . ## Examples - The following code example demonstrates using the property. + The following code example demonstrates using the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet15"::: @@ -1463,12 +1463,12 @@ ## Remarks The raw URL is defined as the part of the URL following the domain information. In the URL string `http://www.contoso.com/articles/recent.aspx`, the raw URL is `/articles/recent.aspx`. The raw URL includes the query string, if present. - To obtain the host and port information, use the property. + To obtain the host and port information, use the property. ## Examples - The following code example demonstrates using the property. + The following code example demonstrates using the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet11"::: @@ -1634,7 +1634,7 @@ property to perform custom Service Provide Name (SPN) validation. + An application could use the property to perform custom Service Provide Name (SPN) validation. ]]> @@ -1694,7 +1694,7 @@ An application could use the property to perform custom authentication using calls to the native Win32 [AcceptSecurityContext](/windows/win32/api/sspi/nf-sspi-acceptsecuritycontext) function. - If an application attempts to retrieve the channel binding token (CBT) from this property using the method and the is not , then the will throw . The overrides the method with an internal implementation. + If an application attempts to retrieve the channel binding token (CBT) from this property using the method and the is not , then the will throw . The overrides the method with an internal implementation. ]]> @@ -1761,13 +1761,13 @@ property allows you to obtain all the information available from a object. If you need to know only the raw text of the URI request, consider using the property instead. + The property allows you to obtain all the information available from a object. If you need to know only the raw text of the URI request, consider using the property instead. - The property is null if the from the client could not be parsed. + The property is null if the from the client could not be parsed. - The property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. + The property indicates if uses the raw unescaped URI instead of the converted URI where any percent-encoded values are converted and other normalization steps are taken. - When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. + When a instance receives a request through the `http.sys` service, it creates an instance of the URI string provided by `http.sys`, and exposes it as the property. The `http.sys` service exposes two request URI strings: @@ -1787,7 +1787,7 @@ `http://www.contoso.com/path/` - The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: + The `http.sys` service combines the property value and the string in the request line to create a converted URI. In addition, `http.sys` and the class also do the following: - Un-escapes all percent encoded values. @@ -1804,7 +1804,7 @@ |EnableNonUTF8|1|If zero, `http.sys` accepts only UTF-8-encoded URLs.

If non-zero, `http.sys` also accepts ANSI-encoded or DBCS-encoded URLs in requests.| |FavorUTF8|1|If non-zero, `http.sys` always tries to decode a URL as UTF-8 first; if that conversion fails and EnableNonUTF8 is non-zero, Http.sys then tries to decode it as ANSI or DBCS.

If zero (and EnableNonUTF8 is non-zero), `http.sys` tries to decode it as ANSI or DBCS; if that is not successful, it tries a UTF-8 conversion.| - When receives a request, it uses the converted URI from `http.sys` as input to the property. + When receives a request, it uses the converted URI from `http.sys` as input to the property. There is a need for supporting characters besides characters and numbers in URIs. An example is the following URI, which is used to retrieve customer information for customer number "1/3812": @@ -1824,12 +1824,12 @@ This is not the intent of the sender of the request. - If the property is set to false, then when the receives a request, it uses the raw URI instead of the converted URI from `http.sys` as input to the property. + If the property is set to false, then when the receives a request, it uses the raw URI instead of the converted URI from `http.sys` as input to the property. ## Examples - The following code example demonstrates using the property. + The following code example demonstrates using the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpListener/Overview/test.cs" id="Snippet15"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpListener/Overview/test.vb" id="Snippet15"::: @@ -1895,7 +1895,7 @@ ## Remarks If a client has followed a hyperlink to the requested URI, its request might contain a `Referrer` header that identifies the URI of the resource that contained the hyperlink. - Clients can falsify or choose not to present a header. Therefore, while the property can be useful for identifying basic trends in Web traffic; you should not use it as part of an authorization scheme to control access to data. + Clients can falsify or choose not to present a header. Therefore, while the property can be useful for identifying basic trends in Web traffic; you should not use it as part of an authorization scheme to control access to data. For a complete list of request headers, see the enumeration. @@ -2038,7 +2038,7 @@ property value. + The information returned by this property is also available in the property value. diff --git a/xml/System.Net/HttpListenerResponse.xml b/xml/System.Net/HttpListenerResponse.xml index 19a8210f153..28cd34dca5d 100644 --- a/xml/System.Net/HttpListenerResponse.xml +++ b/xml/System.Net/HttpListenerResponse.xml @@ -58,9 +58,9 @@ object, the request and response are made available to your application in an object. The request is represented by an object and is available in the property. The response is represented by an object and is available in the property. + When a client makes a request for a resource handled by an object, the request and response are made available to your application in an object. The request is represented by an object and is available in the property. The response is represented by an object and is available in the property. - You can customize the response by setting various properties, such as , , and . Use the property to obtain a instance to which response data can be written. Finally, send the response data to the client by calling the method. + You can customize the response by setting various properties, such as , , and . Use the property to obtain a instance to which response data can be written. Finally, send the response data to the client by calling the method. ]]> @@ -118,7 +118,7 @@ and objects. The connection to the client is also closed, regardless of the property value of the client request. + Calling this method on an object that has already been closed has no effect. If the response has not already been closed, this method closes it and the associated and objects. The connection to the client is also closed, regardless of the property value of the client request. ]]> @@ -174,9 +174,9 @@ method on the collection returned by the property. + Calling this method is equivalent to calling the method on the collection returned by the property. - If the header specified in `name` does not exist, this method inserts a new header into the property's collection. If `name` is present in the collection, this method replaces the existing value with `value`. To add a value to an existing header without replacing the existing value, use the method. + If the header specified in `name` does not exist, this method inserts a new header into the property's collection. If `name` is present in the collection, this method replaces the existing value with `value`. To add a value to an existing header without replacing the existing value, use the method. @@ -247,9 +247,9 @@ method on the collection returned by the property. + Calling this method is equivalent to calling the method on the collection returned by the property. - If the specified cookie does not exist in the property's collection, `cookie` is added. If the cookie exists in the collection, `cookie` replaces it. + If the specified cookie does not exist in the property's collection, `cookie` is added. If the cookie exists in the collection, `cookie` replaces it. @@ -315,9 +315,9 @@ method on the collection returned by the property. + Calling this method is equivalent to calling the method on the collection returned by the property. - If the header specified in `header` does not exist, this method inserts a new header into the property's collection. If `header` is present in the collection, this method adds `value` to the existing values. To replace the value of an existing header, use the method. + If the header specified in `header` does not exist, this method inserts a new header into the property's collection. If `header` is present in the collection, this method adds `value` to the existing values. To replace the value of an existing header, use the method. ]]> @@ -466,7 +466,7 @@ array instead of writing the body data to the property and calling the method. + If you are sending body data with the response, you can use this method to send it as a array instead of writing the body data to the property and calling the method. This method closes the response stream and the associated with the response. @@ -613,7 +613,7 @@ property. If you do not, the does not send the response data. + The `Content-Length` header expresses the length, in bytes, of the response's body data. When using a format that does not send the data chunked or raw, you must set the property. If you do not, the does not send the response data. For a complete list of response headers, see the enumeration. @@ -1021,7 +1021,7 @@ property must be set explicitly before writing to the returned object. + The property must be set explicitly before writing to the returned object. > [!NOTE] > Closing the request does not close the stream returned by this property. When you no longer need the stream, you should close it by calling the Close method. @@ -1156,7 +1156,7 @@ method is used to redirect a client to the new location for a resource. This method sets the response's `Location` header to `url`, the property to , and the property to "Found". + The method is used to redirect a client to the new location for a resource. This method sets the response's `Location` header to `url`, the property to , and the property to "Found". @@ -1225,7 +1225,7 @@ The `Location` header specifies the URL to which the client is directed to locate a requested resource. > [!NOTE] -> Setting this property does not automatically set the property. +> Setting this property does not automatically set the property. diff --git a/xml/System.Net/HttpWebRequest.xml b/xml/System.Net/HttpWebRequest.xml index 65822162aad..bb996b3336e 100644 --- a/xml/System.Net/HttpWebRequest.xml +++ b/xml/System.Net/HttpWebRequest.xml @@ -83,43 +83,43 @@ Do not use the constructor. Use the method to initialize new objects. If the scheme for the Uniform Resource Identifier (URI) is `http://` or `https://`, returns an object. - The method makes a synchronous request to the resource specified in the property and returns an that contains the response object. The response data can be received by using the stream returned by . If the response object or the response stream is closed, remaining data will be forfeited. The remaining data will be drained and the socket will be re-used for subsequent requests when closing the response object or stream if the following conditions hold: it's a keep-alive or pipelined request, only a small amount of data needs to be received, or the remaining data is received in a small time interval. If none of the mentioned conditions hold or the drain time is exceeded, the socket will be closed. For keep-alive or pipelined connections, we strongly recommend that the application reads the streams until EOF. This ensures that the socket will be re-used for subsequent requests resulting in better performance and less resources used. + The method makes a synchronous request to the resource specified in the property and returns an that contains the response object. The response data can be received by using the stream returned by . If the response object or the response stream is closed, remaining data will be forfeited. The remaining data will be drained and the socket will be re-used for subsequent requests when closing the response object or stream if the following conditions hold: it's a keep-alive or pipelined request, only a small amount of data needs to be received, or the remaining data is received in a small time interval. If none of the mentioned conditions hold or the drain time is exceeded, the socket will be closed. For keep-alive or pipelined connections, we strongly recommend that the application reads the streams until EOF. This ensures that the socket will be re-used for subsequent requests resulting in better performance and less resources used. When you want to send data to the resource, the method returns a object to use to send data. The and methods provide asynchronous access to the send data stream. For client authentication with , the client certificate must be installed in the My certificate store of the current user. - The class throws a when errors occur while accessing a resource. The property contains a value that indicates the source of the error. When is , the property contains the received from the resource. + The class throws a when errors occur while accessing a resource. The property contains a value that indicates the source of the error. When is , the property contains the received from the resource. - exposes common HTTP header values sent to the Internet resource as properties, set by methods, or set by the system; the following table contains a complete list. You can set other headers in the property as name/value pairs. Note that servers and caches may change or add headers during the request. + exposes common HTTP header values sent to the Internet resource as properties, set by methods, or set by the system; the following table contains a complete list. You can set other headers in the property as name/value pairs. Note that servers and caches may change or add headers during the request. The following table lists the HTTP headers that are set either by properties or methods or the system. |Header|Set by| |------------|------------| -|`Accept`|Set by the property.| -|`Connection`|Set by the property, property.| -|`Content-Length`|Set by the property.| -|`Content-Type`|Set by the property.| -|`Expect`|Set by the property.| +|`Accept`|Set by the property.| +|`Connection`|Set by the property, property.| +|`Content-Length`|Set by the property.| +|`Content-Type`|Set by the property.| +|`Expect`|Set by the property.| |`Date`|Set by the system to current date.| |`Host`|Set by the system to current host information.| -|`If-Modified-Since`|Set by the property.| +|`If-Modified-Since`|Set by the property.| |`Range`|Set by the method.| -|`Referer`|Set by the property.| -|`Transfer-Encoding`|Set by the property (the property must be `true`).| -|`User-Agent`|Set by the property.| +|`Referer`|Set by the property.| +|`Transfer-Encoding`|Set by the property (the property must be `true`).| +|`User-Agent`|Set by the property.| > [!NOTE] > is registered automatically. You do not need to call the method to register before using URIs beginning with `http://` or `https://`. - The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the instance will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the class uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. + The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the instance will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the class uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. > [!NOTE] > The Framework caches SSL sessions as they are created and attempts to reuse a cached session for a new request, if possible. When attempting to reuse an SSL session, the Framework uses the first element of (if there is one), or tries to reuse an anonymous sessions if is empty. > [!NOTE] -> For security reasons, cookies are disabled by default. If you want to use cookies, use the property to enable cookies. +> For security reasons, cookies are disabled by default. If you want to use cookies, use the property to enable cookies. For apps that use TLS/SSL through APIs such as HttpClient, HttpWebRequest, FTPClient, SmtpClient, and SsStream, .NET blocks insecure cipher and hashing algorithms for connections by default. You might need to opt out of this behavior to maintain interoperability with existing SSL3 services OR TLS w/ RC4 services. [Cannot connect to a server by using the ServicePointManager or SslStream APIs after upgrade to the .NET Framework 4.6](https://support.microsoft.com/kb/3069494) explains how to modify your code to disable this behavior, if necessary. @@ -331,7 +331,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The method cancels a request to a resource. After a request is canceled, calling the , , , , , or method causes a with the property set to . + The method cancels a request to a resource. After a request is canceled, calling the , , , , , or method causes a with the property set to . The method will synchronously execute the callback specified to the or methods if the method is called while either of these operations are outstanding. This can lead to potential deadlock issues. @@ -406,7 +406,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - To clear the `Accept` HTTP header, set the property to `null`. + To clear the `Accept` HTTP header, set the property to `null`. > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. @@ -414,7 +414,7 @@ Both constructors are obsolete and should not b ## Examples - The following code example sets the property. + The following code example sets the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Accept/httpwebrequest_accept.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Accept/httpwebrequest_accept.vb" id="Snippet1"::: @@ -1250,9 +1250,9 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property is set to the URI after any redirections that happen during the request are complete. + The property is set to the URI after any redirections that happen during the request are complete. - The URI of the original request is kept in the property. + The URI of the original request is kept in the property. @@ -1319,7 +1319,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Set to `true` if you want the request to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. + Set to `true` if you want the request to automatically follow HTTP redirection headers to the new location of the resource. The maximum number of redirections to follow is set by the property. If is set to `false`, all responses with an HTTP status code from 300 to 399 is returned to the application. @@ -1328,7 +1328,7 @@ Both constructors are obsolete and should not b ## Examples - The following code example uses the property to allow the request to follow redirection responses. + The following code example uses the property to allow the request to follow redirection responses. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/AllowAutoRedirect/httpwebrequest_allowautoredirect.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/AllowAutoRedirect/httpwebrequest_allowautoredirect.vb" id="Snippet2"::: @@ -1438,7 +1438,7 @@ Both constructors are obsolete and should not b When is `true`, the data is buffered in memory so it is ready to be resent in the event of redirections or authentication requests. ## Examples - The following code example uses the property to disable data buffering. + The following code example uses the property to disable data buffering. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/AllowWriteStreamBuffering/httpwebrequest_allowwritestreambuffering.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/AllowWriteStreamBuffering/httpwebrequest_allowwritestreambuffering.vb" id="Snippet1"::: @@ -1660,7 +1660,7 @@ Both constructors are obsolete and should not b The method starts an asynchronous request for a response from the Internet resource. The asynchronous callback method uses the method to return the actual . - A is thrown in several cases when the properties set on the class are conflicting. This exception occurs if an application sets the property and the property to `true`, and then sends an HTTP GET request. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.0 protocol, where this is not supported. This exception occurs if an application tries to send data without setting the property or the is `false` when buffering is disabled and on a keepalive connection (the property is `true`)`.` + A is thrown in several cases when the properties set on the class are conflicting. This exception occurs if an application sets the property and the property to `true`, and then sends an HTTP GET request. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.0 protocol, where this is not supported. This exception occurs if an application tries to send data without setting the property or the is `false` when buffering is disabled and on a keepalive connection (the property is `true`)`.` If a is thrown, use the and properties of the exception to determine the response from the server. @@ -1838,11 +1838,11 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The request sends the property to the Internet resource as the `Connection` HTTP header. If the value of the property is `true`, the value "Keep-alive" is appended to the end of the `Connection` header. + The request sends the property to the Internet resource as the `Connection` HTTP header. If the value of the property is `true`, the value "Keep-alive" is appended to the end of the `Connection` header. - To clear the `Connection` HTTP header, set the property to `null`. + To clear the `Connection` HTTP header, set the property to `null`. - Changing the property after the request has been started by calling the , , , or method throws an . + Changing the property after the request has been started by calling the , , , or method throws an . > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. @@ -1850,7 +1850,7 @@ Both constructors are obsolete and should not b ## Examples - The following code example uses the property to set the value of the Connection HTTP Header. + The following code example uses the property to set the value of the Connection HTTP Header. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Connection/httpwebrequest_connection.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Connection/httpwebrequest_connection.vb" id="Snippet1"::: @@ -1920,7 +1920,7 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property enables you to associate a request with a connection group. This is useful when your application makes requests to one server for different users, such as a web site that retrieves customer information from a database server. + The property enables you to associate a request with a connection group. This is useful when your application makes requests to one server for different users, such as a web site that retrieves customer information from a database server. ]]> @@ -1987,11 +1987,11 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains the value to send as the `Content-length` HTTP header with the request. + The property contains the value to send as the `Content-length` HTTP header with the request. - Any value other than -1 in the property indicates that the request uploads data and that only methods that upload data are allowed to be set in the property. + Any value other than -1 in the property indicates that the request uploads data and that only methods that upload data are allowed to be set in the property. - After the property is set to a value, that number of bytes must be written to the request stream that is returned by calling the method or both the and the methods. + After the property is set to a value, that number of bytes must be written to the request stream that is returned by calling the method or both the and the methods. > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. @@ -1999,7 +1999,7 @@ Both constructors are obsolete and should not b ## Examples - The following code example sets the property to the length of the string being posted. + The following code example sets the property to the length of the string being posted. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.vb" id="Snippet4"::: @@ -2067,9 +2067,9 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains the media type of the request. Values assigned to the property replace any existing contents when the request sends the `Content-type` HTTP header. + The property contains the media type of the request. Values assigned to the property replace any existing contents when the request sends the `Content-type` HTTP header. - To clear the `Content-type` HTTP header, set the property to `null`. + To clear the `Content-type` HTTP header, set the property to `null`. > [!NOTE] > The value for this property is stored in . If is set, the property value is lost. @@ -2077,7 +2077,7 @@ Both constructors are obsolete and should not b ## Examples - The following code example sets the property. + The following code example sets the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.vb" id="Snippet1"::: @@ -2146,9 +2146,9 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property specifies the callback method to call when the client receives a 100-Continue response. + The property specifies the callback method to call when the client receives a 100-Continue response. - When the property is set, the client calls the delegate whenever protocol responses of type (100) are received. This is useful if you want the client to display the status of the data being received from the Internet resource. + When the property is set, the client calls the delegate whenever protocol responses of type (100) are received. This is useful if you want the client to display the status of the data being received from the Internet resource. ]]> @@ -2273,12 +2273,12 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property provides an instance of the class that contains the cookies associated with this request. + The property provides an instance of the class that contains the cookies associated with this request. - is `null` by default. You must assign a object to the property to have cookies returned in the property of the returned by the method. + is `null` by default. You must assign a object to the property to have cookies returned in the property of the returned by the method. > [!NOTE] -> For security reasons, cookies are disabled by default. If you want to use cookies, use the property to enable cookies. +> For security reasons, cookies are disabled by default. If you want to use cookies, use the property to enable cookies. @@ -2354,11 +2354,11 @@ Both constructors are obsolete and should not b [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains authentication information to identify the maker of the request. The property can be either a , in which case the user, password, and domain information contained in the object is used to authenticate the request, or it can be a , in which case the Uniform Resource Identifier (URI) of the request is used to determine the user, password, and domain information to use to authenticate the request. + The property contains authentication information to identify the maker of the request. The property can be either a , in which case the user, password, and domain information contained in the object is used to authenticate the request, or it can be a , in which case the Uniform Resource Identifier (URI) of the request is used to determine the user, password, and domain information to use to authenticate the request. - In most client scenarios, you should use the property, which contains the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. + In most client scenarios, you should use the property, which contains the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. - If the class is being used in a middle-tier application, such as an ASP.NET application, the credentials in the property belong to the account running the ASP page (the server-side credentials). Typically, you would set this property to the credentials of the client on whose behalf the request is made. + If the class is being used in a middle-tier application, such as an ASP.NET application, the credentials in the property belong to the account running the ASP page (the server-side credentials). Typically, you would set this property to the credentials of the client on whose behalf the request is made. > [!NOTE] > The NTLM authentication scheme cannot be used to impersonate another user. Kerberos must be specially configured to support impersonation. @@ -2438,13 +2438,13 @@ Both constructors are obsolete and should not b If the Date header is `null`, then the return value will be set to . - The property is a standard object and can contain a field of , , or . Any kind of time can be set when using the property. If is set or retrieved, the property is assumed to be (local time). + The property is a standard object and can contain a field of , , or . Any kind of time can be set when using the property. If is set or retrieved, the property is assumed to be (local time). - The classes in the namespace always write it out the property on the wire during transmission in standard form using GMT (Utc) format. + The classes in the namespace always write it out the property on the wire during transmission in standard form using GMT (Utc) format. - If the property is set to , then the `Date` HTTP header is removed from the property and the . + If the property is set to , then the `Date` HTTP header is removed from the property and the . - If the property is , this indicates that the `Date` HTTP header is not included in the property and the . + If the property is , this indicates that the `Date` HTTP header is not included in the property and the . > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. @@ -2505,7 +2505,7 @@ Both constructors are obsolete and should not b Setting this property registers the specified policy for the HTTP and HTTPS schemes. This policy is used for this request if: - There is no property specified for this request. + There is no property specified for this request. -or- @@ -2619,7 +2619,7 @@ Both constructors are obsolete and should not b The length of the response header received the response status line and any extra control characters that are received as part of HTTP protocol. A value of 0 means that all requests fail. - This value can also be changed in the configuration file. The impact of this property can be overridden by setting the property on an instance of the class. + This value can also be changed in the configuration file. The impact of this property can be overridden by setting the property on an instance of the class. ]]> @@ -2693,7 +2693,7 @@ Both constructors are obsolete and should not b The method completes an asynchronous request for a stream that was started by the method. After the object has been returned, you can send data with the by using the method. > [!NOTE] -> - You must set the value of the property before writing data to the stream. +> - You must set the value of the property before writing data to the stream. > - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. > - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -2788,7 +2788,7 @@ Both constructors are obsolete and should not b Some applications that use integrated Windows authentication with extended protection may need to be able to query the transport layer used by in order to retrieve the channel binding token (CBT) from the underlying TLS channel. The method provides access to this information for HTTP methods which have a request body (`POST` and `PUT` requests). This is only needed if the application is implementing its own authentication and needs access to the CBT. > [!NOTE] -> - If you need to set the value of the property before writing data to the stream. +> - If you need to set the value of the property before writing data to the stream. > - You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. > - This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -3125,7 +3125,7 @@ The GetHashCode method returns a hash code of the web request. This value can be The method returns a stream to use to send data for the . After the object has been returned, you can send data with the by using the method. - If an application needs to set the value of the property, then this must be done before retrieving the stream. + If an application needs to set the value of the property, then this must be done before retrieving the stream. You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. @@ -3234,7 +3234,7 @@ The GetHashCode method returns a hash code of the web request. This value can be Some applications that use integrated Windows authentication with extended protection may need to be able to query the transport layer used by in order to retrieve the channel binding token (CBT) from the underlying TLS channel. The method provides access to this information for HTTP methods which have a request body (`POST` and `PUT` requests). This is only needed if the application is implementing its own authentication and needs access to the CBT. - If an application needs to set the value of the property, then this must be done before retrieving the stream. + If an application needs to set the value of the property, then this must be done before retrieving the stream. You must call the method to close the stream and release the connection for reuse. Failure to close the stream causes your application to run out of connections. @@ -3327,7 +3327,7 @@ The GetHashCode method returns a hash code of the web request. This value can be The method returns a object that contains the response from the Internet resource. The actual instance returned is an , and can be typecast to that class to access HTTP-specific properties. - A is thrown in several cases when the properties set on the class are conflicting. This exception occurs if an application sets the property and the property to `true`, and then sends an HTTP GET request. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.0 protocol, where this is not supported. This exception occurs if an application tries to send data without setting the property or the is `false` when buffering is disabled and on a keepalive connection (the property is `true`)`.` + A is thrown in several cases when the properties set on the class are conflicting. This exception occurs if an application sets the property and the property to `true`, and then sends an HTTP GET request. This exception occurs if an application tries to send chunked to a server that only supports HTTP 1.0 protocol, where this is not supported. This exception occurs if an application tries to send data without setting the property or the is `false` when buffering is disabled and on a keepalive connection (the property is `true`)`.` > [!CAUTION] > You must call the method to close the stream and release the connection. Failure to do so may cause your application to run out of connections. @@ -3347,7 +3347,7 @@ The GetHashCode method returns a hash code of the web request. This value can be > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in the .NET Framework](/dotnet/framework/network-programming/network-tracing). > [!NOTE] -> For security reasons, cookies are disabled by default. If you wish to use cookies, use the property to enable cookies. +> For security reasons, cookies are disabled by default. If you wish to use cookies, use the property to enable cookies. @@ -3444,7 +3444,7 @@ The GetHashCode method returns a hash code of the web request. This value can be property to determine if a response has been received from an Internet resource. + The following code example checks the property to determine if a response has been received from an Internet resource. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/HaveResponse/httpwebrequest_haveresponse.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/HaveResponse/httpwebrequest_haveresponse.vb" id="Snippet1"::: @@ -3517,29 +3517,29 @@ The GetHashCode method returns a hash code of the web request. This value can be |Header|Set by| |------------|------------| -|Accept|Set by the property.| -|Connection|Set by the property and property.| -|Content-Length|Set by the property.| -|Content-Type|Set by the property.| -|Expect|Set by the property.| -|Date|Set by the property.| -|Host|Set by the property.| -|If-Modified-Since|Set by the property.| +|Accept|Set by the property.| +|Connection|Set by the property and property.| +|Content-Length|Set by the property.| +|Content-Type|Set by the property.| +|Expect|Set by the property.| +|Date|Set by the property.| +|Host|Set by the property.| +|If-Modified-Since|Set by the property.| |Range|Set by the method.| -|Referer|Set by the property.| -|Transfer-Encoding|Set by the property (the property must be true).| -|User-Agent|Set by the property.| +|Referer|Set by the property.| +|Transfer-Encoding|Set by the property (the property must be true).| +|User-Agent|Set by the property.| The method throws an if you try to set one of these protected headers. - Changing the property after the request has been started by calling , , , or method throws an . + Changing the property after the request has been started by calling , , , or method throws an . You should not assume that the header values will remain unchanged, because Web servers and caches may change or add headers to a Web request. ## Examples - The following code example uses the property to print the HTTP header name/value pairs to the console. + The following code example uses the property to print the HTTP header name/value pairs to the console. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Headers/httpwebrequest_headers.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Headers/httpwebrequest_headers.vb" id="Snippet1"::: @@ -3602,15 +3602,15 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property can be used to set the Host header value to use in an HTTP request independent from the request URI. The property can consist of a hostname and an optional port number. A Host header without port information implies the default port for the service requested (port 80 for an HTTP URL, for example). + The property can be used to set the Host header value to use in an HTTP request independent from the request URI. The property can consist of a hostname and an optional port number. A Host header without port information implies the default port for the service requested (port 80 for an HTTP URL, for example). - The format for specifying a host and port must follow the rules in section 14.23 of RFC2616 published by the IETF. An example complying with these requirements that specifies a port of 8080 would be the following value for the property: + The format for specifying a host and port must follow the rules in section 14.23 of RFC2616 published by the IETF. An example complying with these requirements that specifies a port of 8080 would be the following value for the property: `www.contoso.com:8080` - Using the property to explicitly specify a custom Host header value also affects areas caching, cookies, and authentication. When an application provides credentials for a specific URI prefix, the applications needs to make sure to use the URI containing the value of the Host header, not the target server in the URI. The key used when caching resources, uses the Host header value rather than the request URI. Cookies are stored in a and logically grouped by the server domain name. If the application specifies a Host header, then this value will be used as domain. + Using the property to explicitly specify a custom Host header value also affects areas caching, cookies, and authentication. When an application provides credentials for a specific URI prefix, the applications needs to make sure to use the URI containing the value of the Host header, not the target server in the URI. The key used when caching resources, uses the Host header value rather than the request URI. Cookies are stored in a and logically grouped by the server domain name. If the application specifies a Host header, then this value will be used as domain. - If the property is not set, then the Host header value to use in an HTTP request is based on the request URI. + If the property is not set, then the Host header value to use in an HTTP request is based on the request URI. ]]> @@ -3680,23 +3680,23 @@ The GetHashCode method returns a hash code of the web request. This value can be If the `If-Modified-Since` header is `null`, then the return value will be set to . - The property is a standard object and can contain a field of , , or . Any kind of time can be set when using the property. If is set or retrieved, the property is assumed to be (local time). + The property is a standard object and can contain a field of , , or . Any kind of time can be set when using the property. If is set or retrieved, the property is assumed to be (local time). - The classes in the namespace always write it out the property on the wire during transmission in standard form using GMT (Utc) format. + The classes in the namespace always write it out the property on the wire during transmission in standard form using GMT (Utc) format. - If the property is set to , then the `If-Modified-Since` HTTP header is removed from the property and the . + If the property is set to , then the `If-Modified-Since` HTTP header is removed from the property and the . - If the property is , this indicates that the `If-Modified-Since` HTTP header is not included in the property and the . + If the property is , this indicates that the `If-Modified-Since` HTTP header is not included in the property and the . > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. - If the property is set and 304 (Not Modified) status code is returned, then a will be thrown by the , , and methods. + If the property is set and 304 (Not Modified) status code is returned, then a will be thrown by the , , and methods. ## Examples - The following code example checks the property. + The following code example checks the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/IfModifiedSince/httpwebrequest_ifmodifiedsince.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/IfModifiedSince/httpwebrequest_ifmodifiedsince.vb" id="Snippet1"::: @@ -3765,7 +3765,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Set this property to `true` to send a `Connection` HTTP header with the value Keep-alive. An application uses to indicate a preference for persistent connections. When the property is `true`, the application makes persistent connections to the servers that support them. + Set this property to `true` to send a `Connection` HTTP header with the value Keep-alive. An application uses to indicate a preference for persistent connections. When the property is `true`, the application makes persistent connections to the servers that support them. > [!NOTE] > When using HTTP/1.1, Keep-Alive is on by default. Setting to `false` may result in sending a `Connection: Close` header to the server. @@ -3773,7 +3773,7 @@ The GetHashCode method returns a hash code of the web request. This value can be ## Examples - The following code example sets the property to `false` to avoid establishing a persistent connection with the Internet resource. + The following code example sets the property to `false` to avoid establishing a persistent connection with the Internet resource. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Connection/httpwebrequest_connection.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Connection/httpwebrequest_connection.vb" id="Snippet1"::: @@ -3837,7 +3837,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property sets the maximum number of redirections for the request to follow if the property is `true`. + The property sets the maximum number of redirections for the request to follow if the property is `true`. @@ -3909,9 +3909,9 @@ The GetHashCode method returns a hash code of the web request. This value can be The length of the response header includes the response status line and any extra control characters that are received as part of HTTP protocol. A value of 0 means that all requests fail. - If the property is not explicitly set, it defaults to the value of the property. + If the property is not explicitly set, it defaults to the value of the property. - If the length of the response header received exceeds the value of the property, the or methods will throw a with the property set to . + If the length of the response header received exceeds the value of the property, the or methods will throw a with the property set to . @@ -3987,7 +3987,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The value of the property affects the property. When you set the in the request, the corresponding media type is chosen from the list of character sets returned in the response `Content-type` HTTP header. + The value of the property affects the property. When you set the in the request, the corresponding media type is chosen from the list of character sets returned in the response `Content-type` HTTP header. ]]> @@ -4049,14 +4049,14 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property can be set to any of the HTTP 1.1 protocol verbs: GET, HEAD, POST, PUT, DELETE, TRACE, or OPTIONS. + The property can be set to any of the HTTP 1.1 protocol verbs: GET, HEAD, POST, PUT, DELETE, TRACE, or OPTIONS. - If the property is set to any value other than -1, the property must be set to a protocol property that uploads data. + If the property is set to any value other than -1, the property must be set to a protocol property that uploads data. ## Examples - The following code example sets the property to POST. + The following code example sets the property to POST. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ContentLength/httpwebrequest_contentlength.vb" id="Snippet4"::: @@ -4130,14 +4130,14 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - An application uses the property to indicate a preference for pipelined connections. When is `true`, an application makes pipelined connections to the servers that support them. + An application uses the property to indicate a preference for pipelined connections. When is `true`, an application makes pipelined connections to the servers that support them. - Pipelined connections are made only when the property is also `true`. + Pipelined connections are made only when the property is also `true`. ## Examples - The following code example prints the value of the property to the console. + The following code example prints the value of the property to the console. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Pipelined/httpwebrequest_pipelined.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Pipelined/httpwebrequest_pipelined.vb" id="Snippet1"::: @@ -4232,7 +4232,7 @@ The GetHashCode method returns a hash code of the web request. This value can be If the client request to a specific is not successfully authenticated, the request uses standard authentication procedures. - With the exception of the first request, the property indicates whether to send authentication information with subsequent requests to a that matches the specific up to the last forward slash without waiting to be challenged by the server. + With the exception of the first request, the property indicates whether to send authentication information with subsequent requests to a that matches the specific up to the last forward slash without waiting to be challenged by the server. The following dialog between client and server illustrates the effect of this property. The dialog assumes that basic authentication is in use. @@ -4335,7 +4335,7 @@ The GetHashCode method returns a hash code of the web request. This value can be ## Examples - The following code example sets the Property. + The following code example sets the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ProtocolVersion/httpwebrequest_protocolversion.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ProtocolVersion/httpwebrequest_protocolversion.vb" id="Snippet1"::: @@ -4395,9 +4395,9 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. + The property identifies the object to use to process requests to Internet resources. To specify that no proxy should be used, set the property to the proxy instance returned by the method. - The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the instance will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the class uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. + The local computer or application config file may specify that a default proxy be used. If the property is specified, then the proxy settings from the property override the local computer or application config file and the instance will use the proxy settings specified. If no proxy is specified in a config file and the property is unspecified, the class uses the proxy settings inherited from Internet options on the local computer. If there are no proxy settings in Internet options, the request is sent directly to the server. The class supports local proxy bypass. The class considers a destination to be local if any of the following conditions are met: @@ -4407,7 +4407,7 @@ The GetHashCode method returns a hash code of the web request. This value can be - The domain suffix of the destination matches the local computer's domain suffix (). - Changing the property after the request has been started by calling the , , , or method throws an . For information on the proxy element see [\<defaultProxy\> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/defaultproxy-element-network-settings). + Changing the property after the request has been started by calling the , , , or method throws an . For information on the proxy element see [\<defaultProxy\> Element (Network Settings)](/dotnet/framework/configure-apps/file-schema/network/defaultproxy-element-network-settings). @@ -4484,16 +4484,16 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property is used when writing to the stream returned by the method or reading from the stream returned by the method. + The property is used when writing to the stream returned by the method or reading from the stream returned by the method. - Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. + Specifically, the property controls the time-out for the method, which is used to read the stream returned by the method, and for the method, which is used to write to the stream returned by the method. - To specify the amount of time to wait for the request to complete, use the property. + To specify the amount of time to wait for the request to complete, use the property. ## Examples - The following code example shows how to set the property. + The following code example shows how to set the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Overview/source.cs" id="Snippet2"::: @@ -4560,7 +4560,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - To clear the `Referer` HTTP header, set the property to `null`. + To clear the `Referer` HTTP header, set the property to `null`. > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. @@ -4568,7 +4568,7 @@ The GetHashCode method returns a hash code of the web request. This value can be ## Examples - The following code example sets the property. + The following code example sets the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Referer/httpwebrequest_referer.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Referer/httpwebrequest_referer.vb" id="Snippet1"::: @@ -4639,7 +4639,7 @@ The GetHashCode method returns a hash code of the web request. This value can be The object passed to by the call to . - Following a redirection header does not change the property. To get the actual URI that responded to the request, examine the property. + Following a redirection header does not change the property. To get the actual URI that responded to the request, examine the property. @@ -4705,12 +4705,12 @@ The GetHashCode method returns a hash code of the web request. This value can be When is `true`, the request sends data to the Internet resource in segments. The Internet resource must support receiving chunked data. - Changing the property after the request has been started by calling the , , , or method throws an . + Changing the property after the request has been started by calling the , , , or method throws an . ## Examples - The following code example sets the property to `true` so that data can be sent in segments to the Internet resource. + The following code example sets the property to `true` so that data can be sent in segments to the Internet resource. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/SendChunked/httpwebrequest_sendchunked.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/SendChunked/httpwebrequest_sendchunked.vb" id="Snippet2"::: @@ -4768,7 +4768,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The default is that no callback function is set and the property is `null`. + The default is that no callback function is set and the property is `null`. ]]> @@ -4833,7 +4833,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property may be different from if the request is redirected. + The property may be different from if the request is redirected. @@ -5021,23 +5021,23 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - is the number of milliseconds that a subsequent synchronous request made with the method waits for a response, and the method waits for a stream. The applies to the entire request and response, not individually to the and method calls. If the resource is not returned within the time-out period, the request throws a with the property set to . + is the number of milliseconds that a subsequent synchronous request made with the method waits for a response, and the method waits for a stream. The applies to the entire request and response, not individually to the and method calls. If the resource is not returned within the time-out period, the request throws a with the property set to . - The property must be set before the or method is called. Changing the property after calling the or method has no effect + The property must be set before the or method is called. Changing the property after calling the or method has no effect - The property has no effect on asynchronous requests made with the or method. + The property has no effect on asynchronous requests made with the or method. > [!CAUTION] > In the case of asynchronous requests, the client application implements its own time-out mechanism. Refer to the example in the method. - To specify the amount of time to wait before a read or write operation times out, use the property. + To specify the amount of time to wait before a read or write operation times out, use the property. A Domain Name System (DNS) query may take up to 15 seconds to return or time out. If your request contains a host name that requires resolution and you set to a value less than 15 seconds, it may take 15 seconds or more before a is thrown to indicate a timeout on your request. ## Examples - The following code example sets the property of the object. + The following code example sets the property of the object. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/Timeout/httpwebrequest_timeout.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/Timeout/httpwebrequest_timeout.vb" id="Snippet1"::: @@ -5098,9 +5098,9 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Before you can set the property, you must first set the property to `true`. Clearing by setting it to `null` has no effect on the value of . + Before you can set the property, you must first set the property to `true`. Clearing by setting it to `null` has no effect on the value of . - Values assigned to the property replace any existing contents. + Values assigned to the property replace any existing contents. > [!NOTE] > The value for this property is stored in . If WebHeaderCollection is set, the property value is lost. @@ -5172,9 +5172,9 @@ The GetHashCode method returns a hash code of the web request. This value can be You may want to consider enabling this mechanism if your are having performance problems and your application is running on a Web server with integrated Windows authentication. - Enabling this setting opens the system to security risks. If you set the property to `true` be sure to take the following precautions: + Enabling this setting opens the system to security risks. If you set the property to `true` be sure to take the following precautions: -- Use the property to manage connections for different users. This avoids the potential use of the connection by non-authenticated applications. For example, user A should have a unique connection group name that is different from user B. This provides a layer of isolation for each user account. +- Use the property to manage connections for different users. This avoids the potential use of the connection by non-authenticated applications. For example, user A should have a unique connection group name that is different from user B. This provides a layer of isolation for each user account. - Run your application in a protected environment to help avoid possible connection exploits. @@ -5237,7 +5237,7 @@ The GetHashCode method returns a hash code of the web request. This value can be [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Set this property to `true` when requests made by this 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. + Set this property to `true` when requests made by this 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. ]]> @@ -5303,7 +5303,7 @@ The GetHashCode method returns a hash code of the web request. This value can be The value for this property is stored in . If `WebHeaderCollection` is set, the property value is lost. ## Examples - The following code example sets the property. + The following code example sets the property. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/UserAgent/httpwebrequest_useragent.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/UserAgent/httpwebrequest_useragent.vb" id="Snippet1"::: diff --git a/xml/System.Net/HttpWebResponse.xml b/xml/System.Net/HttpWebResponse.xml index 949c04e5b81..188cd4281de 100644 --- a/xml/System.Net/HttpWebResponse.xml +++ b/xml/System.Net/HttpWebResponse.xml @@ -91,7 +91,7 @@ You should never directly create an instance of the class. Instead, use the instance returned by a call to . You must call either the or the method to close the response and release the connection for reuse. It is not necessary to call both and , but doing so does not cause an error. - Common header information returned from the Internet resource is exposed as properties of the class. See the following table for a complete list. Other headers can be read from the property as name/value pairs. + Common header information returned from the Internet resource is exposed as properties of the class. See the following table for a complete list. Other headers can be read from the property as name/value pairs. The following table shows the common HTTP headers that are available through properties of the class. @@ -313,7 +313,7 @@ The contents of the response from the Internet resource are returned as a property contains a value that describes the character set of the response. This character set information is taken from the header returned with the response. + The property contains a value that describes the character set of the response. This character set information is taken from the header returned with the response. @@ -442,12 +442,12 @@ The contents of the response from the Internet resource are returned as a property contains the value of the Content-Encoding header returned with the response. + The property contains the value of the Content-Encoding header returned with the response. ## Examples - The following example uses the property to obtain the value of the Content-Encoding header returned with the response. + The following example uses the property to obtain the value of the Content-Encoding header returned with the response. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/CharacterSet/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebResponse/CharacterSet/source.vb" id="Snippet1"::: @@ -504,7 +504,7 @@ The contents of the response from the Internet resource are returned as a property contains the value of the Content-Length header returned with the response. If the Content-Length header is not set in the response, is set to the value -1. + The property contains the value of the Content-Length header returned with the response. If the Content-Length header is not set in the response, is set to the value -1. @@ -566,7 +566,7 @@ The contents of the response from the Internet resource are returned as a property contains the value of the Content-Type header returned with the response. + The property contains the value of the Content-Type header returned with the response. @@ -635,9 +635,9 @@ The contents of the response from the Internet resource are returned as a property provides an instance of the class that holds the cookies associated with this response. + The property provides an instance of the class that holds the cookies associated with this response. - If the property of the associated is `null`, the property will also be `null`. Any cookie information sent by the server will be available in the property, however. + If the property of the associated is `null`, the property will also be `null`. Any cookie information sent by the server will be available in the property, however. @@ -1015,7 +1015,7 @@ The GetHashCode method returns a hash code of the web response instance. This va property is a collection of name/value pairs that contain the HTTP header values returned with the response. Common header information returned from the Internet resource is exposed as properties of the class. The following table lists common headers that the API exposes as properties. + The property is a collection of name/value pairs that contain the HTTP header values returned with the response. Common header information returned from the Internet resource is exposed as properties of the class. The following table lists common headers that the API exposes as properties. |Header|Property| |------------|--------------| @@ -1084,7 +1084,7 @@ The GetHashCode method returns a hash code of the web response instance. This va property. + You can specify mutual authentication using the property. ]]> @@ -1137,7 +1137,7 @@ The GetHashCode method returns a hash code of the web response instance. This va property contains the value of the Last-Modified header received with the response. The date and time are assumed to be local time. + The property contains the value of the Last-Modified header received with the response. The date and time are assumed to be local time. @@ -1263,7 +1263,7 @@ The GetHashCode method returns a hash code of the web response instance. This va property contains the HTTP protocol version number of the response sent by the Internet resource. + The property contains the HTTP protocol version number of the response sent by the Internet resource. @@ -1325,11 +1325,11 @@ The GetHashCode method returns a hash code of the web response instance. This va property contains the URI of the Internet resource that actually responded to the request. This URI might not be the same as the originally requested URI, if the original server redirected the request. + The property contains the URI of the Internet resource that actually responded to the request. This URI might not be the same as the originally requested URI, if the original server redirected the request. - The property will use the Content-Location header if present. + The property will use the Content-Location header if present. - Applications that need to access the last redirected should use the property rather than , since the use of property may open security vulnerabilities. + Applications that need to access the last redirected should use the property rather than , since the use of property may open security vulnerabilities. @@ -1390,12 +1390,12 @@ The GetHashCode method returns a hash code of the web response instance. This va property contains the value of the Server header returned with the response. + The property contains the value of the Server header returned with the response. ## Examples - The following example uses the property to display the Web server's name to the console. + The following example uses the property to display the Web server's name to the console. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebResponse/Method/httpwebresponse_method_server.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebResponse/Method/httpwebresponse_method_server.vb" id="Snippet2"::: diff --git a/xml/System.Net/IAuthenticationModule.xml b/xml/System.Net/IAuthenticationModule.xml index 57ae321108d..ea1d80f5ef6 100644 --- a/xml/System.Net/IAuthenticationModule.xml +++ b/xml/System.Net/IAuthenticationModule.xml @@ -57,7 +57,7 @@ ## Examples The following example creates a customized authentication class by implementing the interface. For a complete example refer to the class. - + :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationManager/Overview/custombasicauthentication.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationManager/Overview/custombasicauthentication.vb" id="Snippet6"::: @@ -184,12 +184,12 @@ property identifies the authentication type implemented by this authentication module. The property is used by the method to determine if the authentication module has been registered, and by the method to remove a registered authentication module. + The property identifies the authentication type implemented by this authentication module. The property is used by the method to determine if the authentication module has been registered, and by the method to remove a registered authentication module. ## Examples - The following example shows how to use the property. For a complete example refer to the class. + The following example shows how to use the property. For a complete example refer to the class. :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationManager/Overview/custombasicauthentication.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationManager/Overview/custombasicauthentication.vb" id="Snippet7"::: @@ -242,12 +242,12 @@ property is set to `true` to indicate that the authentication module can respond with a valid instance when the method is called. + The property is set to `true` to indicate that the authentication module can respond with a valid instance when the method is called. ## Examples - The following example shows how to use the property. For a complete example refer to the class. + The following example shows how to use the property. For a complete example refer to the class. :::code language="csharp" source="~/snippets/csharp/System.Net/AuthenticationManager/Overview/custombasicauthentication.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/AuthenticationManager/Overview/custombasicauthentication.vb" id="Snippet7"::: @@ -315,7 +315,7 @@ property is `true`, the method will return an instance of the class containing an authentication message. + When the property is `true`, the method will return an instance of the class containing an authentication message. diff --git a/xml/System.Net/ICredentialPolicy.xml b/xml/System.Net/ICredentialPolicy.xml index 781730e1959..e3e27714cc5 100644 --- a/xml/System.Net/ICredentialPolicy.xml +++ b/xml/System.Net/ICredentialPolicy.xml @@ -51,7 +51,7 @@ > [!NOTE] > policies are invoked only if the or the that is associated with the request has credentials that are not `null`. Setting this policy has no effect on requests that do not specify credentials. - Use the property to set an policy. The that handles authentication for the request will invoke the method before performing the authentication. If the method returns `false`, authentication is not performed. + Use the property to set an policy. The that handles authentication for the request will invoke the method before performing the authentication. If the method returns `false`, authentication is not performed. An policy affects all instances of with non-null credentials in the current application domain. The policy cannot be overridden on individual requests. @@ -59,7 +59,7 @@ ## Examples The following code example shows an implementation of this interface that permits credentials to be sent only for requests that target specific hosts. - + :::code language="csharp" source="~/snippets/csharp/Microsoft.Win32/IntranetZoneCredentialPolicy/Overview/websample.cs" id="Snippet3"::: ]]> @@ -119,7 +119,7 @@ policy has been specified by setting the property, the that handles authentication for a invokes the method before performing the authentication. If this method returns `false`, authentication is not performed. + After an policy has been specified by setting the property, the that handles authentication for a invokes the method before performing the authentication. If this method returns `false`, authentication is not performed. When the original request has been redirected or proxy authentication is required, the resource identified by `challengeUri` can be different from the requested resource that is specified in . In the case of redirection, `challengeUri` contains the actual destination . If proxy authentication is required, `challengeUri` contains the address of the proxy server that requires client authentication. diff --git a/xml/System.Net/ICredentialsByHost.xml b/xml/System.Net/ICredentialsByHost.xml index 6595d49fd5a..fc6dfe5dddd 100644 --- a/xml/System.Net/ICredentialsByHost.xml +++ b/xml/System.Net/ICredentialsByHost.xml @@ -46,11 +46,11 @@ Provides the interface for retrieving credentials for a host, port, and authentication type. - class, and and its derived classes. - + class, and and its derived classes. + ]]> @@ -105,11 +105,11 @@ Returns the credential for the specified host, port, and authentication protocol. A for the specified host, port, and authentication protocol, or if there are no credentials available for the specified host, port, and authentication protocol. - property. - + property. + ]]> diff --git a/xml/System.Net/IPAddress.xml b/xml/System.Net/IPAddress.xml index 0264f5be170..d27b40c390a 100644 --- a/xml/System.Net/IPAddress.xml +++ b/xml/System.Net/IPAddress.xml @@ -168,7 +168,7 @@ is created with the property set to `address`. + The is created with the property set to `address`. If the length of `address` is 4, constructs an IPv4 address; otherwise, an IPv6 address with a scope of 0 is constructed. @@ -229,7 +229,7 @@ instance is created with the property set to `newAddress`. + The instance is created with the property set to `newAddress`. The value is assumed to be in network byte order. @@ -2876,7 +2876,7 @@ The scope identifier is > 0x00000000FFFFFFFF
method converts the IP address that is stored in the property to either IPv4 dotted-quad or IPv6 colon-hexadecimal notation. + The method converts the IP address that is stored in the property to either IPv4 dotted-quad or IPv6 colon-hexadecimal notation. ]]> diff --git a/xml/System.Net/IPEndPoint.xml b/xml/System.Net/IPEndPoint.xml index 931dfc8e44a..14f6ce33765 100644 --- a/xml/System.Net/IPEndPoint.xml +++ b/xml/System.Net/IPEndPoint.xml @@ -96,7 +96,7 @@ -## Examples +## Examples :::code language="csharp" source="~/snippets/csharp/System.Net/IPEndPoint/Overview/ipendpoint.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPEndPoint/Overview/ipendpoint.vb" id="Snippet1"::: @@ -307,7 +307,7 @@ property using the specified. + The following example sets the property using the specified. :::code language="csharp" source="~/snippets/csharp/System.Net/IPEndPoint/Overview/ipendpoint.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPEndPoint/Overview/ipendpoint.vb" id="Snippet3"::: @@ -363,7 +363,7 @@ property to return the to which the belongs. In this case it is the . + The following example uses the property to return the to which the belongs. In this case it is the . :::code language="csharp" source="~/snippets/csharp/System.Net/IPEndPoint/Overview/ipendpoint.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPEndPoint/Overview/ipendpoint.vb" id="Snippet3"::: @@ -601,7 +601,7 @@ property to print the maximum value that can be assigned to the property. + The following example uses the property to print the maximum value that can be assigned to the property. :::code language="csharp" source="~/snippets/csharp/System.Net/IPEndPoint/.ctor/ipendpoint_properties.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPEndPoint/.ctor/ipendpoint_properties.vb" id="Snippet4"::: @@ -657,7 +657,7 @@ property to print the minimum value that can be assigned to the property. + The following example uses the property to print the minimum value that can be assigned to the property. :::code language="csharp" source="~/snippets/csharp/System.Net/IPEndPoint/.ctor/ipendpoint_properties.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPEndPoint/.ctor/ipendpoint_properties.vb" id="Snippet4"::: @@ -883,7 +883,7 @@ Literal IPv6 addresses require to be enclosed in square brackets [] when passing property to set TCP port number of the . + The following example uses the property to set TCP port number of the . :::code language="csharp" source="~/snippets/csharp/System.Net/IPEndPoint/Overview/ipendpoint.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPEndPoint/Overview/ipendpoint.vb" id="Snippet3"::: diff --git a/xml/System.Net/IPHostEntry.xml b/xml/System.Net/IPHostEntry.xml index bb18df9c08d..4e48f1809e2 100644 --- a/xml/System.Net/IPHostEntry.xml +++ b/xml/System.Net/IPHostEntry.xml @@ -64,7 +64,7 @@ ## Examples The following example queries the DNS database for information on the host `www.contoso.com` and returns the information in an instance. - + :::code language="csharp" source="~/snippets/csharp/System.Net/Dns/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/Dns/Overview/source.vb" id="Snippet1"::: @@ -172,7 +172,7 @@ property to access the IP addresses that are associated with the . + The following example uses the property to access the IP addresses that are associated with the . :::code language="csharp" source="~/snippets/csharp/System.Net/IPHostEntry/AddressList/iphostentry_addresslist.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPHostEntry/AddressList/iphostentry_addresslist.vb" id="Snippet1"::: @@ -288,12 +288,12 @@ property contains the primary host name for a server. If the DNS entry for the server defines additional aliases, they will be available in the property. + The property contains the primary host name for a server. If the DNS entry for the server defines additional aliases, they will be available in the property. ## Examples - The following example uses the property to retrieve the primary host name. + The following example uses the property to retrieve the primary host name. :::code language="csharp" source="~/snippets/csharp/System.Net/IPHostEntry/AddressList/iphostentry_addresslist.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IPHostEntry/AddressList/iphostentry_addresslist.vb" id="Snippet1"::: diff --git a/xml/System.Net/IWebProxy.xml b/xml/System.Net/IWebProxy.xml index cd6c69912f4..791b49d863b 100644 --- a/xml/System.Net/IWebProxy.xml +++ b/xml/System.Net/IWebProxy.xml @@ -107,13 +107,13 @@ property is an instance that contains the authorization credentials to send to the proxy server in response to an HTTP 407 (proxy authorization) status code. + The property is an instance that contains the authorization credentials to send to the proxy server in response to an HTTP 407 (proxy authorization) status code. ## Examples - The following example uses the property to set the credentials that will be submitted to the proxy server for authentication. - + The following example uses the property to set the credentials that will be submitted to the proxy server for authentication. + :::code language="csharp" source="~/snippets/csharp/System.Net/IWebProxy/Credentials/iwebproxy_interface.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IWebProxy/Credentials/iwebproxy_interface.vb" id="Snippet1"::: @@ -240,7 +240,7 @@ ## Examples - The following example uses the property to determine whether the proxy server should be used for the specified host. + The following example uses the property to determine whether the proxy server should be used for the specified host. :::code language="csharp" source="~/snippets/csharp/System.Net/IWebProxy/Credentials/iwebproxy_interface.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/IWebProxy/Credentials/iwebproxy_interface.vb" id="Snippet4"::: diff --git a/xml/System.Net/NetworkCredential.xml b/xml/System.Net/NetworkCredential.xml index 66702301bca..0f79ee537af 100644 --- a/xml/System.Net/NetworkCredential.xml +++ b/xml/System.Net/NetworkCredential.xml @@ -220,7 +220,7 @@ object with the property set to `userName` and the property set to `password`. + The constructor initializes a object with the property set to `userName` and the property set to `password`. The `password` parameter is a instance. @@ -283,7 +283,7 @@ object with the property set to `userName` and the property set to `password`. + The constructor initializes a object with the property set to `userName` and the property set to `password`. @@ -352,7 +352,7 @@ object with the property set to `userName`, the property set to `password`, and the property set to `domain`. + The constructor initializes a object with the property set to `userName`, the property set to `password`, and the property set to `domain`. The `password` parameter is a instance. @@ -417,7 +417,7 @@ object with the property set to `userName`, the property set to `password`, and the property set to `domain`. + The constructor initializes a object with the property set to `userName`, the property set to `password`, and the property set to `domain`. ]]> @@ -472,12 +472,12 @@ property specifies the domain or realm to which the user name belongs. Typically, this is the host computer name where the application runs or the user domain for the currently logged in user. + The property specifies the domain or realm to which the user name belongs. Typically, this is the host computer name where the application runs or the user domain for the currently logged in user. ## Examples - The following code example uses the property to set the domain associated with the credentials. + The following code example uses the property to set the domain associated with the credentials. :::code language="csharp" source="~/snippets/csharp/System.Net/NetworkCredential/Domain/networkcredential_username_password_domain.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/NetworkCredential/Domain/networkcredential_username_password_domain.vb" id="Snippet1"::: @@ -557,7 +557,7 @@ property. + The value of `authType` corresponds to the property. ]]> @@ -686,7 +686,7 @@ property to set the password associated with the credentials. + The following code example uses the property to set the password associated with the credentials. :::code language="csharp" source="~/snippets/csharp/System.Net/NetworkCredential/Domain/networkcredential_username_password_domain.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/NetworkCredential/Domain/networkcredential_username_password_domain.vb" id="Snippet1"::: @@ -745,7 +745,7 @@ property to `null`, a new instance of is initialized, If secure strings are not supported on this platform, then the is thrown + If an application attempts to set the property to `null`, a new instance of is initialized, If secure strings are not supported on this platform, then the is thrown ]]> @@ -801,7 +801,7 @@ property to set the user name associated with the credentials. + The following code example uses the property to set the user name associated with the credentials. :::code language="csharp" source="~/snippets/csharp/System.Net/NetworkCredential/Domain/networkcredential_username_password_domain.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/NetworkCredential/Domain/networkcredential_username_password_domain.vb" id="Snippet1"::: diff --git a/xml/System.Net/OpenReadCompletedEventArgs.xml b/xml/System.Net/OpenReadCompletedEventArgs.xml index c835ea3595d..16ccfe7bde2 100644 --- a/xml/System.Net/OpenReadCompletedEventArgs.xml +++ b/xml/System.Net/OpenReadCompletedEventArgs.xml @@ -64,7 +64,7 @@ ## Examples The following code example demonstrates downloading a resource for reading. - + :::code language="csharp" source="~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs" id="Snippet30"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb" id="Snippet30"::: @@ -122,7 +122,7 @@ and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties before using the data that is returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/OpenWriteCompletedEventArgs.xml b/xml/System.Net/OpenWriteCompletedEventArgs.xml index 2c502795765..e1c94a7a410 100644 --- a/xml/System.Net/OpenWriteCompletedEventArgs.xml +++ b/xml/System.Net/OpenWriteCompletedEventArgs.xml @@ -64,7 +64,7 @@ ## Examples The following code example demonstrates opening a stream to write data to be uploaded. - + :::code language="csharp" source="~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs" id="Snippet16"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb" id="Snippet16"::: @@ -122,7 +122,7 @@ and properties before using the stream returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties before using the stream returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/ProtocolViolationException.xml b/xml/System.Net/ProtocolViolationException.xml index ec2d043374e..0cd6095f53a 100644 --- a/xml/System.Net/ProtocolViolationException.xml +++ b/xml/System.Net/ProtocolViolationException.xml @@ -135,7 +135,7 @@ property is initialized to a system-supplied message that describes the error. The property is initialized to `null`. + The property is initialized to a system-supplied message that describes the error. The property is initialized to `null`. ]]> @@ -195,7 +195,7 @@ class with the property set to the value of the `message` parameter. If `message` is a null reference, the `Message` property is initialized to a system-supplied message. The `InnerException` property is initialized to `null`. + This constructor initializes a new instance of the class with the property set to the value of the `message` parameter. If `message` is a null reference, the `Message` property is initialized to a system-supplied message. The `InnerException` property is initialized to `null`. ]]> diff --git a/xml/System.Net/SecurityProtocolType.xml b/xml/System.Net/SecurityProtocolType.xml index 8cee2b4a2f8..e56b52ace09 100644 --- a/xml/System.Net/SecurityProtocolType.xml +++ b/xml/System.Net/SecurityProtocolType.xml @@ -57,10 +57,10 @@ Specifies the security protocols that are supported by the Schannel security package. - property. Use this enumeration to determine your transport security protocol policy when you're using HTTP APIs in the .NET Framework such as , , , and (when using TLS/SSL). + property. Use this enumeration to determine your transport security protocol policy when you're using HTTP APIs in the .NET Framework such as , , , and (when using TLS/SSL). The Transport Layer Security (TLS) protocols assume that a connection-oriented protocol, typically TCP, is in use. diff --git a/xml/System.Net/ServicePointManager.xml b/xml/System.Net/ServicePointManager.xml index 3215d94f43e..eabe8225fa0 100644 --- a/xml/System.Net/ServicePointManager.xml +++ b/xml/System.Net/ServicePointManager.xml @@ -131,7 +131,7 @@ property is set to an interface object, the object uses the certificate policy defined in that instance instead of the default certificate policy. + When the property is set to an interface object, the object uses the certificate policy defined in that instance instead of the default certificate policy. The default certificate policy allows valid certificates and valid certificates that have expired. @@ -257,12 +257,12 @@ property sets the default maximum number of concurrent connections that the object assigns to the property when creating objects. + The property sets the default maximum number of concurrent connections that the object assigns to the property when creating objects. - Changing the property has no effect on existing objects; it affects only objects that are initialized after the change. If the value of this property has not been set either directly or through configuration, the value defaults to the constant . + Changing the property has no effect on existing objects; it affects only objects that are initialized after the change. If the value of this property has not been set either directly or through configuration, the value defaults to the constant . > [!NOTE] -> Any changes to the property affect both HTTP 1.0 and HTTP 1.1 connections. It is not possible to separately alter the connection limit for HTTP 1.0 and HTTP 1.1 protocols. +> Any changes to the property affect both HTTP 1.0 and HTTP 1.1 connections. It is not possible to separately alter the connection limit for HTTP 1.0 and HTTP 1.1 protocols. > [!NOTE] > Since .NET 9, this property maps to unless overridden by . However, handlers are not being reused between requests so it doesn't have any meaningful impact. @@ -372,7 +372,7 @@ property using this field. + The following code example sets the property using this field. :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/HttpWebRequest/ServicePoint/servicepoint.vb" id="Snippet10"::: @@ -552,7 +552,7 @@ property defaults to . This is applied to an SSL/TLS session on this instance. + If a value is not specified in the configuration file, the property defaults to . This is applied to an SSL/TLS session on this instance. The use of the Null cipher is required when the encryption policy is set to . @@ -614,9 +614,9 @@ property is `true` and property is greater than zero or the property is true. The client will expect to receive a 100-Continue response from the server to indicate that the client should send the data to be posted. This mechanism allows clients to avoid sending large amounts of data over the network when the server, based on the request headers, intends to reject the request. + When this property is set to `true`, 100-Continue behavior is used. Client requests that use the `PUT` and `POST` methods will add an Expect header to the request if the property is `true` and property is greater than zero or the property is true. The client will expect to receive a 100-Continue response from the server to indicate that the client should send the data to be posted. This mechanism allows clients to avoid sending large amounts of data over the network when the server, based on the request headers, intends to reject the request. - For example, assume the property is `false`. When the request is sent to the server, it includes the data. If, after reading the request headers, the server requires authentication and must send a 401 response, the client must resend the data with proper authentication headers. + For example, assume the property is `false`. When the request is sent to the server, it includes the data. If, after reading the request headers, the server requires authentication and must send a 401 response, the client must resend the data with proper authentication headers. If this property is `true`, the request headers are sent to the server. If the server has not rejected the request, it sends a 100-Continue response signaling that the data can be transmitted. If, as in the preceding example, the server requires authentication, it sends the 401 response and the client has not unnecessarily transmitted the data. @@ -926,7 +926,7 @@ property sets the maximum idle time that the object assigns to the property when creating objects. Changes to this value affect only objects that are initialized after the value is changed. + The property sets the maximum idle time that the object assigns to the property when creating objects. Changes to this value affect only objects that are initialized after the value is changed. After a object has been idle for the time specified in , it is eligible for garbage collection. A object is idle when the list of connections associated with the object is empty. @@ -999,7 +999,7 @@ property below the number of objects currently in existence, the deletes the objects with the longest idle times. If the number of objects with active connections is greater than the value of , the object deletes the objects as they become idle. + When you reduce the property below the number of objects currently in existence, the deletes the objects with the longest idle times. If the number of objects with active connections is greater than the value of , the object deletes the objects as they become idle. > [!NOTE] > This property is only implemented on .NET Framework. @@ -1197,7 +1197,7 @@ For versions of the .NET Framework through the .NET Framework 4.6.2, no default property to a method to use for custom validation by the client of the server certificate. When doing custom validation, the `sender` parameter passed to the can be a host string name or an object derived from (, for example) depending on the property. +An application can set the property to a method to use for custom validation by the client of the server certificate. When doing custom validation, the `sender` parameter passed to the can be a host string name or an object derived from (, for example) depending on the property. When custom validation is not used, the certificate name is compared with the host name used to create the request. For example, if was passed a parameter of `"https://www.contoso.com/default.html"`, the default behavior is for the client to check the certificate against `www.contoso.com`. diff --git a/xml/System.Net/SocketPermissionAttribute.xml b/xml/System.Net/SocketPermissionAttribute.xml index 1972bfa892b..8e77209a2ac 100644 --- a/xml/System.Net/SocketPermissionAttribute.xml +++ b/xml/System.Net/SocketPermissionAttribute.xml @@ -56,7 +56,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - To use this attribute, your connection must conform to the properties that are specified in your . For example, to apply the permission to a connection on port 80, set the property of the to "80". The security information that is specified in is stored in the metadata of the attribute target, which is the class to which the is applied. The system then accesses the information at run time. The that is passed to the constructor determines the allowable targets. + To use this attribute, your connection must conform to the properties that are specified in your . For example, to apply the permission to a connection on port 80, set the property of the to "80". The security information that is specified in is stored in the metadata of the attribute target, which is the class to which the is applied. The system then accesses the information at run time. The that is passed to the constructor determines the allowable targets. > [!NOTE] > The properties of a must have values that are not `null`. Also, once set, the values of the properties cannot be changed. diff --git a/xml/System.Net/TransportContext.xml b/xml/System.Net/TransportContext.xml index 3f478eca0fd..a76612e5295 100644 --- a/xml/System.Net/TransportContext.xml +++ b/xml/System.Net/TransportContext.xml @@ -48,17 +48,17 @@ The class provides additional context about the underlying transport layer. - class is used with classes in the namespace to provide support for authentication using extended protection for applications. - - The design of integrated Windows authentication allows for some credential challenge responses to be universal, meaning they can be re-used or forwarded. If this particular design feature is not needed then the challenge responses should be constructed with, at minimum, target specific information and, at best, also some channel specific information. Services can then provide extended protection to ensure that credential challenge responses contain service specific information (a Service Provider Name or SPN) and, if necessary, channel specific information (a channel binding token or CBT). With this information in the credential exchanges, services are able to better protect against malicious use of credential challenge responses that might have been improperly obtained. - - is the only class derived from class that can potentially use IWA. The class does only FTP clear text authentication. The class doesn't perform any authentication. - - There are several ways an application may get a instance. An application that uses can get the using the property. An application that uses can get a using the or methods. - + class is used with classes in the namespace to provide support for authentication using extended protection for applications. + + The design of integrated Windows authentication allows for some credential challenge responses to be universal, meaning they can be re-used or forwarded. If this particular design feature is not needed then the challenge responses should be constructed with, at minimum, target specific information and, at best, also some channel specific information. Services can then provide extended protection to ensure that credential challenge responses contain service specific information (a Service Provider Name or SPN) and, if necessary, channel specific information (a channel binding token or CBT). With this information in the credential exchanges, services are able to better protect against malicious use of credential challenge responses that might have been improperly obtained. + + is the only class derived from class that can potentially use IWA. The class does only FTP clear text authentication. The class doesn't perform any authentication. + + There are several ways an application may get a instance. An application that uses can get the using the property. An application that uses can get a using the or methods. + ]]> @@ -156,13 +156,13 @@ Retrieves the requested channel binding. The requested , or if the channel binding is not supported by the current transport or by the operating system. - or . - - If an application attempts to retrieve the channel binding token (CBT) from the property using the method and the is not , then the will throw . The overrides the method with an internal implementation - + or . + + If an application attempts to retrieve the channel binding token (CBT) from the property using the method and the is not , then the will throw . The overrides the method with an internal implementation + ]]> diff --git a/xml/System.Net/UploadDataCompletedEventArgs.xml b/xml/System.Net/UploadDataCompletedEventArgs.xml index 29bab1c8c34..4069b08d939 100644 --- a/xml/System.Net/UploadDataCompletedEventArgs.xml +++ b/xml/System.Net/UploadDataCompletedEventArgs.xml @@ -60,7 +60,7 @@ ## Examples The following code example demonstrates asynchronously uploading data. - + :::code language="csharp" source="~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs" id="Snippet34"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb" id="Snippet34"::: @@ -115,7 +115,7 @@ and properties before using the data returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties before using the data returned by this property. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/UploadFileCompletedEventArgs.xml b/xml/System.Net/UploadFileCompletedEventArgs.xml index 1fa578d615f..944c5c6923d 100644 --- a/xml/System.Net/UploadFileCompletedEventArgs.xml +++ b/xml/System.Net/UploadFileCompletedEventArgs.xml @@ -60,7 +60,7 @@ ## Examples The following code example demonstrates asynchronously uploading a file. - + :::code language="csharp" source="~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb" id="Snippet4"::: @@ -115,7 +115,7 @@ and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/UploadProgressChangedEventArgs.xml b/xml/System.Net/UploadProgressChangedEventArgs.xml index 6be22fca240..c6aa9a7adc9 100644 --- a/xml/System.Net/UploadProgressChangedEventArgs.xml +++ b/xml/System.Net/UploadProgressChangedEventArgs.xml @@ -49,11 +49,11 @@ Provides data for the event of a . - . - + . + ]]> @@ -106,13 +106,13 @@ Gets the number of bytes received. An value that indicates the number of bytes received. - and . - - To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. - + and . + + To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. + ]]> @@ -165,13 +165,13 @@ Gets the number of bytes sent. An value that indicates the number of bytes sent. - and . - - To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. - + and . + + To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. + ]]> @@ -224,15 +224,15 @@ Gets the total number of bytes in a data upload operation. An value that indicates the number of bytes that will be received. - property. - - Uploading data to a server may result in a download from the server. For example, suppose your application uploads a POST request to a Web server. The resulting download will update and . - - To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. - + property. + + Uploading data to a server may result in a download from the server. For example, suppose your application uploads a POST request to a Web server. The resulting download will update and . + + To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. + ]]> @@ -285,15 +285,15 @@ Gets the total number of bytes to send. An value that indicates the number of bytes that will be sent. - property. - - Uploading data to a server may result in a download from the server. For example, suppose your application uploads a POST request to a Web server. The resulting download will update and . - - To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. - + property. + + Uploading data to a server may result in a download from the server. For example, suppose your application uploads a POST request to a Web server. The resulting download will update and . + + To determine what percentage of the transfer has occurred, use the property. When the upload is complete, will be 50%. When the download completes, will be 100%. + ]]> diff --git a/xml/System.Net/UploadStringCompletedEventArgs.xml b/xml/System.Net/UploadStringCompletedEventArgs.xml index b4082cf0d4e..112711b8ea2 100644 --- a/xml/System.Net/UploadStringCompletedEventArgs.xml +++ b/xml/System.Net/UploadStringCompletedEventArgs.xml @@ -64,7 +64,7 @@ ## Examples The following code example demonstrates asynchronously uploading a string. - + :::code language="csharp" source="~/snippets/csharp/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.cs" id="Snippet38"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/DownloadDataCompletedEventArgs/Overview/asyncmethods.vb" id="Snippet38"::: @@ -122,7 +122,7 @@ and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + You should check the and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. diff --git a/xml/System.Net/UploadValuesCompletedEventArgs.xml b/xml/System.Net/UploadValuesCompletedEventArgs.xml index ba28f30c4d6..e69c01ac975 100644 --- a/xml/System.Net/UploadValuesCompletedEventArgs.xml +++ b/xml/System.Net/UploadValuesCompletedEventArgs.xml @@ -51,11 +51,11 @@ Provides data for the event. - . - + . + ]]> @@ -99,11 +99,11 @@ Gets the server reply to a data upload operation started by calling an method. A array containing the server reply. - and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. - + and properties to determine whether the upload completed. If the property's value is an object or the property's value is `true`, the asynchronous operation did not complete correctly and the property's value will not be valid. + ]]> diff --git a/xml/System.Net/WebClient.xml b/xml/System.Net/WebClient.xml index 5836d71e903..cc56813bec7 100644 --- a/xml/System.Net/WebClient.xml +++ b/xml/System.Net/WebClient.xml @@ -247,7 +247,7 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - When the property is `true`, the data is buffered in memory so it is ready to be read by the app. + When the property is `true`, the data is buffered in memory so it is ready to be read by the app. ]]> @@ -307,7 +307,7 @@ ## Remarks - When the property is `true`, the data is buffered in memory so it can be written more efficiently to the Internet resource in larger chunks. + When the property is `true`, the data is buffered in memory so it can be written more efficiently to the Internet resource in larger chunks. ]]> @@ -362,7 +362,7 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains a base URI that is combined with a relative address. When you call a method that uploads or downloads data, the object combines this base URI with the relative address you specify in the method call. If you specify an absolute URI, does not use the property value. + The property contains a base URI that is combined with a relative address. When you call a method that uploads or downloads data, the object combines this base URI with the relative address you specify in the method call. If you specify an absolute URI, does not use the property value. To remove a previously set value, set this property to `null` or an empty string (""). @@ -493,7 +493,7 @@ > [!NOTE] > Starting in .NET Core 2.0, doesn't cancel the request immediately if the response has started to fetch. For optimum cancellation behavior, use the class instead of . - When you call , your application still receives the completion event associated with the operation. For example, when you call to cancel a operation, if you have specified an event handler for the event, your event handler receives notification that the operation has ended. To learn whether the operation completed successfully, check the property on the base class of in the event data object passed to the event handler. + When you call , your application still receives the completion event associated with the operation. For example, when you call to cancel a operation, if you have specified an event handler for the event, your event handler receives notification that the operation has ended. To learn whether the operation completed successfully, check the property on the base class of in the event data object passed to the event handler. If no asynchronous operation is in progress, this method does nothing. @@ -565,7 +565,7 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains the authentication credentials used to access a resource on a host. In most client-side scenarios, you should use the , which are the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. + The property contains the authentication credentials used to access a resource on a host. In most client-side scenarios, you should use the , which are the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. If the class is being used in a middle tier application, such as an ASP.NET application, the belong to the account running the ASP page (the server-side credentials). Typically, you would set this property to the credentials of the client on whose behalf the request is made. @@ -650,7 +650,7 @@ The method downloads the resource with the URI specified by the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -729,7 +729,7 @@ The method downloads the resource with the URI specified by the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -810,13 +810,13 @@ This method retrieves the specified resource using the default method for the protocol associated with the URI scheme specified in `address`. The data is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use one of the methods. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded data is available in the property. + This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use one of the methods. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded data is available in the property. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -896,13 +896,13 @@ This method retrieves the specified resource using the default method for the protocol associated with the URI scheme specified in `address`. The data is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use one of the methods. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded data is available in the property. + This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use one of the methods. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded data is available in the property. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -1068,7 +1068,7 @@ This method retrieves the specified resource using the default method for the protocol associated with the URI scheme specified in the `address` parameter. The data is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1148,7 +1148,7 @@ This method retrieves the specified resource using the default method for the protocol associated with the URI scheme specified in the `address` parameter. The data is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1231,7 +1231,7 @@ The method downloads to a local file data from the URI specified by in the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1319,7 +1319,7 @@ The method downloads to a local file data from the URI specified by in the `address` parameter. This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1426,7 +1426,7 @@ In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1521,7 +1521,7 @@ In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1692,7 +1692,7 @@ In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1781,7 +1781,7 @@ In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -1960,9 +1960,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method retrieves the specified resource. After it downloads the resource, the method uses the encoding specified in the property to convert the resource to a . This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. + This method retrieves the specified resource. After it downloads the resource, the method uses the encoding specified in the property to convert the resource to a . This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2039,9 +2039,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method retrieves the specified resource. After it downloads the resource, the method uses the encoding specified in the property to convert the resource to a . This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. + This method retrieves the specified resource. After it downloads the resource, the method uses the encoding specified in the property to convert the resource to a . This method blocks while downloading the resource. To download a resource and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2128,11 +2128,11 @@ internal class MyWebClient : WebClientProtocol The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use the method. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded string is available in the property. + After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use the method. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded string is available in the property. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2214,11 +2214,11 @@ internal class MyWebClient : WebClientProtocol The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use the method. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded string is available in the property. + After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. To download a resource and block while waiting for the server's response, use the method. When the download completes, the event is raised. Your application must handle this event to receive notification. The downloaded string is available in the property. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2384,11 +2384,11 @@ internal class MyWebClient : WebClientProtocol This operation will not block. The returned object will complete after the data resource has been downloaded. The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. + After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2463,11 +2463,11 @@ internal class MyWebClient : WebClientProtocol This operation will not block. The returned object will complete after the data resource has been downloaded. The resource is downloaded asynchronously using thread resources that are automatically allocated from the thread pool. - After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. + After downloading the resource, this method uses the encoding specified in the property to convert the resource to a . This method does not block the calling thread while downloading the resource. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -2825,7 +2825,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains a instance containing protocol headers that the sends with the request. + The property contains a instance containing protocol headers that the sends with the request. Some common headers are considered restricted and are protected by the system and cannot be set or changed in a object. Any attempt to set one of these restricted headers in the object associated with a object will throw an exception later when attempting to send the request. @@ -3823,7 +3823,7 @@ internal class MyWebClient : WebClientProtocol The method creates a instance used to read the contents of the resource specified by the `address` parameter. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -3904,7 +3904,7 @@ internal class MyWebClient : WebClientProtocol The method creates a instance used to read the contents of the resource specified by the `address` parameter. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -4000,7 +4000,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -4093,7 +4093,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -4270,7 +4270,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -4358,7 +4358,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested resource. If the property is not `null`, it is appended to `address`. This method uses the RETR command to download an FTP resource. For an HTTP resource, the GET method is used. @@ -4445,7 +4445,7 @@ internal class MyWebClient : WebClientProtocol The method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -4529,7 +4529,7 @@ internal class MyWebClient : WebClientProtocol The method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -4611,9 +4611,9 @@ internal class MyWebClient : WebClientProtocol The method returns a writable stream that is used to send data to a resource. The underlying request is made with the method specified in the `method` parameter. The data is sent to the server when you close the stream. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not specify an absolute address, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not specify an absolute address, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -4699,7 +4699,7 @@ internal class MyWebClient : WebClientProtocol The method returns a writable stream that is used to send data to a resource. This method blocks while opening the stream. To continue executing while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -4785,7 +4785,7 @@ internal class MyWebClient : WebClientProtocol This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -4870,7 +4870,7 @@ internal class MyWebClient : WebClientProtocol This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -4947,13 +4947,13 @@ internal class MyWebClient : WebClientProtocol This method retrieves a writable stream that is used to send data to a resource. The stream is retrieved asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the stream is available, add an event handler to the event. The contents of the stream are sent to the server when you close the stream. - If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. This method does not block the calling thread while the stream is being opened. To block while waiting for the stream, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -5124,7 +5124,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -5207,7 +5207,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -5297,11 +5297,11 @@ internal class MyWebClient : WebClientProtocol > [!NOTE] > You must call when you are finished with the to avoid running out of system resources. - If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -5392,11 +5392,11 @@ internal class MyWebClient : WebClientProtocol > [!NOTE] > You must call when you are finished with the to avoid running out of system resources. - If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` parameter specifies a method that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -5468,7 +5468,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property identifies the instance that communicates with remote servers on behalf of this object. The proxy is set by the system using configuration files and the Local Area Network settings. To specify that no proxy should be used, set the property to `null`. + The property identifies the instance that communicates with remote servers on behalf of this object. The proxy is set by the system using configuration files and the Local Area Network settings. To specify that no proxy should be used, set the property to `null`. For information on automatic proxy detection, see [Automatic Proxy Detection](/dotnet/framework/network-programming/automatic-proxy-detection). @@ -5539,12 +5539,12 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains a instance containing name/value pairs that are appended to the URI as a query string. The contents of the property are preceded by a question mark (?), and name/value pairs are separated from one another by an ampersand (&). + The property contains a instance containing name/value pairs that are appended to the URI as a query string. The contents of the property are preceded by a question mark (?), and name/value pairs are separated from one another by an ampersand (&). ## Examples - The following code example takes user input from the command line and builds a that is assigned to the property. It then downloads the response from the server to a local file. + The following code example takes user input from the command line and builds a that is assigned to the property. It then downloads the response from the server to a local file. [!code-cpp[WebClient_QueryString#1](~/snippets/cpp/VS_Snippets_Remoting/WebClient_QueryString/CPP/webclient_querystring.cpp#1)] [!code-csharp[WebClient_QueryString#1](~/snippets/csharp/System.Net/WebClient/QueryString/webclient_querystring.cs#1)] @@ -5610,7 +5610,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains a instance containing header information the receives with the response. + The property contains a instance containing header information the receives with the response. @@ -5692,11 +5692,11 @@ internal class MyWebClient : WebClientProtocol The method sends a data buffer to a resource. - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. The method sends the content of `data` to the server without encoding it. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -5788,11 +5788,11 @@ internal class MyWebClient : WebClientProtocol The method sends a data buffer to a resource. - This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. The method sends the content of `data` to the server without encoding it. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -5884,9 +5884,9 @@ internal class MyWebClient : WebClientProtocol The method sends the content of `data` to the server without encoding it. - If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -5984,9 +5984,9 @@ internal class MyWebClient : WebClientProtocol The method sends the content of `data` to the server without encoding it. - If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6084,7 +6084,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -6182,7 +6182,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6281,7 +6281,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6455,7 +6455,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -6541,7 +6541,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -6637,7 +6637,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6731,7 +6731,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6819,9 +6819,9 @@ internal class MyWebClient : WebClientProtocol This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. - The `POST` method is defined by HTTP. If the underlying request does not use HTTP and `POST` is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + The `POST` method is defined by HTTP. If the underlying request does not use HTTP and `POST` is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -6928,9 +6928,9 @@ internal class MyWebClient : WebClientProtocol This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. - The `POST` method is defined by HTTP. If the underlying request does not use HTTP and `POST` is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + The `POST` method is defined by HTTP. If the underlying request does not use HTTP and `POST` is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -7028,9 +7028,9 @@ internal class MyWebClient : WebClientProtocol When address specifies an HTTP resource, the method sends a local file to a resource using the HTTP method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. - If the `method` parameter specifies a verb that is not understood by the server or the `address` resource, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` parameter specifies a verb that is not understood by the server or the `address` resource, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -7139,9 +7139,9 @@ internal class MyWebClient : WebClientProtocol When address specifies an HTTP resource, the method sends a local file to a resource using the HTTP method specified in the `method` parameter and returns any response from the server. This method blocks while uploading the file. To continue executing while waiting for the server's response, use one of the methods. - If the `method` parameter specifies a verb that is not understood by the server or the `address` resource, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` parameter specifies a verb that is not understood by the server or the `address` resource, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -7247,7 +7247,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7357,7 +7357,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7470,7 +7470,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7656,7 +7656,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7752,7 +7752,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7858,7 +7858,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. BY default, this method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -7964,7 +7964,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. BY default, this method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -8147,9 +8147,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -8237,9 +8237,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string (""), and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -8324,9 +8324,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8420,9 +8420,9 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. To send a string and continue executing while waiting for the server's response, use one of the methods. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8514,13 +8514,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. + This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -8612,13 +8612,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. + This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8715,13 +8715,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. + This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8897,9 +8897,9 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -8981,9 +8981,9 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9075,9 +9075,9 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9173,9 +9173,9 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. + Before uploading the string, this method converts it to a array using the encoding specified in the property. This method blocks while the string is transmitted. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9265,11 +9265,11 @@ internal class MyWebClient : WebClientProtocol The method sends a to a server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. If the Content-type header is `null`, the method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -9371,11 +9371,11 @@ internal class MyWebClient : WebClientProtocol The method sends a to a server. This method blocks while uploading the data. To continue executing while waiting for the server's response, use one of the methods. - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. If the Content-type header is `null`, the method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -9477,9 +9477,9 @@ internal class MyWebClient : WebClientProtocol If the `Content-type` header is `null`, the method sets it to `application/x-www-form-urlencoded`. - If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9585,9 +9585,9 @@ internal class MyWebClient : WebClientProtocol If the `Content-type` header is `null`, the method sets it to `application/x-www-form-urlencoded`. - If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` parameter specifies a verb that is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information, see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9687,13 +9687,13 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. + This method sends a string to a resource. The string is sent asynchronously using thread resources that are automatically allocated from the thread pool. Before uploading the string, this method converts it to a array using the encoding specified in the property. To receive notification when the string upload completes, you can add an event handler to the event. This method does not block the calling thread while the string is being sent. To send a string and block while waiting for the server's response, use one of the methods. In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -9787,7 +9787,7 @@ internal class MyWebClient : WebClientProtocol This method sends the data contained in a to the `address` resource. Use this method to send form data to a URI for processing. The data is sent using the form-urlencoded media type; the Content-Type header value must be set to "application/x-www-form-urlencoded". The header is set correctly by default. The methods throw a if you call this method with a different Content-Type header value set in the collection. - If the `method` method is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` method is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. The is sent asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the upload operation completes, add an event handler to the event. @@ -9795,7 +9795,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not empty, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not empty, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -9894,7 +9894,7 @@ internal class MyWebClient : WebClientProtocol This method sends the data contained in a to the `address` resource. Use this method to send form data to a URI for processing. The data is sent using the form-urlencoded media type; the Content-Type header value must be set to "application/x-www-form-urlencoded". The header is set correctly by default. The methods throw a if you call this method with a different Content-Type header value set in the collection. - If the `method` method is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the `method` method is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. The is sent asynchronously using thread resources that are automatically allocated from the thread pool. To receive notification when the upload operation completes, add an event handler to the event. @@ -9902,7 +9902,7 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not empty, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not empty, it is appended to `address`. > [!NOTE] > This member outputs trace information when you enable network tracing in your application. For more information see [Network Tracing in .NET Framework](/dotnet/framework/network-programming/network-tracing). @@ -10063,11 +10063,11 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -10159,11 +10159,11 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -10265,11 +10265,11 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -10375,11 +10375,11 @@ internal class MyWebClient : WebClientProtocol In .NET Framework and .NET Core 1.0, you can cancel asynchronous operations that have not completed by calling the method. - If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. + If the underlying request is not understood by the server, the underlying protocol classes determine what occurs. Typically, a is thrown with the property set to indicate the error. If the Content-type header is `null`, this method sets it to "application/x-www-form-urlencoded". - If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. + If the property is not an empty string ("") and `address` does not contain an absolute URI, `address` must be a relative URI that is combined with to form the absolute URI of the requested data. If the property is not an empty string, it is appended to `address`. This method uses the STOR command to upload an FTP resource. For an HTTP resource, the POST method is used. @@ -10461,7 +10461,7 @@ internal class MyWebClient : WebClientProtocol [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - Set this property to `true` when requests made by this object should, if requested by the server, be authenticated using the default credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made. + Set this property to `true` when requests made by this object should, if requested by the server, be authenticated using the default credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made. diff --git a/xml/System.Net/WebException.xml b/xml/System.Net/WebException.xml index 9cc1f842965..4ec19bf4728 100644 --- a/xml/System.Net/WebException.xml +++ b/xml/System.Net/WebException.xml @@ -75,15 +75,15 @@ ## Remarks The class is thrown by classes descended from and that implement pluggable protocols for accessing the Internet. - When is thrown by a descendant of the class, the property provides the Internet response to the application. + When is thrown by a descendant of the class, the property provides the Internet response to the application. **Associated Tips** **Check the Response property of the exception to determine why the request failed.** - When a exception is thrown by a descendent of the class, the property provides the Internet response to the application. + When a exception is thrown by a descendent of the class, the property provides the Internet response to the application. **Check the Status property of the exception to determine why the request failed.** - The property of the exception provides status information for the error. For more information, see . + The property of the exception provides status information for the error. For more information, see . **If you are timing out when stepping into an XML Web Service, set the timeout value for the XML Web Service call to infinite.** For more information, see [Error: Timeout While Debugging Web Services](https://msdn.microsoft.com/library/4b7df112-788a-4429-9a0c-4c6dac4fb609). @@ -146,7 +146,7 @@ class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The and properties are initialized to `null`. The property is initialized to . + The parameterless constructor initializes a new instance of the class. The property is initialized to a system-supplied message that describes the error. This message takes into account the current system culture. The and properties are initialized to `null`. The property is initialized to . @@ -214,7 +214,7 @@ instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. The property is initialized to . + The instance is initialized with the property set to the value of `message`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. The property is initialized to . @@ -350,7 +350,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `status`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. + The instance is initialized with the property set to the value of `message` and the property set to the value of `status`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. @@ -421,7 +421,7 @@ instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. The property is initialized to . + The instance is initialized with the property set to the value of `message` and the property set to the value of `innerException`. If `message` is `null`, the property is initialized to a system-supplied message. The and properties are initialized to `null`. The property is initialized to . @@ -503,7 +503,7 @@ instance is initialized with the property set to the value of `message`, the property set to the value of `innerException`, the property set to the value of `status`, and the property set to the value of `response`. If `message` is `null`, the property is initialized to a system-supplied message. + The instance is initialized with the property set to the value of `message`, the property set to the value of `innerException`, the property set to the value of `status`, and the property set to the value of `response`. If `message` is `null`, the property is initialized to a system-supplied message. @@ -630,12 +630,12 @@ sets the property to and provides the that contains the error message in the property of the that was thrown. The application can examine the to determine the actual error. + Some Internet protocols, such as HTTP, return otherwise valid responses indicating that an error has occurred at the protocol level. When the response to an Internet request indicates an error, sets the property to and provides the that contains the error message in the property of the that was thrown. The application can examine the to determine the actual error. ## Examples - The following example checks the property and prints to the console the and of the underlying instance. + The following example checks the property and prints to the console the and of the underlying instance. :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/Response/webexception_status_response.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebException/Response/webexception_status_response.vb" id="Snippet1"::: @@ -697,7 +697,7 @@ property indicates the reason for the . + The property indicates the reason for the . The value of is one of the values. @@ -707,7 +707,7 @@ ## Examples - The following example checks the property and prints to the console the and of the underlying instance. + The following example checks the property and prints to the console the and of the underlying instance. :::code language="csharp" source="~/snippets/csharp/System.Net/WebException/Response/webexception_status_response.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebException/Response/webexception_status_response.vb" id="Snippet1"::: diff --git a/xml/System.Net/WebExceptionStatus.xml b/xml/System.Net/WebExceptionStatus.xml index 4fd4dfbb80b..2576feedd42 100644 --- a/xml/System.Net/WebExceptionStatus.xml +++ b/xml/System.Net/WebExceptionStatus.xml @@ -52,11 +52,11 @@ Defines status codes for the class. - enumeration defines the status codes assigned to the property. - + enumeration defines the status codes assigned to the property. + ]]> diff --git a/xml/System.Net/WebHeaderCollection.xml b/xml/System.Net/WebHeaderCollection.xml index cfeffccbece..a0997ddf821 100644 --- a/xml/System.Net/WebHeaderCollection.xml +++ b/xml/System.Net/WebHeaderCollection.xml @@ -340,7 +340,7 @@ > [!NOTE] > The length of the *value* portion of `header`, that is, the string after the colon (:), is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of the *value* portion of `header` is greater than 65535. All other instances accept a *value* of any length. +> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of the *value* portion of `header` is greater than 65535. All other instances accept a *value* of any length. > - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of the *value* portion of `header` is greater than 65535. All other instances accept a *value* of any length. > - On .NET 5 and later versions: accepts a *value* of any length. ]]> @@ -428,7 +428,7 @@ > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. +> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET 5 and later versions: accepts a `value` of any length. ]]> @@ -497,7 +497,7 @@ > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. +> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET 5 and later versions: accepts a `value` of any length. ]]> @@ -582,7 +582,7 @@ > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. +> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET 5 and later versions: accepts a `value` of any length. ]]> @@ -666,7 +666,7 @@ > [!NOTE] > The length of `headerValue` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `headerValue` is greater than 65535. All other instances accept a `headerValue` of any length. +> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `headerValue` is greater than 65535. All other instances accept a `headerValue` of any length. > - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `headerValue` is greater than 65535. All other instances accept a `headerValue` of any length. > - On .NET 5 and later versions: accepts a `headerValue` of any length. ]]> @@ -737,7 +737,7 @@ property to get the header names a . + The following code example uses the property to get the header names a . :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: @@ -854,7 +854,7 @@ property to iterate through a . + The following code example uses the property to iterate through a . :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: @@ -999,7 +999,7 @@ ## Examples - The following code example uses the property to retrieve header values in a . + The following code example uses the property to retrieve header values in a . :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/AllKeys/webheadercollection_newprops.cs" id="Snippet1"::: @@ -1446,7 +1446,7 @@ ## Examples - The following example checks the property to see if any headers are prohibited from being set. + The following example checks the property to see if any headers are prohibited from being set. :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/IsRestricted/webheadercollection_isrestricted.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebHeaderCollection/IsRestricted/webheadercollection_isrestricted.vb" id="Snippet1"::: @@ -1544,7 +1544,7 @@ - Proxy-Connection ## Examples - The following example checks the property to see if any request headers are prohibited from being set. + The following example checks the property to see if any request headers are prohibited from being set. :::code language="csharp" source="~/snippets/csharp/System.Net/WebHeaderCollection/IsRestricted/webheadercollection_isrestricted.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebHeaderCollection/IsRestricted/webheadercollection_isrestricted.vb" id="Snippet1"::: @@ -1690,7 +1690,7 @@ > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. +> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET 5 and later versions: accepts a `value` of any length. ]]> @@ -2116,7 +2116,7 @@ > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. +> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET 5 and later versions: accepts a `value` of any length. ]]> @@ -2185,7 +2185,7 @@ > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. +> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET 5 and later versions: accepts a `value` of any length. ]]> @@ -2270,7 +2270,7 @@ > [!NOTE] > The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1. -> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. +> - On all applicable .NET Framework versions: A instance that's returned by the property will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET Core versions through version 3.1: A instance used with any header of type will throw an if the length of `value` is greater than 65535. All other instances accept a `value` of any length. > - On .NET 5 and later versions: accepts a `value` of any length. ]]> diff --git a/xml/System.Net/WebProxy.xml b/xml/System.Net/WebProxy.xml index 330e2b76263..97e2a15f46a 100644 --- a/xml/System.Net/WebProxy.xml +++ b/xml/System.Net/WebProxy.xml @@ -78,7 +78,7 @@ - The method. - The method. - These methods each supply a instance that you can further customize; the difference between them is how the instance is initialized before it is returned to your application. The constructor returns an instance of the class with the property set to `null`. When a request uses a instance in this state, no proxy is used to send the request. + These methods each supply a instance that you can further customize; the difference between them is how the instance is initialized before it is returned to your application. The constructor returns an instance of the class with the property set to `null`. When a request uses a instance in this state, no proxy is used to send the request. The method returns an instance of the class with the , , and properties set to the values used by the local computer. @@ -153,9 +153,9 @@ class with the property set to `null`. + The parameterless constructor initializes an empty instance of the class with the property set to `null`. - When the property is `null`, the method returns `true` and the method returns the destination address. + When the property is `null`, the method returns `true` and the method returns the destination address. @@ -212,7 +212,7 @@ instance is initialized with the property set to a instance containing `Address`. + The instance is initialized with the property set to a instance containing `Address`. @@ -277,7 +277,7 @@ instance is initialized with the property set to the `Address` parameter. + The instance is initialized with the property set to the `Address` parameter. @@ -398,7 +398,7 @@ instance is initialized with the property set to a instance that contains `Address` and the property set to `BypassOnLocal`. + The instance is initialized with the property set to a instance that contains `Address` and the property set to `BypassOnLocal`. @@ -459,7 +459,7 @@ instance is initialized with the property set to a instance of the form http:// `Host` : `Port`. + The instance is initialized with the property set to a instance of the form http:// `Host` : `Port`. @@ -526,7 +526,7 @@ instance is initialized with the property set to `Address` and with the property set to `BypassOnLocal`. + The instance is initialized with the property set to `Address` and with the property set to `BypassOnLocal`. @@ -599,7 +599,7 @@ instance is initialized with the property set to a instance that contains `Address`, the property set to `BypassOnLocal`, and the property set to `BypassList`. + The instance is initialized with the property set to a instance that contains `Address`, the property set to `BypassOnLocal`, and the property set to `BypassList`. @@ -682,7 +682,7 @@ instance is initialized with the property set to `Address`, the property set to `BypassOnLocal`, and the property set to `BypassList`. + The instance is initialized with the property set to `Address`, the property set to `BypassOnLocal`, and the property set to `BypassList`. @@ -757,7 +757,7 @@ instance is initialized with the property set to a instance that contains `Address`, the property set to `BypassOnLocal`, the property set to `BypassList`, and the property set to `Credentials`. + The instance is initialized with the property set to a instance that contains `Address`, the property set to `BypassOnLocal`, the property set to `BypassList`, and the property set to `Credentials`. @@ -836,7 +836,7 @@ instance is initialized with the property set to `Address`, the property set to `BypassOnLocal`, the property set to `BypassList`, and the property set to `Credentials`. + The instance is initialized with the property set to `Address`, the property set to `BypassOnLocal`, the property set to `BypassList`, and the property set to `Credentials`. @@ -893,9 +893,9 @@ property contains the address of the proxy server. When automatic proxy detection is not enabled, and no automatic configuration script is specified, the property and determine the proxy used for a request. + The property contains the address of the proxy server. When automatic proxy detection is not enabled, and no automatic configuration script is specified, the property and determine the proxy used for a request. - When the property is `null`, requests bypass the proxy and connect directly to the destination host. + When the property is `null`, requests bypass the proxy and connect directly to the destination host. @@ -1012,12 +1012,12 @@ property contains an array of regular expressions that describe URIs that are accessed directly instead of through the proxy server. + The property contains an array of regular expressions that describe URIs that are accessed directly instead of through the proxy server. ## Examples - The following code example displays the properties of a object, including its property. + The following code example displays the properties of a object, including its property. :::code language="csharp" source="~/snippets/csharp/System.Net/WebProxy/Address/proxy.cs" id="Snippet1"::: @@ -1070,7 +1070,7 @@ property determines whether to use the proxy server when accessing local Internet resources. + The setting of the property determines whether to use the proxy server when accessing local Internet resources. If is `true`, requests to local Internet resources do not use the proxy server. Local requests are identified by the lack of a period (.) in the URI, as in `http://webserver/`, or access the local server, including `http://localhost`, `http://loopback`, or `http://127.0.0.1`. When is `false`, all Internet requests are made through the proxy server. @@ -1145,10 +1145,10 @@ property contains the authentication credentials to send to the proxy server in response to an HTTP 407 (proxy authorization) status code. In most client scenarios, you should use the , which are the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. + The property contains the authentication credentials to send to the proxy server in response to an HTTP 407 (proxy authorization) status code. In most client scenarios, you should use the , which are the credentials of the currently logged on user. To do this, set the property to `true` instead of setting this property. > [!NOTE] -> If you set the property to credentials other than the , setting the property to `true` causes a . To prevent this, you must set the property to `null` before setting the property to `true`. Likewise, you cannot set this property to any value when is `true`. +> If you set the property to credentials other than the , setting the property to `true` causes a . To prevent this, you must set the property to `null` before setting the property to `true`. Likewise, you cannot set this property to any value when is `true`. ]]> @@ -1340,7 +1340,7 @@ compares `destination` with the contents of , using the method. If returns `true`, returns `destination` and the instance does not use the proxy server. - If `destination` is not in , the instance uses the proxy server and the property is returned. + If `destination` is not in , the instance uses the proxy server and the property is returned. @@ -1538,9 +1538,9 @@ object should, if requested by the server, be authenticated using the credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made. + Set this property to `true` when requests made by this 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. - The following table shows the effect of setting the value, based on the value of the property. + The following table shows the effect of setting the value, based on the value of the property. | value| value|Effect| |----------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|------------| @@ -1549,7 +1549,7 @@ |`null`|`true`| is set to .| |Any value other than or `null`|`true` or `false`|Setting throws an exception.| - If is `false`, you can change the property to any credentials. If is `true`, changing the property from (the value that is set when the property is set to `true`) will throw an exception. + If is `false`, you can change the property to any credentials. If is `true`, changing the property from (the value that is set when the property is set to `true`) will throw an exception. ]]> diff --git a/xml/System.Net/WebRequest.xml b/xml/System.Net/WebRequest.xml index ea35c84cdb3..aa7476abd46 100644 --- a/xml/System.Net/WebRequest.xml +++ b/xml/System.Net/WebRequest.xml @@ -84,7 +84,7 @@ Requests are sent from an application to a particular URI, such as a Web page on a server. The URI determines the proper descendant class to create from a list of descendants registered for the application. descendants are typically registered to handle a specific protocol, such as HTTP or FTP, but can be registered to handle a request to a specific server or path on a server. - The class throws a when errors occur while accessing an Internet resource. The property is one of the values that indicates the source of the error. When is , the property contains the received from the Internet resource. + The class throws a when errors occur while accessing an Internet resource. The property is one of the values that indicates the source of the error. When is , the property contains the received from the Internet resource. Because the class is an `abstract` class, the actual behavior of instances at run time is determined by the descendant class returned by method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -619,7 +619,7 @@ The current cache policy and the presence of the requested resource in the cache determine whether a response can be retrieved from the cache. Using cached responses usually improves application performance, but there is a risk that the response in the cache does not match the response on the server. - Default cache policy can be specified in the Machine.config configuration file or by setting the property for requests that use the Hypertext Transfer Protocol (HTTP) or Secure Hypertext Transfer Protocol (HTTPS) URI scheme. + Default cache policy can be specified in the Machine.config configuration file or by setting the property for requests that use the Hypertext Transfer Protocol (HTTP) or Secure Hypertext Transfer Protocol (HTTPS) URI scheme. A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request. @@ -695,7 +695,7 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property associates specific requests within an application to one or more connection pools. + The property associates specific requests within an application to one or more connection pools. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -760,7 +760,7 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains the number of bytes of data sent to the Internet resource by the instance. + The property contains the number of bytes of data sent to the Internet resource by the instance. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -768,7 +768,7 @@ ## Examples - The following example sets the property to the amount of bytes in the outgoing byte buffer. + The following example sets the property to the amount of bytes in the outgoing byte buffer. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/ContentLength/webrequest_contenttype.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/ContentLength/webrequest_contenttype.vb" id="Snippet4"::: @@ -839,7 +839,7 @@ [!INCLUDE [obsolete-notice](~/includes/web-request-obsolete.md)] - The property contains the media type of the request. This is typically the MIME encoding of the content. + The property contains the media type of the request. This is typically the MIME encoding of the content. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -847,7 +847,7 @@ ## Examples - The following example sets the property to the appropriate media type. + The following example sets the property to the appropriate media type. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/ContentLength/webrequest_contenttype.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/ContentLength/webrequest_contenttype.vb" id="Snippet4"::: @@ -1207,7 +1207,7 @@ Note: In .NET for Win When a URI that begins with `http://` or `https://` is passed in the `requestUriString` parameter, a is returned by . Any other scheme will throw a . - The method uses the `requestUriString` parameter to create a instance that it passes to the new . If the method is successful, the property on the returned instance is set to `false`. + The method uses the `requestUriString` parameter to create a instance that it passes to the new . If the method is successful, the property on the returned instance is set to `false`. .NET includes support for the `http://` and `https://` URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes. @@ -1280,7 +1280,7 @@ Note: In .NET for Win When a URI that begins with `http://` or `http://` is passed in the `requestUri` parameter, an is returned by . Another other scheme will throw a . - The method uses the `requestUri` parameter to create a new instance. If the method is successful, the property on the returned instance is set to `false`. + The method uses the `requestUri` parameter to create a new instance. If the method is successful, the property on the returned instance is set to `false`. .NET includes support for the `http://` and `https://` URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes. @@ -1398,7 +1398,7 @@ This property allows an application to determine which property contains the authentication credentials required to access the Internet resource. + The property contains the authentication credentials required to access the Internet resource. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -1406,7 +1406,7 @@ This property allows an application to determine which property using the default credentials of the current user. When the request is made, credentials stored in this property are used to validate the client. This is identical to setting the property to `true`. + The following example sets the property using the default credentials of the current user. When the request is made, credentials stored in this property are used to validate the client. This is identical to setting the property to `true`. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Overview/webrequestget.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/Overview/webrequestget.vb" id="Snippet2"::: @@ -1476,7 +1476,7 @@ This property allows an application to determine which property specified for this request. +- There is no property specified for this request. - The machine and application configuration files do not specify a cache policy that is applicable to the Uniform Resource Identifier (URI) used to create this request. @@ -1556,11 +1556,11 @@ This property allows an application to determine which property gets or sets the global proxy. The property determines the default proxy that all instances use if the request supports proxies and no proxy is set explicitly using the property. Proxies are currently supported by and . + The property gets or sets the global proxy. The property determines the default proxy that all instances use if the request supports proxies and no proxy is set explicitly using the property. Proxies are currently supported by and . - The property reads proxy settings from the app.config file. If there is no config file, the current user's Internet options proxy settings are used. + The property reads proxy settings from the app.config file. If there is no config file, the current user's Internet options proxy settings are used. - If the property is set to null, all subsequent instances of the class created by the or methods do not have a proxy. + If the property is set to null, all subsequent instances of the class created by the or methods do not have a proxy. ]]> @@ -1981,7 +1981,7 @@ This property allows an application to determine which property to 10000 milliseconds. If the timeout period expires before the resource can be returned, a is thrown. + The following example sets the property to 10000 milliseconds. If the timeout period expires before the resource can be returned, a is thrown. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/GetResponse/webrequest_timeout.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/GetResponse/webrequest_timeout.vb" id="Snippet1"::: @@ -2160,7 +2160,7 @@ This property allows an application to determine which property contains a instance containing the header information to send to the Internet resource. + The property contains a instance containing the header information to send to the Internet resource. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -2297,7 +2297,7 @@ This property allows an application to determine which property contains the request method to use in this request. + When overridden in a descendant class, the property contains the request method to use in this request. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -2305,7 +2305,7 @@ This property allows an application to determine which property to POST to indicate that the request will post data to the target host. + The following example sets the property to POST to indicate that the request will post data to the target host. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/BeginGetRequestStream/webrequest_begingetrequest.vb" id="Snippet3"::: @@ -2369,7 +2369,7 @@ This property allows an application to determine which property indicates whether to send authentication information with subsequent requests without waiting to be challenged by the server. When is `false`, the waits for an authentication challenge before sending authentication information. + With the exception of the first request, the property indicates whether to send authentication information with subsequent requests without waiting to be challenged by the server. When is `false`, the waits for an authentication challenge before sending authentication information. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -2437,7 +2437,7 @@ This property allows an application to determine which property identifies the network proxy that the request uses to access the Internet resource. The request is made through the proxy server rather than directly to the Internet resource. + The property identifies the network proxy that the request uses to access the Internet resource. The request is made through the proxy server rather than directly to the Internet resource. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -2640,7 +2640,7 @@ This property allows an application to determine which property contains the instance that method uses to create the request. + When overridden in a descendant class, the property contains the instance that method uses to create the request. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -2648,7 +2648,7 @@ This property allows an application to determine which property to determine the site originally requested. + The following example checks the property to determine the site originally requested. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/RequestUri/webrequest_requesturi.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/RequestUri/webrequest_requesturi.vb" id="Snippet1"::: @@ -2777,7 +2777,7 @@ This property allows an application to determine which property indicates the length of time, in milliseconds, until the request times out and throws a . The property affects only synchronous requests made with the method. To time out asynchronous requests, use the method. + The property indicates the length of time, in milliseconds, until the request times out and throws a . The property affects only synchronous requests made with the method. To time out asynchronous requests, use the method. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and . @@ -2785,7 +2785,7 @@ This property allows an application to determine which property to 10000 milliseconds. If the timeout period expires before the resource can be returned, a is thrown. + The following example sets the property to 10000 milliseconds. If the timeout period expires before the resource can be returned, a is thrown. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/GetResponse/webrequest_timeout.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/GetResponse/webrequest_timeout.vb" id="Snippet1"::: @@ -2849,7 +2849,7 @@ This property allows an application to determine which 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. + Set this property to `true` when requests made by this 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. ]]> diff --git a/xml/System.Net/WebRequestMethods+File.xml b/xml/System.Net/WebRequestMethods+File.xml index 83048b7a13b..374731732b3 100644 --- a/xml/System.Net/WebRequestMethods+File.xml +++ b/xml/System.Net/WebRequestMethods+File.xml @@ -51,11 +51,11 @@ Represents the types of file protocol methods that can be used with a FILE request. This class cannot be inherited. - property that determines the protocol method that is to be used to perform a requested action, such as copying and retrieving a file. - + property that determines the protocol method that is to be used to perform a requested action, such as copying and retrieving a file. + ]]> diff --git a/xml/System.Net/WebRequestMethods+Ftp.xml b/xml/System.Net/WebRequestMethods+Ftp.xml index 0815756ae6a..6cefa0b9709 100644 --- a/xml/System.Net/WebRequestMethods+Ftp.xml +++ b/xml/System.Net/WebRequestMethods+Ftp.xml @@ -51,11 +51,11 @@ Represents the types of FTP protocol methods that can be used with an FTP request. This class cannot be inherited. - property that determines the protocol method that is to be used to perform a requested action, such as uploading or downloading a file. - + property that determines the protocol method that is to be used to perform a requested action, such as uploading or downloading a file. + ]]> diff --git a/xml/System.Net/WebResponse.xml b/xml/System.Net/WebResponse.xml index ab9d803b079..e365d4d331c 100644 --- a/xml/System.Net/WebResponse.xml +++ b/xml/System.Net/WebResponse.xml @@ -356,7 +356,7 @@ property contains the length, in bytes, of the response from the Internet resource. For request methods that contain header information, the does not include the length of the header information. + The property contains the length, in bytes, of the response from the Internet resource. For request methods that contain header information, the does not include the length of the header information. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -364,7 +364,7 @@ ## Examples - The following example uses the property to obtain the Length of the resource returned. + The following example uses the property to obtain the Length of the resource returned. :::code language="csharp" source="~/snippets/csharp/System.Net/WebResponse/ContentLength/webresponse_contentlength_type.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebResponse/ContentLength/webresponse_contentlength_type.vb" id="Snippet1"::: @@ -426,7 +426,7 @@ property contains the MIME content type of the response from the Internet resource, if known. + The property contains the MIME content type of the response from the Internet resource, if known. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -434,7 +434,7 @@ ## Examples - The following example uses the property to obtain the content type of the response. + The following example uses the property to obtain the content type of the response. :::code language="csharp" source="~/snippets/csharp/System.Net/WebResponse/ContentLength/webresponse_contentlength_type.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebResponse/ContentLength/webresponse_contentlength_type.vb" id="Snippet1"::: @@ -742,7 +742,7 @@ property contains the name-value header pairs returned in the response. + The property contains the name-value header pairs returned in the response. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -814,7 +814,7 @@ property to set and the class to enumerate the current caching policy. + The current cache policy and the presence of the requested resource in the cache determine whether a response can be retrieved from the cache. Using cached responses usually improves application performance, but there is a risk that the response in the cache does not match the response on the server. Use the property to set and the class to enumerate the current caching policy. Note that getting this property can throw . @@ -868,7 +868,7 @@ property using the or enumeration value. The default value for the property contains and . + To request mutual authentication, set the property using the or enumeration value. The default value for the property contains and . Note that getting this property can throw . @@ -933,7 +933,7 @@ property contains the URI of the Internet resource that actually provided the response data. This resource might not be the originally requested URI if the underlying protocol allows redirection of the request. + The property contains the URI of the Internet resource that actually provided the response data. This resource might not be the originally requested URI if the underlying protocol allows redirection of the request. > [!NOTE] > The class is an `abstract` class. The actual behavior of instances at run time is determined by the descendant class returned by . For more information about default values and exceptions, please see the documentation for the descendant classes, such as and . @@ -941,7 +941,7 @@ ## Examples - The following example uses the property to determine the location from which the originated. + The following example uses the property to determine the location from which the originated. :::code language="csharp" source="~/snippets/csharp/System.Net/WebRequest/Create/webresponse_responseuri.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Net/WebRequest/Create/webresponse_responseuri.vb" id="Snippet1"::: diff --git a/xml/System.Net/WriteStreamClosedEventArgs.xml b/xml/System.Net/WriteStreamClosedEventArgs.xml index 554ad7b6f03..54268c32227 100644 --- a/xml/System.Net/WriteStreamClosedEventArgs.xml +++ b/xml/System.Net/WriteStreamClosedEventArgs.xml @@ -139,11 +139,11 @@ Gets the error value when a write stream is closed. Returns . - property is an object, the asynchronous operation did not complete correctly. - + property is an object, the asynchronous operation did not complete correctly. + ]]> diff --git a/xml/System.Numerics/BigInteger.xml b/xml/System.Numerics/BigInteger.xml index 4a6690f1172..110773cddd2 100644 --- a/xml/System.Numerics/BigInteger.xml +++ b/xml/System.Numerics/BigInteger.xml @@ -3305,7 +3305,7 @@ For this method matches the IEE property is used to compare a value to -1 or to assign -1 to a object. + The property is used to compare a value to -1 or to assign -1 to a object. ]]> @@ -3589,7 +3589,7 @@ For this method matches the IEE property is usually used to compare a value to 1 or to assign 1 to a object. + The property is usually used to compare a value to 1 or to assign 1 to a object. ]]> @@ -9876,7 +9876,7 @@ If `provider` is `null`, the object property is equivalent to the method for the primitive numeric types. + The property is equivalent to the method for the primitive numeric types. ]]> @@ -12551,7 +12551,7 @@ Elements in square brackets ([ and ]) are optional. The following table describe |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 `value` 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.| +|*$*|A culture-specific currency symbol. Its position in `value` 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.| @@ -12681,7 +12681,7 @@ If `provider` is `null`, the object |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.| +|*$*|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.| diff --git a/xml/System.Numerics/Complex.xml b/xml/System.Numerics/Complex.xml index b3ca7ffb60d..9d96c8d943c 100644 --- a/xml/System.Numerics/Complex.xml +++ b/xml/System.Numerics/Complex.xml @@ -290,16 +290,16 @@ property. The absolute value of a complex number `a + bi` is calculated as follows: + The absolute value of a complex number is equivalent to its property. The absolute value of a complex number `a + bi` is calculated as follows: - If `b = 0`, the result is `a`. - If `a > b`, the result is $a \times \sqrt{1 + \frac{b^2}{a^2}}$. - If `b > a`, the result is $b \times \sqrt{1 + \frac{a^2}{b^2}}$. - If the calculation of the absolute value results in an overflow, the method returns either or . If either the or property is and the other property is neither nor , the method returns . + If the calculation of the absolute value results in an overflow, the method returns either or . If either the or property is and the other property is neither nor , the method returns . ## Examples - The following example calculates the absolute value of a complex number and demonstrates that it is equivalent to the value of the property. + The following example calculates the absolute value of a complex number and demonstrates that it is equivalent to the value of the property. :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Abs/abs1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Numerics/Complex/Abs/abs1.fs" id="Snippet1"::: @@ -1615,7 +1615,7 @@ $\frac{ac + bd}{c^2 + d^2} + (\frac{bc - ad}{c^2 + d^2})i$ property returns the value of `b`. + Given a complex number `a + bi`, the property returns the value of `b`. ## Examples The following example instantiates an array of objects and displays the real and imaginary components of each in the form `a + bi`. @@ -2615,7 +2615,7 @@ This function returns `true` for a complex number `a + bi` where `b` is zero. property is equivalent to the absolute value of a complex number. It specifies the distance from the origin (the intersection of the x-axis and the y-axis in the Cartesian coordinate system) to the two-dimensional point represented by a complex number. The absolute value is calculated as follows: + The property is equivalent to the absolute value of a complex number. It specifies the distance from the origin (the intersection of the x-axis and the y-axis in the Cartesian coordinate system) to the two-dimensional point represented by a complex number. The absolute value is calculated as follows: $| a + bi | = \sqrt{a \times a + b \times b}$ @@ -2626,7 +2626,7 @@ This function returns `true` for a complex number `a + bi` where `b` is zero. You can instantiate a complex number based on its polar coordinates instead of its Cartesian coordinates by calling the method. ## Examples - The following example calculates the absolute value of a complex number and demonstrates that it is equivalent to the value of the property. + The following example calculates the absolute value of a complex number and demonstrates that it is equivalent to the value of the property. :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Abs/abs1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Numerics/Complex/Abs/abs1.fs" id="Snippet1"::: @@ -3654,7 +3654,7 @@ Languages that don't support custom operators and operator overloading can call ## Remarks Explicit conversion operators define types that can be converted to a object. 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` in Visual Basic) is used. Otherwise, they display a compiler error. - The conversion of a value to the real part of a complex number can result in a loss of precision because a , which is the type of the complex number's property, has fewer significant digits than a . + The conversion of a value to the real part of a complex number can result in a loss of precision because a , which is the type of the complex number's property, has fewer significant digits than a . ## Examples The following example illustrates the explicit conversion of values to values. @@ -3751,9 +3751,9 @@ Languages that don't support custom operators and operator overloading can call ## Remarks Explicit conversion operators define types that can be converted to a object. 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` in Visual Basic) is used. Otherwise, they display a compiler error. - The conversion of a value to the real part of a complex number can result in a loss of precision because a , which is the type of the complex number's property, has fewer significant digits than a . + The conversion of a value to the real part of a complex number can result in a loss of precision because a , which is the type of the complex number's property, has fewer significant digits than a . - If the conversion is unsuccessful because the value is out of the range of the type, the operation does not throw an . Instead, if `value` is less than , the result is a complex number that has a property value equal to . If `value` is greater than , the result is a complex number that has a property value equal to . + If the conversion is unsuccessful because the value is out of the range of the type, the operation does not throw an . Instead, if `value` is less than , the result is a complex number that has a property value equal to . If `value` is greater than , the result is a complex number that has a property value equal to . ## Examples The following example illustrates the explicit conversion of values to values. @@ -5540,7 +5540,7 @@ Languages that don't support custom operators can call the property) is the distance from the point of origin to the point that is represented by the complex number. + You can identify a complex number by its Cartesian coordinates on the complex plane or by its polar coordinates. The phase (argument) of a complex number is the angle to the real axis of a line drawn from the point of origin (the intersection of the x-axis and the y-axis) to the point represented by the complex number. The magnitude (represented by the property) is the distance from the point of origin to the point that is represented by the complex number. You can instantiate a complex number based on its polar coordinates instead of its Cartesian coordinates by calling the method. @@ -5726,7 +5726,7 @@ Languages that don't support custom operators can call the property returns the value of `a`. + Given a complex number `a + bi`, the property returns the value of `a`. ## Examples The following example instantiates an array of objects and displays the real and imaginary components of each in the form `a + bi`. diff --git a/xml/System.Numerics/Vector2.xml b/xml/System.Numerics/Vector2.xml index bf6fe1f3b11..4e9e63ddc69 100644 --- a/xml/System.Numerics/Vector2.xml +++ b/xml/System.Numerics/Vector2.xml @@ -5803,7 +5803,7 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using the "G" (general) format string and the formatting conventions of the current culture. The "\<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. ]]> @@ -5876,7 +5876,7 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and the current culture's formatting conventions. The "\<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. ]]> @@ -5952,7 +5952,7 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi " characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and `formatProvider`. The "\<" and ">" characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. ]]> diff --git a/xml/System.Numerics/Vector3.xml b/xml/System.Numerics/Vector3.xml index e4004ce17ef..ab05d27a5b3 100644 --- a/xml/System.Numerics/Vector3.xml +++ b/xml/System.Numerics/Vector3.xml @@ -5891,7 +5891,7 @@ " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using the "G" (general) format string and the formatting conventions of the current culture. The "\<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. ]]> @@ -5964,7 +5964,7 @@ " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and the current culture's formatting conventions. The "\<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. ]]> @@ -6040,7 +6040,7 @@ " characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and `formatProvider`. The "\<" and ">" characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. ]]> diff --git a/xml/System.Numerics/Vector4.xml b/xml/System.Numerics/Vector4.xml index a7d417fff6e..62cadff1cc6 100644 --- a/xml/System.Numerics/Vector4.xml +++ b/xml/System.Numerics/Vector4.xml @@ -56,13 +56,13 @@ Represents a vector with four single-precision floating-point values. - structure provides support for hardware acceleration. + structure provides support for hardware acceleration. + + [!INCLUDE[vectors-are-rows-paragraph](~/includes/system-numerics-vectors-are-rows.md)] - [!INCLUDE[vectors-are-rows-paragraph](~/includes/system-numerics-vectors-are-rows.md)] - ]]> @@ -884,11 +884,11 @@ The destination array. Copies the elements of the vector to a specified array. - @@ -995,21 +995,21 @@ The index at which to copy the first element of the vector. Copies the elements of the vector to a specified array starting at a specified index position. - is . The number of elements in the current instance is greater than in the array. - is less than zero. - - -or- - + is less than zero. + + -or- + is greater than or equal to the array length. is multidimensional. @@ -1813,11 +1813,11 @@ if the two vectors are equal; otherwise, . - , , , and elements are equal. - + , , , and elements are equal. + ]]> @@ -1883,11 +1883,11 @@ if the current instance and are equal; otherwise, . If is , the method returns . - object and their corresponding elements are equal. - + object and their corresponding elements are equal. + ]]> @@ -3075,11 +3075,11 @@ Returns the length of the vector squared. The vector's length squared. - method. - + method. + ]]> @@ -3172,12 +3172,12 @@ Performs a linear interpolation between two vectors based on the given weighting. The interpolated vector. - @@ -4536,11 +4536,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Gets a vector whose 4 elements are equal to one. Returns . - @@ -4625,11 +4625,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Adds two vectors together. The summed vector. - method defines the addition operation for objects. - + method defines the addition operation for objects. + ]]> @@ -4762,11 +4762,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Divides the first vector by the second. The vector that results from dividing by . - method defines the division operation for objects. - + method defines the division operation for objects. + ]]> @@ -4818,11 +4818,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Divides the specified vector by a specified scalar value. The result of the division. - method defines the division operation for objects. - + method defines the division operation for objects. + ]]> @@ -4875,11 +4875,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi if and are equal; otherwise, . - objects are equal if each element in `left` is equal to the corresponding element in `right`. - + objects are equal if each element in `left` is equal to the corresponding element in `right`. + ]]> @@ -5062,11 +5062,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Returns a new vector whose values are the product of each pair of elements in two specified vectors. The element-wise product vector. - method defines the multiplication operation for objects. - + method defines the multiplication operation for objects. + ]]> @@ -5118,11 +5118,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Multiples the specified vector by the specified scalar value. The scaled vector. - method defines the multiplication operation for objects. - + method defines the multiplication operation for objects. + ]]> @@ -5174,11 +5174,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Multiples the scalar value by the specified vector. The scaled vector. - method defines the multiplication operation for objects. - + method defines the multiplication operation for objects. + ]]> @@ -5298,11 +5298,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Subtracts the second vector from the first. The vector that results from subtracting from . - method defines the subtraction operation for objects. - + method defines the subtraction operation for objects. + ]]> @@ -5352,11 +5352,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Negates the specified vector. The negated vector. - method defines the unary negation operation for objects. - + method defines the unary negation operation for objects. + ]]> @@ -5923,11 +5923,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Returns the string representation of the current instance using default formatting. The string representation of the current instance. - " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. - + " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + ]]> @@ -5996,11 +5996,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Returns the string representation of the current instance using the specified format string to format individual elements. The string representation of the current instance. - " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. - + " characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + ]]> Standard Numeric Format Strings @@ -6072,11 +6072,11 @@ The behavior of this method changed in .NET 5. For more information, see [Behavi Returns the string representation of the current instance using the specified format string to format individual elements and the specified format provider to define culture-specific formatting. The string representation of the current instance. - " characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. - + " characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. + ]]> Standard Numeric Format Strings diff --git a/xml/System.Numerics/Vector`1.xml b/xml/System.Numerics/Vector`1.xml index 230451ccec3..eec5a6205ca 100644 --- a/xml/System.Numerics/Vector`1.xml +++ b/xml/System.Numerics/Vector`1.xml @@ -432,10 +432,10 @@ The type `T` can be any of the following numeric types: is . - is less than zero. - - -or- - + is less than zero. + + -or- + The length of minus is less than . .NET 5 and later: Type is not supported. @@ -737,9 +737,9 @@ The type `T` can be any of the following numeric types: The number of elements stored in the vector. To be added. Access to the property getter via reflection is not supported. - + -or- - + .NET 5 and later: Type is not supported. @@ -1041,10 +1041,10 @@ The type `T` can be any of the following numeric types: The element at index . To be added. - is less than zero. - - -or- - + is less than zero. + + -or- + is greater than or equal to . .NET 5 and later: Type is not supported. @@ -2900,7 +2900,7 @@ The type `T` can be any of the following numeric types: property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using the "G" (general) format string and the formatting conventions of the current culture. The current culture's property followed by a space is used to separate each element. ]]> @@ -2970,7 +2970,7 @@ The type `T` can be any of the following numeric types: property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and the current culture's formatting conventions. The current culture's property followed by a space is used to separate each element. ]]> @@ -3041,7 +3041,7 @@ The type `T` can be any of the following numeric types: property followed by a space is used to separate each element. + This method returns a string in which each element of the vector is formatted using `format` and `formatProvider`, and the format provider's property followed by a space is used to separate each element. ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintBooleanProperty.xml b/xml/System.Printing.IndexedProperties/PrintBooleanProperty.xml index cabbac236de..c2283a86c41 100644 --- a/xml/System.Printing.IndexedProperties/PrintBooleanProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintBooleanProperty.xml @@ -24,14 +24,14 @@ Represents a property (and its value) of a printing system hardware or software component. - @@ -72,11 +72,11 @@ The name of the attribute that the represents. Initializes a new instance of the class for the specified attribute. - property of a print system object, including casing. For example, the property of a object must be spelled "IsBusy", not "Busy" or "Isbusy". - + property of a print system object, including casing. For example, the property of a object must be spelled "IsBusy", not "Busy" or "Isbusy". + ]]> @@ -110,19 +110,19 @@ The value of the property that the represents. Initializes a new instance of the class for the specified property that is using the specified value. - property of a print system object, including casing. For example, the property of a object must be spelled "IsBusy", not "Busy" or "Isbusy". - - - -## Examples - The following example shows how to use this constructor while installing a second printer that differs in its properties from an existing printer only in location, port, and shared status. - + property of a print system object, including casing. For example, the property of a object must be spelled "IsBusy", not "Busy" or "Isbusy". + + + +## Examples + The following example shows how to use this constructor while installing a second printer that differs in its properties from an existing printer only in location, port, and shared status. + :::code language="csharp" source="~/snippets/csharp/System.Printing/LocalPrintServer/.ctor/Program.cs" id="Snippetcloneprinter"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintDateTimeProperty.xml b/xml/System.Printing.IndexedProperties/PrintDateTimeProperty.xml index cdd43c04e60..f1b835ff20d 100644 --- a/xml/System.Printing.IndexedProperties/PrintDateTimeProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintDateTimeProperty.xml @@ -69,11 +69,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "StartTimeOfDay", not "StartTime" or "Starttimeofday". - + property of a print system object, including casing. For example, the property of a object must be spelled "StartTimeOfDay", not "StartTime" or "Starttimeofday". + ]]> @@ -107,11 +107,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified attribute. - property of a print system object, including casing. For example, the property of a object must be spelled "StartTimeOfDay", not "StartTime" or "Starttimeofday". - + property of a print system object, including casing. For example, the property of a object must be spelled "StartTimeOfDay", not "StartTime" or "Starttimeofday". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintDriverProperty.xml b/xml/System.Printing.IndexedProperties/PrintDriverProperty.xml index c74f8479404..45286749689 100644 --- a/xml/System.Printing.IndexedProperties/PrintDriverProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintDriverProperty.xml @@ -62,11 +62,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "QueueDriver", not "PrintDriver" or "Queuedriver". - + property of a print system object, including casing. For example, the property of a object must be spelled "QueueDriver", not "PrintDriver" or "Queuedriver". + ]]> @@ -100,11 +100,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified attribute. - property of a print system object, including casing. For example, the property of a object must be spelled "QueueDriver", not "PrintDriver" or "Queuedriver". - + property of a print system object, including casing. For example, the property of a object must be spelled "QueueDriver", not "PrintDriver" or "Queuedriver". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintInt32Property.xml b/xml/System.Printing.IndexedProperties/PrintInt32Property.xml index 5085bcb8121..2d642329d5a 100644 --- a/xml/System.Printing.IndexedProperties/PrintInt32Property.xml +++ b/xml/System.Printing.IndexedProperties/PrintInt32Property.xml @@ -62,11 +62,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "AveragePagesPerMinute", not "AveragePPM" or "AveragePagesperMinute". - + property of a print system object, including casing. For example, the property of a object must be spelled "AveragePagesPerMinute", not "AveragePPM" or "AveragePagesperMinute". + ]]> @@ -100,11 +100,11 @@ The value of the property that the represents. Initializes a new instance of the class for the specified attribute and gives it the specified value. - property of a print system object, including casing. For example, the property of a object must be spelled "AveragePagesPerMinute", not "AveragePPM" or "AveragePagesperMinute". - + property of a print system object, including casing. For example, the property of a object must be spelled "AveragePagesPerMinute", not "AveragePPM" or "AveragePagesperMinute". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintJobPriorityProperty.xml b/xml/System.Printing.IndexedProperties/PrintJobPriorityProperty.xml index 023bf80e72b..7ccc0d618f0 100644 --- a/xml/System.Printing.IndexedProperties/PrintJobPriorityProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintJobPriorityProperty.xml @@ -69,11 +69,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "Priority", not "JobPriority". - + property of a print system object, including casing. For example, the property of a object must be spelled "Priority", not "JobPriority". + ]]> @@ -107,11 +107,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified attribute. - property of a print system object, including casing. For example, the property of a object must be spelled "Priority", not "JobPriority". - + property of a print system object, including casing. For example, the property of a object must be spelled "Priority", not "JobPriority". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintJobStatusProperty.xml b/xml/System.Printing.IndexedProperties/PrintJobStatusProperty.xml index 107fb7b76cd..4728105d373 100644 --- a/xml/System.Printing.IndexedProperties/PrintJobStatusProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintJobStatusProperty.xml @@ -69,11 +69,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "JobStatus", not "Status" or "Jobstatus". - + property of a print system object, including casing. For example, the property of a object must be spelled "JobStatus", not "Status" or "Jobstatus". + ]]> @@ -107,11 +107,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "JobStatus", not "Status" or "Jobstatus". - + property of a print system object, including casing. For example, the property of a object must be spelled "JobStatus", not "Status" or "Jobstatus". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintPortProperty.xml b/xml/System.Printing.IndexedProperties/PrintPortProperty.xml index 68aa5078d6a..0ca2cbfc7cb 100644 --- a/xml/System.Printing.IndexedProperties/PrintPortProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintPortProperty.xml @@ -62,11 +62,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "QueuePort", not "Port" or "Queueport". - + property of a print system object, including casing. For example, the property of a object must be spelled "QueuePort", not "Port" or "Queueport". + ]]> @@ -100,11 +100,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "QueuePort", not "Port" or "Queueport". - + property of a print system object, including casing. For example, the property of a object must be spelled "QueuePort", not "Port" or "Queueport". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintProcessorProperty.xml b/xml/System.Printing.IndexedProperties/PrintProcessorProperty.xml index b5991781692..bb786722a5c 100644 --- a/xml/System.Printing.IndexedProperties/PrintProcessorProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintProcessorProperty.xml @@ -62,11 +62,11 @@ The that is converted. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "QueuePrintProcessor", not "PrintProcessor" or "Queueprintprocessor". - + property of a print system object, including casing. For example, the property of a object must be spelled "QueuePrintProcessor", not "PrintProcessor" or "Queueprintprocessor". + ]]> @@ -100,11 +100,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "QueuePrintProcessor", not "PrintProcessor" or "Queueprintprocessor". - + property of a print system object, including casing. For example, the property of a object must be spelled "QueuePrintProcessor", not "PrintProcessor" or "Queueprintprocessor". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintProperty.xml b/xml/System.Printing.IndexedProperties/PrintProperty.xml index a3cdc0ceab6..0819a5ebba8 100644 --- a/xml/System.Printing.IndexedProperties/PrintProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintProperty.xml @@ -80,7 +80,7 @@ property of a object must be spelled "QueuePort", not "PrintPort", "Port", or "Queueport". + The `attributeName` should be spelled exactly the same as the name of some particular property of a print system object, including casing. For example, the property of a object must be spelled "QueuePort", not "PrintPort", "Port", or "Queueport". ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml b/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml index 66b86c23dcc..8049812ca43 100644 --- a/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml +++ b/xml/System.Printing.IndexedProperties/PrintPropertyDictionary.xml @@ -48,7 +48,7 @@ dictionary. The property of each in the collection is an instance of a class that is derived from . + The collection takes the form of a dictionary. The property of each in the collection is an instance of a class that is derived from . @@ -177,7 +177,7 @@ property of `attributeValue` becomes the property of the new . The as a whole becomes the property of the new . + The property of `attributeValue` becomes the property of the new . The as a whole becomes the property of the new . For another way to add an entry to the dictionary, see . @@ -382,7 +382,7 @@ property of a object must be spelled "QueuePort", not "PrintPort", "Port", or "Queueport". + The `attribName` must be spelled exactly the same as the name of some particular property of a print system object, including casing. For example, the property of a object must be spelled "QueuePort", not "PrintPort", "Port", or "Queueport". ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintQueueAttributeProperty.xml b/xml/System.Printing.IndexedProperties/PrintQueueAttributeProperty.xml index 4c35ac7361f..28c9f4babbb 100644 --- a/xml/System.Printing.IndexedProperties/PrintQueueAttributeProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintQueueAttributeProperty.xml @@ -62,11 +62,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "QueueAttributes", not "Attributes" or "Queueattributes". - + property of a print system object, including casing. For example, the property of a object must be spelled "QueueAttributes", not "Attributes" or "Queueattributes". + ]]> @@ -100,11 +100,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "QueueAttributes", not "Attributes" or "Queueattributes". - + property of a print system object, including casing. For example, the property of a object must be spelled "QueueAttributes", not "Attributes" or "Queueattributes". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintQueueProperty.xml b/xml/System.Printing.IndexedProperties/PrintQueueProperty.xml index 9553b3b6a82..a1331bcf96a 100644 --- a/xml/System.Printing.IndexedProperties/PrintQueueProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintQueueProperty.xml @@ -62,11 +62,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "HostingPrintQueue", not "PrintQueue" or "Hostingprintqueue". - + property of a print system object, including casing. For example, the property of a object must be spelled "HostingPrintQueue", not "PrintQueue" or "Hostingprintqueue". + ]]> @@ -100,11 +100,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "HostingPrintQueue", not "PrintQueue" or "Hostingprintqueue". - + property of a print system object, including casing. For example, the property of a object must be spelled "HostingPrintQueue", not "PrintQueue" or "Hostingprintqueue". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintQueueStatusProperty.xml b/xml/System.Printing.IndexedProperties/PrintQueueStatusProperty.xml index 4fe241330f5..017be2e300e 100644 --- a/xml/System.Printing.IndexedProperties/PrintQueueStatusProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintQueueStatusProperty.xml @@ -62,11 +62,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "QueueStatus", not "Status" or "Queuestatus". - + property of a print system object, including casing. For example, the property of a object must be spelled "QueueStatus", not "Status" or "Queuestatus". + ]]> @@ -100,11 +100,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "QueueStatus", not "Status" or "Queuestatus". - + property of a print system object, including casing. For example, the property of a object must be spelled "QueueStatus", not "Status" or "Queuestatus". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintServerLoggingProperty.xml b/xml/System.Printing.IndexedProperties/PrintServerLoggingProperty.xml index 4c41d8a438f..2a3e76166e2 100644 --- a/xml/System.Printing.IndexedProperties/PrintServerLoggingProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintServerLoggingProperty.xml @@ -62,11 +62,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "EventLog", not "Events" or "Eventlog". - + property of a print system object, including casing. For example, the property of a object must be spelled "EventLog", not "Events" or "Eventlog". + ]]> @@ -100,11 +100,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "EventLog", not "Events" or "Eventlog". - + property of a print system object, including casing. For example, the property of a object must be spelled "EventLog", not "Events" or "Eventlog". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintServerProperty.xml b/xml/System.Printing.IndexedProperties/PrintServerProperty.xml index 4d48dca1406..9435feae8d9 100644 --- a/xml/System.Printing.IndexedProperties/PrintServerProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintServerProperty.xml @@ -62,11 +62,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "HostingPrintServer", not "PrintServer" or "Hostingprintserver". - + property of a print system object, including casing. For example, the property of a object must be spelled "HostingPrintServer", not "PrintServer" or "Hostingprintserver". + ]]> @@ -100,11 +100,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "HostingPrintServer", not "PrintServer" or "Hostingprintserver". - + property of a print system object, including casing. For example, the property of a object must be spelled "HostingPrintServer", not "PrintServer" or "Hostingprintserver". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintStreamProperty.xml b/xml/System.Printing.IndexedProperties/PrintStreamProperty.xml index 529deeebae0..bd4f1161b0e 100644 --- a/xml/System.Printing.IndexedProperties/PrintStreamProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintStreamProperty.xml @@ -69,11 +69,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "JobStream", not "Stream" or "Jobstream". - + property of a print system object, including casing. For example, the property of a object must be spelled "JobStream", not "Stream" or "Jobstream". + ]]> @@ -107,11 +107,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "JobStream", not "Stream" or "Jobstream". - + property of a print system object, including casing. For example, the property of a object must be spelled "JobStream", not "Stream" or "Jobstream". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintStringProperty.xml b/xml/System.Printing.IndexedProperties/PrintStringProperty.xml index 663ea3eac82..f95563545a6 100644 --- a/xml/System.Printing.IndexedProperties/PrintStringProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintStringProperty.xml @@ -31,14 +31,14 @@ Represents a property (and its value) of a printing system hardware or software component. - @@ -79,11 +79,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "Submitter", not "submitter". - + property of a print system object, including casing. For example, the property of a object must be spelled "Submitter", not "submitter". + ]]> @@ -117,19 +117,19 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "Submitter", not "submitter". - - - -## Examples - The following example shows how to use this constructor to install a second printer that differs in its properties from an existing printer only in location, port, and shared status. - + property of a print system object, including casing. For example, the property of a object must be spelled "Submitter", not "submitter". + + + +## Examples + The following example shows how to use this constructor to install a second printer that differs in its properties from an existing printer only in location, port, and shared status. + :::code language="csharp" source="~/snippets/csharp/System.Printing/LocalPrintServer/.ctor/Program.cs" id="Snippetcloneprinter"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/ClonePrinter/visualbasic/program.vb" id="Snippetcloneprinter"::: + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintThreadPriorityProperty.xml b/xml/System.Printing.IndexedProperties/PrintThreadPriorityProperty.xml index e9b8aac14d1..15a61ecc805 100644 --- a/xml/System.Printing.IndexedProperties/PrintThreadPriorityProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintThreadPriorityProperty.xml @@ -62,11 +62,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "PortThreadPriority", not "ThreadPriority" or "Portthreadpriority". - + property of a print system object, including casing. For example, the property of a object must be spelled "PortThreadPriority", not "ThreadPriority" or "Portthreadpriority". + ]]> @@ -100,11 +100,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "PortThreadPriority", not "ThreadPriority" or "Portthreadpriority". - + property of a print system object, including casing. For example, the property of a object must be spelled "PortThreadPriority", not "ThreadPriority" or "Portthreadpriority". + ]]> diff --git a/xml/System.Printing.IndexedProperties/PrintTicketProperty.xml b/xml/System.Printing.IndexedProperties/PrintTicketProperty.xml index 461ac8c0b5b..c2766aaa8cd 100644 --- a/xml/System.Printing.IndexedProperties/PrintTicketProperty.xml +++ b/xml/System.Printing.IndexedProperties/PrintTicketProperty.xml @@ -68,11 +68,11 @@ The name of the property that the represents. Initializes a new instance of the class for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "DefaultPrintTicket", not "DefaultPrintSettings" or "Defaultprintticket". - + property of a print system object, including casing. For example, the property of a object must be spelled "DefaultPrintTicket", not "DefaultPrintSettings" or "Defaultprintticket". + ]]> @@ -112,11 +112,11 @@ The value of the property that the represents. Initializes a new instance of the class that has the specified value for the specified property. - property of a print system object, including casing. For example, the property of a object must be spelled "DefaultPrintTicket", not "DefaultPrintSettings" or "Defaultprintticket". - + property of a print system object, including casing. For example, the property of a object must be spelled "DefaultPrintTicket", not "DefaultPrintSettings" or "Defaultprintticket". + ]]> diff --git a/xml/System.Printing/Collation.xml b/xml/System.Printing/Collation.xml index 83ba09319f6..efcb985d27f 100644 --- a/xml/System.Printing/Collation.xml +++ b/xml/System.Printing/Collation.xml @@ -34,11 +34,11 @@ - As members of the collection, which is a property of , these values indicate the type of output that the printer supports. (Many printers support both types.) -- As the value of the property of a , the value instructs the printer whether to collate. +- As the value of the property of a , the value instructs the printer whether to collate. The **Unknown** value is never used in properties of objects. - You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the collation feature to an unrecognized collation option, then a object in your application that is constructed with that document will have **Unknown** as the value of the property. + You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the collation feature to an unrecognized collation option, then a object in your application that is constructed with that document will have **Unknown** as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/DeviceFontSubstitution.xml b/xml/System.Printing/DeviceFontSubstitution.xml index 8d3de2dba95..cc1daa9a0f8 100644 --- a/xml/System.Printing/DeviceFontSubstitution.xml +++ b/xml/System.Printing/DeviceFontSubstitution.xml @@ -32,11 +32,11 @@ - As members of the collection, a property of , they represent the printer capabilities. -- As the value of the property of a , they instruct the printer to enable or disable device font substitution for the print job. +- As the value of the property of a , they instruct the printer to enable or disable device font substitution for the print job. The Unknown value is never used in properties of objects. - You should never set a property to Unknown. If some other producing application has created a PrintTicket document that sets the device font substitution feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have Unknown as the value of the property. + You should never set a property to Unknown. If some other producing application has created a PrintTicket document that sets the device font substitution feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have Unknown as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information, see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/Duplexing.xml b/xml/System.Printing/Duplexing.xml index 3812f59be52..aecd9014fc1 100644 --- a/xml/System.Printing/Duplexing.xml +++ b/xml/System.Printing/Duplexing.xml @@ -30,11 +30,11 @@ - As members of the collection, which is a property of , these values indicate the kinds of one-sided and two-sided printing that the printer supports. -- As the value of the property of a , they direct the printer to use one-sided printing or some kind of two-sided printing. +- As the value of the property of a , they direct the printer to use one-sided printing or some kind of two-sided printing. The **Unknown** value is never used in properties of objects. - You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the duplexing feature to an unrecognized duplexing option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have **Unknown** as the value of the property. + You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the duplexing feature to an unrecognized duplexing option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have **Unknown** as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/InputBin.xml b/xml/System.Printing/InputBin.xml index c70b5af3c76..edd3d0a8932 100644 --- a/xml/System.Printing/InputBin.xml +++ b/xml/System.Printing/InputBin.xml @@ -30,11 +30,11 @@ - As members of the collection, a property of , they indicate the types of input bins that the printer supports. -- As the value of the property of a , they instruct the printer to use the specified bin. +- As the value of the property of a , they instruct the printer to use the specified bin. The `Unknown` value is never used in properties of objects. - You should never set a property to `Unknown`. If some other producing application has created a document that sets the input bin feature to an unrecognized optio, (that is, an option that is not defined in the [Print Schema](/windows/win32/printdocs/printschema), then a object in your application that is constructed with that document will have `Unknown` as the value of the property. + You should never set a property to `Unknown`. If some other producing application has created a document that sets the input bin feature to an unrecognized optio, (that is, an option that is not defined in the [Print Schema](/windows/win32/printdocs/printschema), then a object in your application that is constructed with that document will have `Unknown` as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information, see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/OutputColor.xml b/xml/System.Printing/OutputColor.xml index 5049cd4a1b7..b0dda55bf8b 100644 --- a/xml/System.Printing/OutputColor.xml +++ b/xml/System.Printing/OutputColor.xml @@ -30,11 +30,11 @@ - As members of the collection, which is a property of , these values specify the types of output that a printer supports. (Many printers support more than one type.) -- As the value of the property of a , they direct the printer to produce the designated type of output. +- As the value of the property of a , they direct the printer to produce the designated type of output. The **Unknown** value is never used in properties of objects. - You should never set a property to `Unknown`. If some other producing application has created a *PrintTicket document* that sets the output color feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have `Unknown` as the value of the property. + You should never set a property to `Unknown`. If some other producing application has created a *PrintTicket document* that sets the output color feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have `Unknown` as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/OutputQuality.xml b/xml/System.Printing/OutputQuality.xml index 6e0ebc0334e..25e7a4db4b4 100644 --- a/xml/System.Printing/OutputQuality.xml +++ b/xml/System.Printing/OutputQuality.xml @@ -30,11 +30,11 @@ - As members of the collection, which is a property of , these values indicate the types of output quality that a printer supports. -- As the value of the property of a , they direct a printer to produce a particular quality. +- As the value of the property of a , they direct a printer to produce a particular quality. The `Unknown` value is never used in properties of objects. - You should never set a property to `Unknown`. If some other producing application has created a *PrintTicket document* that sets the output quality feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have `Unknown` as the value of the property. + You should never set a property to `Unknown`. If some other producing application has created a *PrintTicket document* that sets the output quality feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have `Unknown` as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/PageBorderless.xml b/xml/System.Printing/PageBorderless.xml index d3aba8228dc..48e31f59486 100644 --- a/xml/System.Printing/PageBorderless.xml +++ b/xml/System.Printing/PageBorderless.xml @@ -32,11 +32,11 @@ - As members of the collection, which is a property of , these values indicate whether the device supports borderless printing. -- As the value of the property of a , the value instructs the printer whether to print to the edge of the media. +- As the value of the property of a , the value instructs the printer whether to print to the edge of the media. The **Unknown** value is never used in properties of objects. - You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the page borderless feature to an unrecognized option, then a object in your application that is constructed with that document will have **Unknown** as the value of the property. + You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the page borderless feature to an unrecognized option, then a object in your application that is constructed with that document will have **Unknown** as the value of the property. ]]> diff --git a/xml/System.Printing/PageImageableArea.xml b/xml/System.Printing/PageImageableArea.xml index f8ee3722c5b..73337c57058 100644 --- a/xml/System.Printing/PageImageableArea.xml +++ b/xml/System.Printing/PageImageableArea.xml @@ -24,18 +24,18 @@ Represents the area of a page that can be printed. - and also includes page size, see . - + and also includes page size, see . + > [!CAUTION] -> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. - - If you want to print from a Windows Forms application, see the namespace. - +> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. + + If you want to print from a Windows Forms application, see the namespace. + ]]> @@ -73,11 +73,11 @@ Gets the height of the imageable area. A that represents the height of the imageable area in pixels (1/96 of an inch). - property gets the distance from the upper-left corner of the imageable area (also called the "origin" of the imageable area) to the lower-left corner. - + property gets the distance from the upper-left corner of the imageable area (also called the "origin" of the imageable area) to the lower-left corner. + ]]> @@ -115,11 +115,11 @@ Gets the width of the imageable area. A that represents the width of the imageable area in pixels (1/96 of an inch). - property gets the distance from the upper-left corner of the imageable area (also called the "origin" of the imageable area) to the upper-right corner. - + property gets the distance from the upper-left corner of the imageable area (also called the "origin" of the imageable area) to the upper-right corner. + ]]> @@ -222,13 +222,13 @@ Returns the representation of . A that represents the property values of the . - , ), (, ) - + , ), (, ) + ]]> diff --git a/xml/System.Printing/PageMediaSizeName.xml b/xml/System.Printing/PageMediaSizeName.xml index 26605c6b36a..0a4c3449222 100644 --- a/xml/System.Printing/PageMediaSizeName.xml +++ b/xml/System.Printing/PageMediaSizeName.xml @@ -23,11 +23,11 @@ Specifies the page size or roll width of the paper or other print media. - property. The class, in turn, is used to provide values for the property where it specifies the various page sizes a printer can use, and the property, where it instructs a printer which page size to use. - + property. The class, in turn, is used to provide values for the property where it specifies the various page sizes a printer can use, and the property, where it instructs a printer which page size to use. + ]]> diff --git a/xml/System.Printing/PageMediaType.xml b/xml/System.Printing/PageMediaType.xml index fb8f22e5603..b78e4c87035 100644 --- a/xml/System.Printing/PageMediaType.xml +++ b/xml/System.Printing/PageMediaType.xml @@ -30,11 +30,11 @@ - As members of the collection, a property of , they indicate the types of media that the printer supports. -- As the value of the property of a , they instruct the printer to use a specific type of media. +- As the value of the property of a , they instruct the printer to use a specific type of media. The Unknownvalue is never used in properties of objects. - You should never set a property to Unknown. If some other producing application has created a PrintTicket document that sets the page media type feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have Unknown as the value of the property. + You should never set a property to Unknown. If some other producing application has created a PrintTicket document that sets the page media type feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have Unknown as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information, see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/PageOrder.xml b/xml/System.Printing/PageOrder.xml index 8c64190008d..2a17dafd036 100644 --- a/xml/System.Printing/PageOrder.xml +++ b/xml/System.Printing/PageOrder.xml @@ -30,11 +30,11 @@ - As members of the collection, a property of , these values indicate the type of page order that a printer supports. (Many printers support both types.) -- As the value of the property of a , the value directs a printer to print output in a specified order. +- As the value of the property of a , the value directs a printer to print output in a specified order. The **Unknown** value is never used in properties of objects. - You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the page order feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have **Unknown** as the value of the property. + You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the page order feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have **Unknown** as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/PageOrientation.xml b/xml/System.Printing/PageOrientation.xml index e428b457d63..090d1d111d4 100644 --- a/xml/System.Printing/PageOrientation.xml +++ b/xml/System.Printing/PageOrientation.xml @@ -30,11 +30,11 @@ - As members of the collection, which is a property of , these values indicate the orientation types that a printer supports. -- As the value of the property of a , the value directs the printer to use a particular orientation. +- As the value of the property of a , the value directs the printer to use a particular orientation. The **Unknown** value is never used in properties of objects. - You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the orientation feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have **Unknown** as the value of the property. + You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the orientation feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have **Unknown** as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/PageQualitativeResolution.xml b/xml/System.Printing/PageQualitativeResolution.xml index 0dcad1a0caf..8d9679fc192 100644 --- a/xml/System.Printing/PageQualitativeResolution.xml +++ b/xml/System.Printing/PageQualitativeResolution.xml @@ -23,13 +23,13 @@ Specifies the page resolution as a qualitative, non-numerical, value. - property. The class, in turn, is used to provide values for the property where it specifies the various resolutions that a printer supports, and the property, where it instructs a printer what resolution to use. - + property. The class, in turn, is used to provide values for the property where it specifies the various resolutions that a printer supports, and the property, where it instructs a printer what resolution to use. + ]]> diff --git a/xml/System.Printing/PageScalingFactorRange.xml b/xml/System.Printing/PageScalingFactorRange.xml index 98d14ec9812..e4536a91764 100644 --- a/xml/System.Printing/PageScalingFactorRange.xml +++ b/xml/System.Printing/PageScalingFactorRange.xml @@ -24,16 +24,16 @@ Specifies a range of percentages by which a printer can enlarge or reduce the print image on a page. - property of a object. - + property of a object. + > [!CAUTION] -> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. - - If you want to print from a Windows Forms application, see the namespace. - +> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. + + If you want to print from a Windows Forms application, see the namespace. + ]]> @@ -136,13 +136,13 @@ Returns the representation of the range. A representation of the scaling range. - , ) - + , ) + ]]> diff --git a/xml/System.Printing/PagesPerSheetDirection.xml b/xml/System.Printing/PagesPerSheetDirection.xml index 4e43c16fba6..79604b9570a 100644 --- a/xml/System.Printing/PagesPerSheetDirection.xml +++ b/xml/System.Printing/PagesPerSheetDirection.xml @@ -30,11 +30,11 @@ - As members of the collection, which is a property of , these values indicate the page arrangements that the printer supports. -- As the value of the property of a , the value directs the printer to arrange pages of content in a specified direction. +- As the value of the property of a , the value directs the printer to arrange pages of content in a specified direction. The **Unknown** value is never used in properties of objects. - You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the pages-per-sheet-direction feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have **Unknown** as the value of the property. + You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the pages-per-sheet-direction feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have **Unknown** as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/PhotoPrintingIntent.xml b/xml/System.Printing/PhotoPrintingIntent.xml index d61fc09571b..4e8e2be6e1a 100644 --- a/xml/System.Printing/PhotoPrintingIntent.xml +++ b/xml/System.Printing/PhotoPrintingIntent.xml @@ -34,7 +34,7 @@ The `Unknown` value is never used in properties of objects. - You should never set a property to `Unknown`. If some other producing application has created a PrintTicket document that sets the photo printing intent feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](/windows/win32/printdocs/printschema), then a object in your application that is constructed with that document will have `Unknown` as the value of the property. + You should never set a property to `Unknown`. If some other producing application has created a PrintTicket document that sets the photo printing intent feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](/windows/win32/printdocs/printschema), then a object in your application that is constructed with that document will have `Unknown` as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information, see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/PrintCapabilities.xml b/xml/System.Printing/PrintCapabilities.xml index 15d9b4408eb..2ae2fa7d220 100644 --- a/xml/System.Printing/PrintCapabilities.xml +++ b/xml/System.Printing/PrintCapabilities.xml @@ -27,7 +27,7 @@ object is an easy-to-work-with representation of a certain type of XML document called a *PrintCapabilities document*. The latter is a snapshot of all of a printer's capabilities and their current settings. For example, if the printer supports color printing, then the document would have a `` element that sets out how color output will be handled. The element is, in turn, represented by the property of the object. If the printer does not support color, then there is no `` element in the document and the value of the property is `null`. The PrintCapabilities document must conform to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). + A object is an easy-to-work-with representation of a certain type of XML document called a *PrintCapabilities document*. The latter is a snapshot of all of a printer's capabilities and their current settings. For example, if the printer supports color printing, then the document would have a `` element that sets out how color output will be handled. The element is, in turn, represented by the property of the object. If the printer does not support color, then there is no `` element in the document and the value of the property is `null`. The PrintCapabilities document must conform to the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397). The class enables your application to obtain a printer's capabilities without having to engage in any direct reading of XML objects. @@ -793,13 +793,13 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) property generally represents the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageScaling` keyword. But there are some complexities as follows. + This property generally represents the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)'s `PageScaling` keyword. But there are some complexities as follows. -- If the PrintCapabilities document does not have a `PageScaling` element, or it has one, but neither its **CustomSquare** nor **Custom** options are defined; then the property is null. +- If the PrintCapabilities document does not have a `PageScaling` element, or it has one, but neither its **CustomSquare** nor **Custom** options are defined; then the property is null. - In all other cases, the property's behavior is as follows. - The property of the property's object is the smallest of the following values. + The property of the property's object is the smallest of the following values. - The **MinValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option's **ScaleWidth** `ScoredProperty`. @@ -807,7 +807,7 @@ foreach (PageResolution pageRes in pc.PageResolutionCapability) - The **MinValue** property of the `PageScalingScale` datatype that provides the value of the **CustomSquare** option's **Scale** `ScoredProperty`. - The property of the property's object is the largest of the following values. + The property of the property's object is the largest of the following values. - The **MaxValue** property of the `PageScalingScaleWidth` datatype that provides the value of the **Custom** option's **ScaleWidth** `ScoredProperty`. diff --git a/xml/System.Printing/PrintDocumentImageableArea.xml b/xml/System.Printing/PrintDocumentImageableArea.xml index ef514fa3d74..bb025181f8a 100644 --- a/xml/System.Printing/PrintDocumentImageableArea.xml +++ b/xml/System.Printing/PrintDocumentImageableArea.xml @@ -24,18 +24,18 @@ Specifies the size of the paper (or other media), the size of the imageable area, and the location of the imageable area. - objects primarily as parameters to the methods. - + objects primarily as parameters to the methods. + > [!CAUTION] -> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. - - If you want to print from a Windows Forms application, see the namespace. - +> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. + + If you want to print from a Windows Forms application, see the namespace. + ]]> @@ -67,11 +67,11 @@ Gets the height of the imageable area. A that represents the distance from the origin. - property gets the distance from the upper-left corner of the imageable area (also called the 'origin' of the imageable area) to the lower-left corner of the imageable area. - + property gets the distance from the upper-left corner of the imageable area (also called the 'origin' of the imageable area) to the lower-left corner of the imageable area. + ]]> @@ -103,11 +103,11 @@ Gets the width of the imageable area. A that represents the distance from the origin. - property gets the distance from the upper-left corner of the imageable area (also called the 'origin' of the imageable area) to the upper-right corner of the imageable area. - + property gets the distance from the upper-left corner of the imageable area (also called the 'origin' of the imageable area) to the upper-right corner of the imageable area. + ]]> diff --git a/xml/System.Printing/PrintJobSettings.xml b/xml/System.Printing/PrintJobSettings.xml index 05c2a6bcada..57e526de0a1 100644 --- a/xml/System.Printing/PrintJobSettings.xml +++ b/xml/System.Printing/PrintJobSettings.xml @@ -24,16 +24,16 @@ Describes a print job. - object, which is the value of the property, holds all the detailed settings for a print job. The parent, , adds only a description. - + object, which is the value of the property, holds all the detailed settings for a print job. The parent, , adds only a description. + > [!CAUTION] -> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. - - If you want to print from a Windows Forms application, see the namespace. - +> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. + + If you want to print from a Windows Forms application, see the namespace. + ]]> @@ -75,11 +75,11 @@ Gets or sets a object that holds all the detailed settings for the print job. A object that holds all the details about the print job, such as the number of copies to print, and whether stapling or duplex printing is used. - property does not validate or modify the specified for a particular . If needed, use the method to create a -specific that is valid for a given printer. - + property does not validate or modify the specified for a particular . If needed, use the method to create a -specific that is valid for a given printer. + ]]> diff --git a/xml/System.Printing/PrintJobStatus.xml b/xml/System.Printing/PrintJobStatus.xml index 65309ce31ad..e70c73488e7 100644 --- a/xml/System.Printing/PrintJobStatus.xml +++ b/xml/System.Printing/PrintJobStatus.xml @@ -30,20 +30,20 @@ Specifies the current status of a print job in a print queue. - property. - - - -## Examples - The following example shows how to use this enumeration when diagnosing a problem with a print job. - + property. + + + +## Examples + The following example shows how to use this enumeration when diagnosing a problem with a print job. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CPP/Program.cpp" id="Snippetspottroubleusingjobattributes"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintJobStatus/Overview/Program.cs" id="Snippetspottroubleusingjobattributes"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobattributes"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobattributes"::: + ]]> diff --git a/xml/System.Printing/PrintPort.xml b/xml/System.Printing/PrintPort.xml index f6f0d40f3a8..d0874caf991 100644 --- a/xml/System.Printing/PrintPort.xml +++ b/xml/System.Printing/PrintPort.xml @@ -25,16 +25,16 @@ Represents a printer port on a print server. Each print queue has a print port assigned to it. - property holds the object that is assigned to the queue. - + property holds the object that is assigned to the queue. + > [!CAUTION] -> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. - - If you want to print from a Windows Forms application, see the namespace. - +> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. + + If you want to print from a Windows Forms application, see the namespace. + ]]> diff --git a/xml/System.Printing/PrintQueue.xml b/xml/System.Printing/PrintQueue.xml index 177f28c5ac7..7995246bdd6 100644 --- a/xml/System.Printing/PrintQueue.xml +++ b/xml/System.Printing/PrintQueue.xml @@ -486,7 +486,7 @@ ## Remarks Use this method to write device specific information, to a spool file, that is not automatically included by the Microsoft Windows spooler. Of course, you need to know whether the spool file is Enhanced Metafile (EMF) or XML Paper Specification (XPS). If you prefer to work with the API, you can use the class instead of this method. - After the method has been called, you must write a array to the property of the that is returned by or no print job is created. This array is what prints if the printer is working and is not paused. + After the method has been called, you must write a array to the property of the that is returned by or no print job is created. This array is what prints if the printer is working and is not paused. > [!CAUTION] > If the is not closed with before the end of the thread in which is called, then an is thrown when that thread ends because the spooler thread cannot gain control over the object. @@ -549,7 +549,7 @@ ## Remarks Use this method to write device specific information, to a spool file, that is not automatically included by the Microsoft Windows spooler. Of course, you need to know whether the spool file is Enhanced Metafile (EMF) or XML Paper Specification (XPS). If you prefer to work with the API, you can use the class instead of this method. - After the method has been called, you must write a array to the property of the that is returned by or no print job is created. This array is what prints if the printer is working and is not paused. + After the method has been called, you must write a array to the property of the that is returned by or no print job is created. This array is what prints if the printer is working and is not paused. > [!CAUTION] > If the is not closed with before the end of the thread in which is called, then an is thrown when that thread ends because the spooler thread cannot gain control over the object. @@ -837,7 +837,7 @@ property enables you to store information that users cannot view unless your application makes it visible.) + The comment is visible to users in the Windows printer list and on the Windows common print dialog. It can provide information not contained in the printer's name, model, or location properties, which are also visible in the same places; for example, "Reserved for Payroll Dept. between 3 pm and 4 pm." (The property enables you to store information that users cannot view unless your application makes it visible.) ]]> @@ -1309,9 +1309,9 @@ Each maintains its own . - In normal operation the property returns a . If the detects an invalid state, returns `null`. If returns `null`, the application should display an informational user dialog that an error has occurred on this print queue and that the print job should be restarted with the output directed to a different print queue. + In normal operation the property returns a . If the detects an invalid state, returns `null`. If returns `null`, the application should display an informational user dialog that an error has occurred on this print queue and that the print job should be restarted with the output directed to a different print queue. - Getting or setting the property does not validate the . The method can be used to validate a . + Getting or setting the property does not validate the . The method can be used to validate a . @@ -1394,7 +1394,7 @@ property with the property which is visible to users in the common print dialog and the Printers and Faxes list. + When the queue is created, the description defaults to a three part string that consists of the queue name, model, and location separated by commas. Contrast the property with the property which is visible to users in the common print dialog and the Printers and Faxes list. ]]> @@ -1922,7 +1922,7 @@ property is `true`, your program cannot create a object that represents this printer unless the user has full printing permissions for the printer. + When the property is `true`, your program cannot create a object that represents this printer unless the user has full printing permissions for the printer. ]]> @@ -2028,7 +2028,7 @@ property. + Busy does not necessarily mean that it is processing a print job. If the device is a combination printer/fax/copier, then it might be faxing or copying. Compare with the property. If the device does not support a signal with this meaning, then the property is always `false`. @@ -3021,7 +3021,7 @@ ## Remarks If the printer does not support a signal with this meaning, then the property is always `false`. - The object also has a property. + The object also has a property. @@ -3328,7 +3328,7 @@ The two tickets are then merged. If they have different values for a particular property then the resulting merged ticket initially uses the value of the delta ticket. - The merged ticket is then checked against the actual capabilities of the printer. If any settings in the ticket are incompatible with the printer's capabilities, then the printer driver changes those settings by using whatever logic it wants. Typically, it substitutes the user's or printer's default value for the setting. It the driver's source of substitute values is not the same ticket as `basePrintTicket`, then the merged ticket might have some settings that are different from both of the input tickets. If the printer driver has to change any settings then this fact is reported in the property of the . + The merged ticket is then checked against the actual capabilities of the printer. If any settings in the ticket are incompatible with the printer's capabilities, then the printer driver changes those settings by using whatever logic it wants. Typically, it substitutes the user's or printer's default value for the setting. It the driver's source of substitute values is not the same ticket as `basePrintTicket`, then the merged ticket might have some settings that are different from both of the input tickets. If the printer driver has to change any settings then this fact is reported in the property of the . To merge and validate based on a print queue's default settings, you should set `basePrintTicket` to the or the . @@ -3399,7 +3399,7 @@ The two tickets are then merged. If they have different values for a particular property then the resulting merged ticket initially uses the value of the delta ticket. - The merged ticket is then checked against the actual capabilities of the printer. If any settings in the ticket are incompatible with the printer's capabilities, then the printer driver changes those settings by using whatever logic it wants. Typically, it substitutes the user's or printer's default value for the setting. It the driver's source of substitute values is not the same ticket as `basePrintTicket`, then the merged ticket might have some settings that are different from both of the input tickets. If the printer driver has to change any settings then this fact is reported in the property of the . + The merged ticket is then checked against the actual capabilities of the printer. If any settings in the ticket are incompatible with the printer's capabilities, then the printer driver changes those settings by using whatever logic it wants. Typically, it substitutes the user's or printer's default value for the setting. It the driver's source of substitute values is not the same ticket as `basePrintTicket`, then the merged ticket might have some settings that are different from both of the input tickets. If the printer driver has to change any settings then this fact is reported in the property of the . To merge and validate based on a print queue's default settings, you should set `basePrintTicket` to the or the . @@ -3449,7 +3449,7 @@ object also has a read only property and a writeable property. + The object also has a read only property and a writeable property. For queues on the local print server, and are the same. @@ -3669,7 +3669,7 @@ property which is about the relative priority of print jobs in the queue. + Contrast this property with the property which is about the relative priority of print jobs in the queue. ]]> @@ -4046,7 +4046,7 @@ object also has a read only property and a writeable property. For queues on the local print server, these properties have the same value. + The object also has a read only property and a writeable property. For queues on the local print server, these properties have the same value. ]]> diff --git a/xml/System.Printing/PrintQueueStatus.xml b/xml/System.Printing/PrintQueueStatus.xml index 062b2f05c9a..828a34b30b2 100644 --- a/xml/System.Printing/PrintQueueStatus.xml +++ b/xml/System.Printing/PrintQueueStatus.xml @@ -30,22 +30,22 @@ Specifies the status of a print queue or its printer. - class, this enumeration handles the print queue and the physical printer (or device) as one unit. Some values represent the status of the physical device and others represent the status of the print queue program that is running on the print server. - - Use this enumeration to provide values for the property of the class. - - - -## Examples - The following example shows how to use this enumeration as part of a survey all printers for possible error status. - + class, this enumeration handles the print queue and the physical printer (or device) as one unit. Some values represent the status of the physical device and others represent the status of the print queue program that is running on the print server. + + Use this enumeration to provide values for the property of the class. + + + +## Examples + The following example shows how to use this enumeration as part of a survey all printers for possible error status. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/PrinterStatusSurvey/CPP/Program.cpp" id="Snippetspottroubleusingqueueattributes"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintQueue/HasPaperProblem/Program.cs" id="Snippetspottroubleusingqueueattributes"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrinterStatusSurvey/visualbasic/program.vb" id="Snippetspottroubleusingqueueattributes"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/PrinterStatusSurvey/visualbasic/program.vb" id="Snippetspottroubleusingqueueattributes"::: + ]]> diff --git a/xml/System.Printing/PrintQueueStream.xml b/xml/System.Printing/PrintQueueStream.xml index bd9ce165a3d..899030e1897 100644 --- a/xml/System.Printing/PrintQueueStream.xml +++ b/xml/System.Printing/PrintQueueStream.xml @@ -27,7 +27,7 @@ array, you can also use two of the overloads of the method and the property to write to the spool file. + Use this class to write device specific information to a spool file that is not automatically included by the Microsoft Windows spooler. Of course, you need to know whether the spool file is Enhanced Metafile (EMF) or XML Paper Specification (XPS). If you prefer working with a array, you can also use two of the overloads of the method and the property to write to the spool file. > [!CAUTION] > Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. @@ -793,7 +793,7 @@ ## Remarks A stream must support both writing and seeking for to work. - Use the property to determine whether the current instance supports writing, and use the property to determine whether seeking is supported. + Use the property to determine whether the current instance supports writing, and use the property to determine whether seeking is supported. ]]> diff --git a/xml/System.Printing/PrintServerEventLoggingTypes.xml b/xml/System.Printing/PrintServerEventLoggingTypes.xml index cd73ee476a2..09daa400f40 100644 --- a/xml/System.Printing/PrintServerEventLoggingTypes.xml +++ b/xml/System.Printing/PrintServerEventLoggingTypes.xml @@ -30,11 +30,11 @@ Specifies the types of events that can be logged by a . - property of the . - + property of the . + ]]> diff --git a/xml/System.Printing/PrintSystemJobInfo.xml b/xml/System.Printing/PrintSystemJobInfo.xml index de44efdd939..001b34f396d 100644 --- a/xml/System.Printing/PrintSystemJobInfo.xml +++ b/xml/System.Printing/PrintSystemJobInfo.xml @@ -25,22 +25,22 @@ Defines a print job in detail. - object, use the static method or one of the following instance methods: , , or . - - Many print job properties, such as whether a job is completed, must be passed from the printer to the object before your application reads the corresponding property (). The method provides this functionality. - - Similarly, when your application changes the value of the property, the change must be written to the print queue utility on the computer. The method provides this functionality. - - If you derive a class from that has additional writable properties, then you must implement an override of the and methods. - + object, use the static method or one of the following instance methods: , , or . + + Many print job properties, such as whether a job is completed, must be passed from the printer to the object before your application reads the corresponding property (). The method provides this functionality. + + Similarly, when your application changes the value of the property, the change must be written to the print queue utility on the computer. The method provides this functionality. + + If you derive a class from that has additional writable properties, then you must implement an override of the and methods. + > [!CAUTION] -> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. - - If you want to print from a Windows Forms application, see the namespace. - +> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. + + If you want to print from a Windows Forms application, see the namespace. + ]]> @@ -72,15 +72,15 @@ Cancels the print job. - @@ -112,11 +112,11 @@ Writes any changes to the properties of the object to the actual print job that the object represents. - property is writable. If you derive a class from that has additional writable properties, you must override the and methods with implementations of your own. - + property is writable. If you derive a class from that has additional writable properties, you must override the and methods with implementations of your own. + ]]> @@ -155,11 +155,11 @@ Gets the for the specified job in the specified . The that corresponds to the . - method for the same purpose. - + method for the same purpose. + ]]> @@ -192,15 +192,15 @@ Gets the print queue that is hosting the print job. A value that represents the print queue that owns the print job. - @@ -301,15 +301,15 @@ if the print job is blocked; otherwise, . - @@ -342,15 +342,15 @@ if the print job is finished; otherwise, . - @@ -383,20 +383,20 @@ if the print job was deleted; otherwise . - object only *represents* a real print job. Deleting the latter from its print queue does not automatically dispose of the object in your application. Similarly, the object is not removed from any that was created before the print job it represents was deleted. For example, if the method is run before the print job was deleted, the returned collection will include a object that represents the print job. This object is not removed from the collection when the print job is deleted. But if is then run again, the returned collection will have no members that represent the deleted print jobs. - - - -## Examples - The following example shows how to use this property when diagnosing a problem with a print job. - + object only *represents* a real print job. Deleting the latter from its print queue does not automatically dispose of the object in your application. Similarly, the object is not removed from any that was created before the print job it represents was deleted. For example, if the method is run before the print job was deleted, the returned collection will include a object that represents the print job. This object is not removed from the collection when the print job is deleted. But if is then run again, the returned collection will have no members that represent the deleted print jobs. + + + +## Examples + The following example shows how to use this property when diagnosing a problem with a print job. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CPP/Program.cpp" id="Snippetspottroubleusingjobproperties"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintJobStatus/Overview/Program.cs" id="Snippetspottroubleusingjobproperties"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobproperties"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobproperties"::: + ]]> @@ -429,15 +429,15 @@ if the print job is being deleted; otherwise . - @@ -470,15 +470,15 @@ if an error condition is associated with the print job; otherwise . - @@ -511,20 +511,20 @@ if the printer is offline; otherwise . - objects from the property of the hosting . - - - -## Examples - The following example shows how to use this property when diagnosing a problem with a print job. - + objects from the property of the hosting . + + + +## Examples + The following example shows how to use this property when diagnosing a problem with a print job. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CPP/Program.cpp" id="Snippetspottroubleusingjobproperties"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintJobStatus/Overview/Program.cs" id="Snippetspottroubleusingjobproperties"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobproperties"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobproperties"::: + ]]> @@ -557,15 +557,15 @@ if the printer has run out of the required paper; otherwise, . - @@ -598,20 +598,20 @@ if the print job is paused; otherwise . - can be `false` even when the value of the property is `true`. - - - -## Examples - The following example shows how to use this property when diagnosing a problem with a print job. - + can be `false` even when the value of the property is `true`. + + + +## Examples + The following example shows how to use this property when diagnosing a problem with a print job. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CPP/Program.cpp" id="Snippetspottroubleusingjobproperties"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintJobStatus/Overview/Program.cs" id="Snippetspottroubleusingjobproperties"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobproperties"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobproperties"::: + ]]> @@ -646,15 +646,15 @@ if the print job has printed; otherwise . - @@ -687,15 +687,15 @@ if the printer is printing; otherwise . - @@ -728,11 +728,11 @@ if the printer is printing; otherwise . - method, which resumes a job at the point it was paused. - + method, which resumes a job at the point it was paused. + ]]> @@ -768,11 +768,11 @@ if the print job was saved; otherwise . - property of the object is set to `true` and if the properties of the queue have been committed with the method of the . - + property of the object is set to `true` and if the properties of the queue have been committed with the method of the . + ]]> @@ -805,15 +805,15 @@ if the print job is being spooled; otherwise . - @@ -846,20 +846,20 @@ if user intervention is needed; otherwise . - objects from the property of the hosting . - - - -## Examples - The following example shows how to use this property when diagnosing a problem with a print job. - + objects from the property of the hosting . + + + +## Examples + The following example shows how to use this property when diagnosing a problem with a print job. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CPP/Program.cpp" id="Snippetspottroubleusingjobproperties"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintJobStatus/Overview/Program.cs" id="Snippetspottroubleusingjobproperties"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobproperties"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobproperties"::: + ]]> @@ -891,24 +891,24 @@ Gets the identification number for the print job. An that identifies the print job. - @@ -940,15 +940,15 @@ Gets or sets a name for the print job. A name for the print job. - @@ -1009,20 +1009,20 @@ Gets the current status of the print job. A value. - and . - - - -## Examples - The following example shows how to use this property when diagnosing a problem with a print job. - + and . + + + +## Examples + The following example shows how to use this property when diagnosing a problem with a print job. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CPP/Program.cpp" id="Snippetspottroubleusingjobattributes"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintJobStatus/Overview/Program.cs" id="Snippetspottroubleusingjobattributes"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobattributes"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetspottroubleusingjobattributes"::: + ]]> @@ -1054,11 +1054,11 @@ Gets a reference to the of the print job. A that contains the print job. - @@ -1090,22 +1090,22 @@ Gets the number of pages in the print job. An that states the number of pages in the print job. - @@ -1168,13 +1168,13 @@ Halts printing of the job until runs. - also has and methods. If the print queue is paused, resuming an individual job does not cause that job to resume printing. - + also has and methods. If the print queue is paused, resuming an individual job does not cause that job to resume printing. + ]]> @@ -1266,13 +1266,13 @@ Updates the properties of the object so that their values match the values of the actual print job that the object represents. - object must be written to the actual print job by using the method. Any changes that you have not committed are lost when the method runs. - - If you derive a class from that has additional properties, then you must override the method with an implementation of your own. - + object must be written to the actual print job by using the method. Any changes that you have not committed are lost when the method runs. + + If you derive a class from that has additional properties, then you must override the method with an implementation of your own. + ]]> @@ -1305,11 +1305,11 @@ Restarts a print job from the beginning. - method, which restarts a paused print job, starting at the point it was paused. - + method, which restarts a paused print job, starting at the point it was paused. + ]]> @@ -1341,20 +1341,20 @@ Resumes the printing of a paused print job. - also has and methods. If the print queue is paused, resuming an individual job does not resume the printing of the print job. - - - -## Examples - The following example shows how to use this method to resume a paused print job. - + also has and methods. If the print queue is paused, resuming an individual job does not resume the printing of the print job. + + + +## Examples + The following example shows how to use this method to resume a paused print job. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CPP/Program.cpp" id="Snippethandlepausedjob"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintJobStatus/Overview/Program.cs" id="Snippethandlepausedjob"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippethandlepausedjob"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippethandlepausedjob"::: + ]]> @@ -1388,30 +1388,30 @@ Gets the earliest time of day, expressed as the number of minutes after midnight Coordinated Universal Time (UTC) (also called Greenwich Mean Time [GMT]), that the print job can begin printing. An specifying the earliest possible start time for the print job, expressed as the number of minutes after midnight (UTC). The maximum value is 1439. - object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is earlier than is changed to the value of . - - After the job is added to the queue, it can be given a new value through the Microsoft Windows user interface (UI), provided that it is not earlier than . - - If you are not in the UTC time zone, you must add or subtract multiples of 60 to get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. If returns 960, that means 16:00 (4:00 PM) in UTC (because 960/60 = 16). To convert this to Pacific Time, you must subtract 480 (= 8 * 60) minutes. - - You also must remember that time rolls over to zero after 24 hours (that is; after the 1439th minute). If returns 120, that means 2:00 AM in UTC. To convert this to Pacific Time, you must subtract 480 minutes, which results in -360. To get a positive value that has meaning, add the negative number to the total minutes in a day, 1440, resulting in a final value of 1080 (6:00 PM) Pacific Time. - - See , , and for methods that help make time-zone adjustments. - - If the printer is always available, then this property returns 0 in all time zones. - - - -## Examples - The following example shows how to use this property as part of the process of diagnosing a problematic print job. - + object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is earlier than is changed to the value of . + + After the job is added to the queue, it can be given a new value through the Microsoft Windows user interface (UI), provided that it is not earlier than . + + If you are not in the UTC time zone, you must add or subtract multiples of 60 to get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. If returns 960, that means 16:00 (4:00 PM) in UTC (because 960/60 = 16). To convert this to Pacific Time, you must subtract 480 (= 8 * 60) minutes. + + You also must remember that time rolls over to zero after 24 hours (that is; after the 1439th minute). If returns 120, that means 2:00 AM in UTC. To convert this to Pacific Time, you must subtract 480 minutes, which results in -360. To get a positive value that has meaning, add the negative number to the total minutes in a day, 1440, resulting in a final value of 1080 (6:00 PM) Pacific Time. + + See , , and for methods that help make time-zone adjustments. + + If the printer is always available, then this property returns 0 in all time zones. + + + +## Examples + The following example shows how to use this property as part of the process of diagnosing a problematic print job. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CPP/Program.cpp" id="Snippetusingjobstartanduntiltimes"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintJobStatus/Overview/Program.cs" id="Snippetusingjobstartanduntiltimes"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetusingjobstartanduntiltimes"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetusingjobstartanduntiltimes"::: + ]]> @@ -1449,15 +1449,15 @@ Gets the name of the user who submitted the print job. A that identifies the user who submitted the print job. - @@ -1547,30 +1547,30 @@ Gets the last time of day, expressed as the number of minutes after midnight Coordinated Universal Time (UTC) (also called Greenwich Mean Time [GMT]), that the print job can begin printing. An that specifies the last time that the job can print, expressed as the number of minutes after midnight (UTC). The maximum value is 1439. - object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is later than is changed to the value of . - - After the job is added to the queue, it can be given a new value through the Microsoft Windows user interface (UI), provided that it is not later than . - - If you are not in the UTC time zone, you must add or subtract multiples of 60 to get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. If returns 960, that means 16:00 (4:00 PM) in UTC (because 960/60 = 16). To convert this to Pacific Time, you must subtract 480 (= 8 * 60) minutes. - - You also must remember that time rolls over to zero after 24 hours (that is; after the 1439th minute). If returns 120, that means 2:00 AM in UTC. To convert this to Pacific Time, you must subtract 480 minutes, which results in -360. To get a positive value that has meaning, add the negative number to the total minutes in a day, 1440, resulting in a final value of 1080 (6:00 PM) Pacific Time. - - See , , and for methods that help make time-zone adjustments. - - If the printer is always available, then this property returns 0 in all time zones. - - - -## Examples - The following example shows how to use this property as part of the process of diagnosing a problematic print job. - + object from the property of the hosting at the time the job enters the queue. If is changed, then any value that is later than is changed to the value of . + + After the job is added to the queue, it can be given a new value through the Microsoft Windows user interface (UI), provided that it is not later than . + + If you are not in the UTC time zone, you must add or subtract multiples of 60 to get the correct time for your time zone. For example, if you are in the Pacific Time Zone of North America and daylight savings time is not in effect, then your local time is 8 hours earlier than UTC. If returns 960, that means 16:00 (4:00 PM) in UTC (because 960/60 = 16). To convert this to Pacific Time, you must subtract 480 (= 8 * 60) minutes. + + You also must remember that time rolls over to zero after 24 hours (that is; after the 1439th minute). If returns 120, that means 2:00 AM in UTC. To convert this to Pacific Time, you must subtract 480 minutes, which results in -360. To get a positive value that has meaning, add the negative number to the total minutes in a day, 1440, resulting in a final value of 1080 (6:00 PM) Pacific Time. + + See , , and for methods that help make time-zone adjustments. + + If the printer is always available, then this property returns 0 in all time zones. + + + +## Examples + The following example shows how to use this property as part of the process of diagnosing a problematic print job. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/CPP/Program.cpp" id="Snippetusingjobstartanduntiltimes"::: :::code language="csharp" source="~/snippets/csharp/System.Printing/PrintJobStatus/Overview/Program.cs" id="Snippetusingjobstartanduntiltimes"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetusingjobstartanduntiltimes"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Wpf/DiagnoseProblematicPrintJob/visualbasic/program.vb" id="Snippetusingjobstartanduntiltimes"::: + ]]> diff --git a/xml/System.Printing/PrintTicket.xml b/xml/System.Printing/PrintTicket.xml index bcebfa889c0..2fad15f9453 100644 --- a/xml/System.Printing/PrintTicket.xml +++ b/xml/System.Printing/PrintTicket.xml @@ -31,7 +31,7 @@ object is an easy-to-work-with representation of a certain type of XML document called a *PrintTicket document*. The latter is a set of instructions telling a printer how to set its various features (such as duplexing, collating, and stapling). For example, to instruct the printer to turn on its stapler and staple print jobs in the upper left corner, the document would have a `` element that specifies **StapleTopLeft**. The element is, in turn, represented by the property of the object. The PrintTicket document must conform to the [Print Schema](/windows/win32/printdocs/printschema). + A object is an easy-to-work-with representation of a certain type of XML document called a *PrintTicket document*. The latter is a set of instructions telling a printer how to set its various features (such as duplexing, collating, and stapling). For example, to instruct the printer to turn on its stapler and staple print jobs in the upper left corner, the document would have a `` element that specifies **StapleTopLeft**. The element is, in turn, represented by the property of the object. The PrintTicket document must conform to the [Print Schema](/windows/win32/printdocs/printschema). The class enables your application to configure the printer's features without having to engage in any direct writing of XML objects. @@ -214,7 +214,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `DocumentCollate` keyword, not the `JobCollateAllDocuments` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. @@ -264,7 +264,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobCopiesAllDocuments` keyword, not the `DocumentCopiesAllPages` keyword, or the `PageCopies` keyword. - You can test for the printer's maximum by using the property. + You can test for the printer's maximum by using the property. ]]> @@ -305,7 +305,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageDeviceFontSubstitution` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> @@ -346,7 +346,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobDuplexAllDocumentsContiguously` keyword, not the `DocumentDuplex` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. @@ -443,7 +443,7 @@ When this property is set to any value, then matching `JobInputBin` markup will be added to the XML print ticket and any `DocumentInputBin` and `PageInputBin` markup that is already there will be removed. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> @@ -484,7 +484,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageOutputColor` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. @@ -533,7 +533,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageOutputQuality` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> @@ -574,7 +574,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageBorderless` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> @@ -613,7 +613,7 @@ ## Remarks This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageMediaSize` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. @@ -670,7 +670,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageMediaType` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> @@ -711,7 +711,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobPageOrder` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> @@ -752,7 +752,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageOrientation` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. @@ -801,7 +801,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageResolution` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> @@ -851,9 +851,9 @@ A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. - This property generally represents the **Scale** `ScoredProperty` of the [Print Schema](/windows/win32/printdocs/printschema)'s `PageScaling` keyword. But there are some complexities as follows. + This property generally represents the **Scale** `ScoredProperty` of the [Print Schema](/windows/win32/printdocs/printschema)'s `PageScaling` keyword. But there are some complexities as follows. - When reading the property, the property behaves as follows. + When reading the property, the property behaves as follows. - If the PrintTicket XML document has the `PageScaling` feature set to the **CustomSquare** option, and the **CustomSquare** option's **Scale** value is positive value, then that is the value that is returned. @@ -861,7 +861,7 @@ - In all other cases, `null` is returned. - When setting the property, the property behaves as follows. + When setting the property, the property behaves as follows. - If it's set to `null`, then the `PageScaling` markup is removed from the PrintTicket XML document. @@ -902,13 +902,13 @@ property. + Most printers support only a limited range of specific possibilities, such as 1, 2, 4, 6, 8, and 16 pages per side. You can test for the options that the printer supports by using the property. A `null` value for this property means that this feature setting is not specified. Also, when the value is `null`, the XML versions of the (see and ) will not contain any markup for this feature. This property corresponds to the **PagesPerSheet**`ScoredProperty` of the [Print Schema](/windows/win32/printdocs/printschema)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> @@ -951,7 +951,7 @@ This property corresponds to the **PresentationDirection** subfeature of the [Print Schema](/windows/win32/printdocs/printschema)'s `JobNUpAllDocumentsContiguously` keyword, not the `DocumentNUp` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> @@ -994,7 +994,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PagePhotoPrintingIntent` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> @@ -1113,7 +1113,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `JobStapleAllDocuments` keyword, not the `DocumentStaple` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. @@ -1163,7 +1163,7 @@ This property corresponds to the [Print Schema](/windows/win32/printdocs/printschema)'s `PageTrueTypeFontMode` keyword. - You can test for the options that the printer supports by using the property. + You can test for the options that the printer supports by using the property. ]]> diff --git a/xml/System.Printing/PrintingNotSupportedException.xml b/xml/System.Printing/PrintingNotSupportedException.xml index eb58e5939f5..2df694db91c 100644 --- a/xml/System.Printing/PrintingNotSupportedException.xml +++ b/xml/System.Printing/PrintingNotSupportedException.xml @@ -31,15 +31,15 @@ The exception that is thrown when a printing operation is not supported. - [!CAUTION] -> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. - - If you want to print from a Windows Forms application, see the namespace. - +> Classes within the namespace are not supported for use within a Windows service or ASP.NET application or service. Attempting to use these classes from within one of these application types may produce unexpected problems, such as diminished service performance and run-time exceptions. + + If you want to print from a Windows Forms application, see the namespace. + ]]> @@ -82,18 +82,18 @@ Initializes a new instance of the class with a system-supplied message that describes the error. - property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> Handling and Throwing Exceptions @@ -126,16 +126,16 @@ The message that describes the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. Initializes a new instance of the class with a specified message that describes the error. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -176,11 +176,11 @@ The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization @@ -215,18 +215,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 the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string specified in `message`.| - + 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| +|--------------|-----------| +||`null`.| +||The error message string specified in `message`.| + ]]> Handling and Throwing Exceptions @@ -270,11 +270,11 @@ The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - XML and SOAP Serialization diff --git a/xml/System.Printing/Stapling.xml b/xml/System.Printing/Stapling.xml index 4d8f6e297eb..e69c528e95b 100644 --- a/xml/System.Printing/Stapling.xml +++ b/xml/System.Printing/Stapling.xml @@ -30,11 +30,11 @@ - As members of the collection, which is a property of , these values indicate the types of stapling that a printer supports. -- As the value of the property of a , the value instructs the printer whether, and where, to staple. +- As the value of the property of a , the value instructs the printer whether, and where, to staple. The `Unknown` value is never used in properties of objects. - You should never set a property to `Unknown`. If some other producing application has created a *PrintTicket document* that sets the stapling feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have `Unknown` as the value of the property. + You should never set a property to `Unknown`. If some other producing application has created a *PrintTicket document* that sets the stapling feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397)), then a object in your application that is constructed with that document will have `Unknown` as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Printing/TrueTypeFontMode.xml b/xml/System.Printing/TrueTypeFontMode.xml index 133bf7e13ab..78ced5eff16 100644 --- a/xml/System.Printing/TrueTypeFontMode.xml +++ b/xml/System.Printing/TrueTypeFontMode.xml @@ -42,11 +42,11 @@ - As members of the collection, which is a property of , these values indicate which of the preceding techniques is available for a particular printer. Many printers support more than one of these techniques. -- As the value of the property of a , the value instructs the printer to handle TrueType fonts in a particular way. +- As the value of the property of a , the value instructs the printer to handle TrueType fonts in a particular way. The **Unknown** value is never used in properties of objects. - You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the TrueType font handling feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), then a object in your application that is constructed with that document will have **Unknown** as the value of the property. + You should never set a property to **Unknown**. If some other producing application has created a *PrintTicket document* that sets the TrueType font handling feature to an unrecognized option (that is, an option that is not defined in the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397), then a object in your application that is constructed with that document will have **Unknown** as the value of the property. Although the and classes cannot be inherited, you can extend the [Print Schema](https://go.microsoft.com/fwlink/?LinkId=186397) to recognize print device features that are not accounted for in the or classes. For more information see [How to: Extend the Print Schema and Create New Print System Classes](https://learn.microsoft.com/previous-versions/aa970573(v=vs.100)). diff --git a/xml/System.Reflection.Emit/AssemblyBuilder.xml b/xml/System.Reflection.Emit/AssemblyBuilder.xml index cf169152682..fb16c4cdc58 100644 --- a/xml/System.Reflection.Emit/AssemblyBuilder.xml +++ b/xml/System.Reflection.Emit/AssemblyBuilder.xml @@ -348,7 +348,7 @@ The following code example shows how to define and use a dynamic assembly. The e property. + To get the absolute path to the loaded manifest-containing file, use the property. ]]> @@ -745,7 +745,7 @@ The following code example shows how to define and use a dynamic assembly. The e ## Remarks To define a persistable dynamic module, this assembly needs to be created with the or the attribute. - If you want the module to contain the assembly manifest, `name` should be the same as the name of the assembly (that is, the property of the used to create the dynamic assembly) and `fileName` should be the same as the filename you specify when you save the assembly. + If you want the module to contain the assembly manifest, `name` should be the same as the name of the assembly (that is, the property of the used to create the dynamic assembly) and `fileName` should be the same as the filename you specify when you save the assembly. In an assembly with only one module, that module should contain the assembly manifest. @@ -832,7 +832,7 @@ The following code example shows how to define and use a dynamic assembly. The e ## Remarks To define a persistable dynamic module, this assembly needs to be created with the or the attribute. - If you want the module to contain the assembly manifest, `name` should be the same as the name of the assembly (that is, the property of the used to create the dynamic assembly) and `fileName` should be the same as the filename you specify when you save the assembly. + If you want the module to contain the assembly manifest, `name` should be the same as the name of the assembly (that is, the property of the used to create the dynamic assembly) and `fileName` should be the same as the filename you specify when you save the assembly. In an assembly with only one module, that module should contain the assembly manifest. diff --git a/xml/System.Reflection.Emit/DynamicILInfo.xml b/xml/System.Reflection.Emit/DynamicILInfo.xml index 7fb700beab9..1bfabac7bf7 100644 --- a/xml/System.Reflection.Emit/DynamicILInfo.xml +++ b/xml/System.Reflection.Emit/DynamicILInfo.xml @@ -226,7 +226,7 @@ object. To call the associated dynamic method recursively, pass the value of the property. + The token returned by this method overload allows you to call a dynamic method from the dynamic method associated with the current object. To call the associated dynamic method recursively, pass the value of the property. ]]> @@ -276,7 +276,7 @@ object. Use the method to get a for the field you want to access, then use the property to get the . + You must obtain a token for any field that will be accessed by the dynamic method associated with the current object. Use the method to get a for the field you want to access, then use the property to get the . ]]> @@ -332,7 +332,7 @@ object. Use the method to get a for the method you want to access, and then use the property to get the . + You must obtain a token for any method that will be accessed by the dynamic method associated with the current object. Use the method to get a for the method you want to access, and then use the property to get the . > [!NOTE] > For a method that belongs to a generic type, use the method overload and specify a for the generic type. @@ -387,7 +387,7 @@ ## Remarks The token returned by this method overload allows you to define a local variable type, and emit MSIL to create an instance of a type in the dynamic method associated with the current object. - To get a representing a type, use the property. + To get a representing a type, use the property. ]]> @@ -481,7 +481,7 @@ object. Use the method to get a for the field you want to access, and then use the property to get the . + You must obtain a token for any field that will be accessed by the dynamic method associated with the current object. Use the method to get a for the field you want to access, and then use the property to get the . ]]> @@ -533,7 +533,7 @@ object. Use the method to get a for the method you want to call, and then use the property to get the . + You must obtain a token for any method that will be called by the dynamic method associated with the current object. Use the method to get a for the method you want to call, and then use the property to get the . ]]> diff --git a/xml/System.Reflection.Emit/DynamicMethod.xml b/xml/System.Reflection.Emit/DynamicMethod.xml index 4202f4d4940..80505153580 100644 --- a/xml/System.Reflection.Emit/DynamicMethod.xml +++ b/xml/System.Reflection.Emit/DynamicMethod.xml @@ -1913,7 +1913,7 @@ The following code example creates a dynamic method that takes two parameters. T ## Examples - The following code example displays the property of a dynamic method. This code example is part of a larger example provided for the class. + The following code example displays the property of a dynamic method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet24"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection.Emit/DynamicMethod/Overview/source.vb" id="Snippet24"::: @@ -2453,7 +2453,7 @@ The following code example creates a dynamic method that takes two parameters. T If a module was specified when the dynamic method was created, this property returns that module. If a type was specified as the owner when the dynamic method was created, this property returns the module that contains that type. ## Examples - The following code example displays the property of a dynamic method. This code example is part of a larger example provided for the class. + The following code example displays the property of a dynamic method. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/DynamicMethod/Overview/source.cs" id="Snippet26"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection.Emit/DynamicMethod/Overview/source.vb" id="Snippet26"::: diff --git a/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml b/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml index abd3ba5d214..ec45666656b 100644 --- a/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml +++ b/xml/System.Reflection.Emit/GenericTypeParameterBuilder.xml @@ -76,7 +76,7 @@ - Special constraints specify that any type assigned to the generic type parameter must have a parameterless constructor, must be a reference type, or must be a value type. Set the special constraints for a type parameter by using the method. - Interface constraints and special constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameters, you can use its object to reflect the constraints. Use the method to get the type parameters, and for each type parameter use the method to get the base type constraint and interface constraints, and the property to get the special constraints. + Interface constraints and special constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameters, you can use its object to reflect the constraints. Use the method to get the type parameters, and for each type parameter use the method to get the base type constraint and interface constraints, and the property to get the special constraints. @@ -341,7 +341,7 @@ object always represents a generic type parameter. The value of the property reflects that fact and does not imply anything about any generic type argument that might be assigned to the type parameter. + A object always represents a generic type parameter. The value of the property reflects that fact and does not imply anything about any generic type argument that might be assigned to the type parameter. ]]> @@ -396,7 +396,7 @@ property is not `null`, then the declaring method is a generic method definition and `DeclaringMethod.IsGenericMethodDefinition` is `true`. + If the property is not `null`, then the declaring method is a generic method definition and `DeclaringMethod.IsGenericMethodDefinition` is `true`. ]]> @@ -3869,9 +3869,9 @@ property. + To retrieve the base type constraint use the property. - Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameter and their constraints. To get the type parameters of a completed generic type, use the method. For each type parameter, get the base type constraint and interface constraints by using the method, and get the special constraints by using the property. + Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameter and their constraints. To get the type parameters of a completed generic type, use the method. For each type parameter, get the base type constraint and interface constraints by using the method, and get the special constraints by using the property. @@ -4125,7 +4125,7 @@ For information on how to format `binaryAttribute`, see the metadata specificati ## Remarks Special constraints can specify that any type assigned to the generic type parameter must have a parameterless constructor, must be a reference type, or must be a value type. - Special constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameters and their constraints. To get the type parameters of a completed generic type, use the method. To get the special constraints for each type parameter, use the property. + Special constraints cannot be retrieved using methods of the class. Once you have created the generic type that contains the type parameter, you can use its object to reflect the type parameters and their constraints. To get the type parameters of a completed generic type, use the method. To get the special constraints for each type parameter, use the property. The enumeration values that refer to the variance characteristics of a type parameter are relevant only in languages that support covariance and contravariance, such as Microsoft intermediate language (MSIL). Visual Basic and C# currently do not support covariance and contravariance. diff --git a/xml/System.Reflection.Emit/ILGenerator.xml b/xml/System.Reflection.Emit/ILGenerator.xml index 6aef79dcd5b..88fa607d435 100644 --- a/xml/System.Reflection.Emit/ILGenerator.xml +++ b/xml/System.Reflection.Emit/ILGenerator.xml @@ -2492,7 +2492,7 @@ The following code example emits two methods, a `varargs` method and a method th ## Remarks This method is transparent, and can be called from partially trusted code. - If the property is accessed before any MSIL instructions have been emitted, it returns 0 (zero). + If the property is accessed before any MSIL instructions have been emitted, it returns 0 (zero). When MSIL is generated for dynamic languages, this property can be used to map offsets in the MSIL stream to source code line numbers. The resulting information can be used to provide stack traces when exceptions are thrown. diff --git a/xml/System.Reflection.Emit/MethodBuilder.xml b/xml/System.Reflection.Emit/MethodBuilder.xml index 69b758ba0e4..5d962a46414 100644 --- a/xml/System.Reflection.Emit/MethodBuilder.xml +++ b/xml/System.Reflection.Emit/MethodBuilder.xml @@ -1791,7 +1791,7 @@ The following example uses the class , call the method on the completed type, and get the property on the resulting . + To determine whether a method in a dynamic assembly is security-critical, complete the type by calling , call the method on the completed type, and get the property on the resulting . ]]> @@ -1835,7 +1835,7 @@ The following example uses the class , call the method on the completed type, and get the property on the resulting . + To determine whether a method in a dynamic assembly is security-safe-critical, complete the type by calling , call the method on the completed type, and get the property on the resulting . ]]> @@ -1879,7 +1879,7 @@ The following example uses the class , call the method on the completed type, and get the property on the resulting . + To determine whether a method in a dynamic assembly is security-transparent, complete the type by calling , call the method on the completed type, and get the property on the resulting . ]]> @@ -2118,7 +2118,7 @@ The following example uses the class property to get the type in which the method is being declared, and then calling the property of the resulting object. + This property is provided as a convenience. It is equivalent to using the 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 . diff --git a/xml/System.Reflection.Emit/ModuleBuilder.xml b/xml/System.Reflection.Emit/ModuleBuilder.xml index 58518f47e7f..d1f31c354c9 100644 --- a/xml/System.Reflection.Emit/ModuleBuilder.xml +++ b/xml/System.Reflection.Emit/ModuleBuilder.xml @@ -4554,7 +4554,7 @@ property is referred to as the `mvid`, and is stored in the GUID heap. + In unmanaged metadata, the GUID returned by the property is referred to as the `mvid`, and is stored in the GUID heap. > [!NOTE] > More information about metadata 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/). diff --git a/xml/System.Reflection.Emit/OpCode.xml b/xml/System.Reflection.Emit/OpCode.xml index f9ef996029c..8fbdffd1e08 100644 --- a/xml/System.Reflection.Emit/OpCode.xml +++ b/xml/System.Reflection.Emit/OpCode.xml @@ -356,11 +356,11 @@ The name of the intermediate language (IL) instruction. Read-only. The name of the IL instruction. - property returns the numeric value of the IL instruction. - + property returns the numeric value of the IL instruction. + ]]> @@ -768,19 +768,19 @@ Gets the numeric value of the intermediate language (IL) instruction. Read-only. The numeric value of the IL instruction. - property returns the string name that corresponds to the instruction's numeric value. - - - -## Examples - The following example displays the property values of the instruction. - + property returns the string name that corresponds to the instruction's numeric value. + + + +## Examples + The following example displays the property values of the instruction. + :::code language="csharp" source="~/snippets/csharp/System.Reflection.Emit/OpCode/Value/value1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Reflection.Emit/OpCode/Value/value1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Reflection.Emit/OpCode/Value/value1.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Reflection.Emit/PropertyBuilder.xml b/xml/System.Reflection.Emit/PropertyBuilder.xml index d0214479320..c5b6548520f 100644 --- a/xml/System.Reflection.Emit/PropertyBuilder.xml +++ b/xml/System.Reflection.Emit/PropertyBuilder.xml @@ -981,7 +981,7 @@ property to get the type in which the property is declared, and then calling the property of the resulting object. + This property is provided as a convenience for the user. It is equivalent to using the property to get the type in which the property is declared, and then calling the property of the resulting object. ]]> diff --git a/xml/System.Reflection.Emit/TypeBuilder.xml b/xml/System.Reflection.Emit/TypeBuilder.xml index 70650fe6e97..551fb287014 100644 --- a/xml/System.Reflection.Emit/TypeBuilder.xml +++ b/xml/System.Reflection.Emit/TypeBuilder.xml @@ -4561,7 +4561,7 @@ See for a description of the format of the > [!NOTE] > When emitting code, a generic type parameter is represented by a object rather than by a object. - If the current does not represent a generic type parameter, the value of this property is undefined. Use the property to determine whether the current represents a generic type parameter. + If the current does not represent a generic type parameter, the value of this property is undefined. Use the property to determine whether the current represents a generic type parameter. ]]> @@ -5523,7 +5523,7 @@ See for a description of the format of the A object represents a generic type definition if the method has been used to give it generic type parameters. This method retrieves the objects that represent the generic type parameters. - For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. + For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. ]]> @@ -5605,7 +5605,7 @@ See for a description of the format of the method on a object for which the property returns `true`, the property returns the current instance. A that represents a generic type is always a generic type definition. + If you call the method on a object for which the property returns `true`, the property returns the current instance. A that represents a generic type is always a generic type definition. If you used the method to construct a generic type from a object that represents a generic type definition, using the method on the constructed type gets back the object that represents the generic type definition. @@ -7230,7 +7230,7 @@ See for a description of the format of the ## Remarks A object represents a generic type definition if the method has been used to give it generic type parameters. An instance of the class that is generic is always a generic type definition. - For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. + For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. ]]> @@ -7286,7 +7286,7 @@ See for a description of the format of the A can be used to build generic type definitions, but not constructed generic types. To get a constructed generic type, call the method on a that represents a generic type definition. - For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. + For more information on generic types in reflection and a list of the invariant conditions for terms used in generic reflection, see the property. ]]> diff --git a/xml/System.Reflection/AmbiguousMatchException.xml b/xml/System.Reflection/AmbiguousMatchException.xml index e38d91065ae..b3f12b3a222 100644 --- a/xml/System.Reflection/AmbiguousMatchException.xml +++ b/xml/System.Reflection/AmbiguousMatchException.xml @@ -280,7 +280,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Reflection/Assembly.xml b/xml/System.Reflection/Assembly.xml index 359038de65a..70bf710c1d8 100644 --- a/xml/System.Reflection/Assembly.xml +++ b/xml/System.Reflection/Assembly.xml @@ -153,7 +153,7 @@ ## Examples The following code example shows how to obtain the currently executing assembly, create an instance of a type contained in that assembly, and invoke one of the type's methods with late binding. For this purpose, the code example defines a class named `Example`, with a method named `SampleMethod`. The constructor of the class accepts an integer, which is used to compute the return value of the method. - The code example also demonstrates the use of the method to obtain an object that can be used to parse the full name of the assembly. The example displays the version number of the assembly, the property, and the property. + The code example also demonstrates the use of the method to obtain an object that can be used to parse the full name of the assembly. The example displays the version number of the assembly, the property, and the property. :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/Assembly/Overview/source.vb" id="Snippet1"::: @@ -281,14 +281,14 @@ property instead. + To get the absolute path to the loaded manifest-containing file, use the property instead. If the assembly was loaded as a byte array, using an overload of the method that takes an array of bytes, this property returns the location of the caller of the method, not the location of the loaded assembly. In .NET 5 and later versions, for bundled assemblies, this property throws an exception. ## Examples - The following example uses the property. + The following example uses the property. :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/CodeBase/codebase1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/Assembly/CodeBase/codebase1.vb" id="Snippet1"::: @@ -381,7 +381,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex - You haven't specified the fully qualified name of the type. -- You've specified the fully qualified type name, but its case doesn't match the case of the type's property. For a case-insensitive comparison of `typeName` with the type's full name, call the overload and specify `true` for the `ignoreCase` argument. +- You've specified the fully qualified type name, but its case doesn't match the case of the type's property. For a case-insensitive comparison of `typeName` with the type's full name, call the overload and specify `true` for the `ignoreCase` argument. - The type doesn't exist in the current instance. @@ -499,7 +499,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex ## Examples - The following example defines a `Person` class. It then calls the method to instantiate it, but because the casing of the `typeName` argument doesn't match that of the type's property, the method returns `null`. When the example passes the same string to the overload and specifies that the comparison should be case-insensitive, the `Person` class is found, and a `Person` object is successfully instantiated. + The following example defines a `Person` class. It then calls the method to instantiate it, but because the casing of the `typeName` argument doesn't match that of the type's property, the method returns `null`. When the example passes the same string to the overload and specifies that the comparison should be case-insensitive, the `Person` class is found, and a `Person` object is successfully instantiated. :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/CreateInstance/createinstance2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/Assembly/CreateInstance/createinstance2.vb" id="Snippet2"::: @@ -818,7 +818,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex property is comparable to the method, except that the property returns a collection of objects, and the method returns an array of objects. + The property is comparable to the method, except that the property returns a collection of objects, and the method returns an array of objects. The returned array includes nested types. @@ -1172,7 +1172,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex > [!NOTE] > Writing your own code to parse display names is not recommended. Instead, pass the display name to the constructor, which parses it and populates the appropriate fields of the new . - In the .NET Framework version 2.0, processor architecture is added to assembly identity, and can be specified as part of assembly name strings. However, it is not included in the string returned by the property, for compatibility reasons. See . + In the .NET Framework version 2.0, processor architecture is added to assembly identity, and can be specified as part of assembly name strings. However, it is not included in the string returned by the property, for compatibility reasons. See . @@ -1683,7 +1683,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex object that represents the current assembly is to use the property of a type found in the assembly, as the following example illustrates. + For performance reasons, you should call this method only when you do not know at design time what assembly is currently executing. The recommended way to retrieve an object that represents the current assembly is to use the property of a type found in the assembly, as the following example illustrates. :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/GetExecutingAssembly/assembly1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/Assembly/GetExecutingAssembly/assembly1.vb" id="Snippet1"::: @@ -1693,7 +1693,7 @@ In .NET 5 and later versions, for bundled assemblies, this property throws an ex ## Examples - The following example uses the property to get the currently executing assembly based on a type contained in that assembly. It also calls the method to show that it returns an object that represents the same assembly. + The following example uses the property to get the currently executing assembly based on a type contained in that assembly. It also calls the method to show that it returns an object that represents the same assembly. :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/GetExecutingAssembly/getexecutingassembly1.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/Assembly/GetExecutingAssembly/getexecutingassembly1.vb" id="Snippet5"::: @@ -2597,7 +2597,7 @@ Note: In .NET for Win ## Remarks This method works on file names. - Classes in the `Reflection.Emit` namespace emit the scope name for a dynamic module. The scope name can be determined by the property. Pass the kind of module you want to `Assembly.GetModule`. For example, if you want the module that contains the assembly manifest, pass the scope name of the module to `GetModule`. Otherwise, pass the file name of the module. Assemblies loaded by one of the `Load` methods that have a byte[] parameter have only one module, and that is the manifest module. Always seek these modules using the scope name. + Classes in the `Reflection.Emit` namespace emit the scope name for a dynamic module. The scope name can be determined by the property. Pass the kind of module you want to `Assembly.GetModule`. For example, if you want the module that contains the assembly manifest, pass the scope name of the module to `GetModule`. Otherwise, pass the file name of the module. Assemblies loaded by one of the `Load` methods that have a byte[] parameter have only one module, and that is the manifest module. Always seek these modules using the scope name. A type can be retrieved from a specific module using . Calling `Module.GetType` on the module containing the manifest will not initiate a search of the entire assembly. To retrieve a type from an assembly, regardless of which module it is in, you must call . @@ -3595,7 +3595,7 @@ Note: In .NET for Win > [!NOTE] > If a type has been forwarded to another assembly, it is not included in the returned array. For information on type forwarding, see [Type Forwarding in the Common Language Runtime](/dotnet/standard/assembly/type-forwarding). - To retrieve a collection of objects instead of an array of objects, use the property. + To retrieve a collection of objects instead of an array of objects, use the property. ## Examples The following example displays parameters of one method on a type in the specified assembly. @@ -3956,7 +3956,7 @@ This property is marked obsolete starting in .NET 5, and generates a compile-tim ## Remarks Dynamic assemblies are represented by the derived class . - When a dynamic assembly is saved to disk, the saved assembly is not dynamic. If the saved assembly is loaded into another application domain or process, the property returns `false`. + When a dynamic assembly is saved to disk, the saved assembly is not dynamic. If the saved assembly is loaded into another application domain or process, the property returns `false`. ]]> @@ -4165,10 +4165,10 @@ This property is marked obsolete starting in .NET 5, and generates a compile-tim > **.NET Framework only:** For information about loading assemblies from remote locations, see [``](/dotnet/framework/configure-apps/file-schema/runtime/loadfromremotesources-element). > [!NOTE] -> **.NET Framework only:** Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](/dotnet/framework/deployment/best-practices-for-assembly-loading). +> **.NET Framework only:** Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](/dotnet/framework/deployment/best-practices-for-assembly-loading). > [!NOTE] -> **.NET Framework only:** If both the property and the property are set, the first attempt to load the assembly uses the display name (including version, culture, and so on, as returned by the property). If the file is not found, is used to search for the assembly. If the assembly is found using , the display name is matched against the assembly. If the match fails, a is thrown. +> **.NET Framework only:** If both the property and the property are set, the first attempt to load the assembly uses the display name (including version, culture, and so on, as returned by the property). If the file is not found, is used to search for the assembly. If the assembly is found using , the display name is matched against the assembly. If the match fails, a is thrown. ## Examples The following example instantiates an object and uses it to load the `sysglobal.dll` assembly. The example then displays the full name of the assembly's public types. @@ -4256,7 +4256,7 @@ Note: In .NET for Win In .NET Core/.NET 5+, the target assembly will be loaded into the current or into the context if it's set. For more information on assembly loading, see [Managed assembly loading algorithm](/dotnet/core/dependency-loading/loading-managed#algorithm). -To load the correct assembly, it's recommended to call the `Load` method by passing the long form of the assembly name. The long form of an assembly name consists of its simple name (such as "System" for the System.dll assembly) along with its version, culture, public key token, and optionally its processor architecture. It corresponds to the assembly's property. The following example illustrates the use of a long name to load the System.dll assembly for .NET Framework 4: +To load the correct assembly, it's recommended to call the `Load` method by passing the long form of the assembly name. The long form of an assembly name consists of its simple name (such as "System" for the System.dll assembly) along with its version, culture, public key token, and optionally its processor architecture. It corresponds to the assembly's property. The following example illustrates the use of a long name to load the System.dll assembly for .NET Framework 4: :::code language="csharp" source="~/snippets/csharp/System.Reflection/Assembly/Load/load11.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/Assembly/Load/load11.vb" id="Snippet1"::: @@ -4430,7 +4430,7 @@ In .NET Core/5+, the target assembly is loaded into the current `](/dotnet/framework/configure-apps/file-schema/runtime/loadfromremotesources-element) for loading assemblies from remote locations. > [!NOTE] -> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](/dotnet/framework/deployment/best-practices-for-assembly-loading). +> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](/dotnet/framework/deployment/best-practices-for-assembly-loading). Whether certain permissions are granted or not granted to an assembly is based on evidence. The rules for assembly and security evidence merging are as follows: @@ -4443,7 +4443,7 @@ In .NET Core/5+, the target assembly is loaded into the current method with a `Byte[]` parameter and to load a COFF image, only the supplied evidence is used. Evidence of the calling assembly and evidence of the COFF image is ignored. > [!NOTE] -> If both the property and the property are set, the first attempt to load the assembly uses the display name (including version, culture, and so on, as returned by the property). If the file is not found, is used to search for the assembly. If the assembly is found using , the display name is matched against the assembly. If the match fails, a is thrown. +> If both the property and the property are set, the first attempt to load the assembly uses the display name (including version, culture, and so on, as returned by the property). If the file is not found, is used to search for the assembly. If the assembly is found using , the display name is matched against the assembly. If the match fails, a is thrown. If you call the method more than once on the same assembly but with a different evidence specified, the common language runtime does not throw a because the equality and integrity of the different evidence specifications cannot be determined. The evidence that first succeeds is the evidence that is used. @@ -5778,7 +5778,7 @@ The assembly is loaded into the default AssemblyLoadContext. For more informatio In .NET 5 and later versions, for bundled assemblies, the value returned is an empty string. -.NET Framework only: If the loaded file was [shadow-copied](/dotnet/framework/app-domains/shadow-copy-assemblies), the location is that of the file after being shadow-copied. To get the location before the file has been shadow-copied, use the property. +.NET Framework only: If the loaded file was [shadow-copied](/dotnet/framework/app-domains/shadow-copy-assemblies), the location is that of the file after being shadow-copied. To get the location before the file has been shadow-copied, use the property. ## Examples The following example displays the location of the loaded file that contains the manifest. diff --git a/xml/System.Reflection/AssemblyFlagsAttribute.xml b/xml/System.Reflection/AssemblyFlagsAttribute.xml index 9286fb65c21..47e8ffbf52e 100644 --- a/xml/System.Reflection/AssemblyFlagsAttribute.xml +++ b/xml/System.Reflection/AssemblyFlagsAttribute.xml @@ -70,14 +70,14 @@ ## Remarks The enumeration describes the assembly characteristics that can be set using this attribute. - To access the flags that have been specified for an assembly, use the property to obtain an object, then use the property to obtain an value. + To access the flags that have been specified for an assembly, use the property to obtain an object, then use the property to obtain an value. - To specify flags for a dynamic assembly, set the property of the object that you pass to the method. + To specify flags for a dynamic assembly, set the property of the object that you pass to the method. ## Examples - The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. + The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyFlagsAttribute/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyFlagsAttribute/Overview/source.vb" id="Snippet1"::: @@ -208,7 +208,7 @@ to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. + The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyFlagsAttribute/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyFlagsAttribute/Overview/source.vb" id="Snippet1"::: @@ -338,7 +338,7 @@ ## Examples - The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. + The following code example shows how to apply the to an assembly, and how to read the flags at run time. The example also creates an instance of the attribute, and uses the property to display the flags. For an example of how to apply the to a dynamic assembly, see the property. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyFlagsAttribute/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyFlagsAttribute/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/AssemblyName.xml b/xml/System.Reflection/AssemblyName.xml index 08da18d4173..bced6a8e924 100644 --- a/xml/System.Reflection/AssemblyName.xml +++ b/xml/System.Reflection/AssemblyName.xml @@ -454,17 +454,17 @@ Note: In .NET for Win property. + When an assembly is loaded, this value can also be obtained using the property. If the assembly was loaded as a byte array, this property returns the location of the caller of the method overload, not the location of the loaded assembly. > [!NOTE] -> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](/dotnet/framework/deployment/best-practices-for-assembly-loading). +> Do not use an with only the property set. The property does not supply any elements of the assembly identity (such as name or version), so loading does not occur according to load-by-identity rules, as you would expect from the method. Instead, the assembly is loaded using load-from rules. For information about the disadvantages of using the load-from context, see the method overload or [Best Practices for Assembly Loading](/dotnet/framework/deployment/best-practices-for-assembly-loading). ## Examples - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to specify the directory where the assembly is saved. + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to specify the directory where the assembly is saved. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.vb" id="Snippet1"::: @@ -572,7 +572,7 @@ Note: In .NET for Win property is used to specify the culture, which is part of the assembly's display name. + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to specify the culture, which is part of the assembly's display name. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.vb" id="Snippet2"::: @@ -741,7 +741,7 @@ Note: In .NET for Win property is used to specify that the assembly has a public key. + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to specify that the assembly has a public key. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/Flags/assemblyname_keypair.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyName/Flags/assemblyname_keypair.vb" id="Snippet4"::: @@ -817,12 +817,12 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 Writing your own code to parse display names is not recommended. Instead, pass the display name to the constructor, which parses it and populates the appropriate fields of the new . - When an assembly is loaded, this value can also be obtained using the property. + When an assembly is loaded, this value can also be obtained using the property. ## Examples - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the code example sets the , , , and properties, which together comprise an assembly's full name, or display name. The property is then used to retrieve the display name. + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the code example sets the , , , and properties, which together comprise an assembly's full name, or display name. The property is then used to retrieve the display name. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.vb" id="Snippet4"::: @@ -1162,12 +1162,12 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 ## Remarks > [!IMPORTANT] -> Starting with the .NET Framework 4, the property of an object that is returned by the method is if there is no hash algorithm for the referenced assembly, or if the hash algorithm of the referenced assembly is not identified by the enumeration. In previous versions of the .NET Framework, the property returned in this situation. +> Starting with the .NET Framework 4, the property of an object that is returned by the method is if there is no hash algorithm for the referenced assembly, or if the hash algorithm of the referenced assembly is not identified by the enumeration. In previous versions of the .NET Framework, the property returned in this situation. ## Examples - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to set the hash algorithm for the assembly manifest. + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to set the hash algorithm for the assembly manifest. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyName/CodeBase/assemblyname_codebase.vb" id="Snippet3"::: @@ -1229,10 +1229,10 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 property. The getter for the property is only useful if the user set the property before using the object to create a dynamic assembly, and subsequently wants to retrieve the key pair. + When the runtime loads an assembly, it does not set the property. The getter for the property is only useful if the user set the property before using the object to create a dynamic assembly, and subsequently wants to retrieve the key pair. ## Examples - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to set the assembly's public and private cryptographic keys. + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to set the assembly's public and private cryptographic keys. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/Flags/assemblyname_keypair.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyName/Flags/assemblyname_keypair.vb" id="Snippet1"::: @@ -1299,7 +1299,7 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 ## Examples - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to set the simple name of the dynamic assembly. + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to set the simple name of the dynamic assembly. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/.ctor/assemblyname_constructor.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyName/.ctor/assemblyname_constructor.vb" id="Snippet2"::: @@ -1951,7 +1951,7 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 ## Examples - This section contains two examples. The first example shows how to retrieve the version of the currently executing assembly. The second example shows how to use the property to specify the assembly version when you emit a dynamic assembly. + This section contains two examples. The first example shows how to retrieve the version of the currently executing assembly. The second example shows how to use the property to specify the assembly version when you emit a dynamic assembly. **Example 1** @@ -1962,7 +1962,7 @@ mylib, Version=1.2.1900.0, Culture=neutral, PublicKeyToken=a14f3033def15840 **Example 2** - The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to specify version information for the assembly. + The following example emits a dynamic assembly and saves it to the current directory. When the assembly is created, the property is used to specify version information for the assembly. :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyName/.ctor/assemblyname_constructor.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyName/.ctor/assemblyname_constructor.vb" id="Snippet3"::: diff --git a/xml/System.Reflection/AssemblyTitleAttribute.xml b/xml/System.Reflection/AssemblyTitleAttribute.xml index c11e61fa7d0..31fe7b37d98 100644 --- a/xml/System.Reflection/AssemblyTitleAttribute.xml +++ b/xml/System.Reflection/AssemblyTitleAttribute.xml @@ -80,7 +80,7 @@ ## Examples The following example shows how to add attributes, including the attribute, to a dynamic assembly. The example saves the assembly to disk, and the attribute value can be viewed by using the **Windows File Properties** dialog box. - + :::code language="csharp" source="~/snippets/csharp/System.Reflection/AssemblyCompanyAttribute/Overview/assemblybuilder_defineversioninforesource.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/AssemblyCompanyAttribute/Overview/assemblybuilder_defineversioninforesource.vb" id="Snippet1"::: @@ -192,7 +192,7 @@ property appears on the **Details** tab of the **Windows File Properties** dialog box for the assembly. The property name is **File description**. In Windows XP, this property appears on the **Version** tab of the **Windows File Properties** dialog box. + In Windows Vista, the value of the property appears on the **Details** tab of the **Windows File Properties** dialog box for the assembly. The property name is **File description**. In Windows XP, this property appears on the **Version** tab of the **Windows File Properties** dialog box. ]]> diff --git a/xml/System.Reflection/AssemblyVersionAttribute.xml b/xml/System.Reflection/AssemblyVersionAttribute.xml index 550a72e1773..5f7df368e7b 100644 --- a/xml/System.Reflection/AssemblyVersionAttribute.xml +++ b/xml/System.Reflection/AssemblyVersionAttribute.xml @@ -111,14 +111,14 @@ You can mitigate some of these issues by limiting the use of time-based versions The assembly major and minor versions are used as the type library version number when the assembly is exported. Some COM hosts do not accept type libraries with the version number 0.0. Therefore, if you want to expose an assembly to COM clients, set the assembly version explicitly to 1.0 in the `AssemblyVersionAttribute` page for projects created outside Visual Studio 2005 and with no `AssemblyVersionAttribute` specified. Do this even when the assembly version is 0.0. All projects created in Visual Studio 2005 have a default assembly version of 1.0.*. - To get the name of an assembly you have loaded, call on the assembly to get an , and then get the property. To get the name of an assembly you have not loaded, call from your client application to check the assembly version that your application uses. + To get the name of an assembly you have loaded, call on the assembly to get an , and then get the property. To get the name of an assembly you have not loaded, call from your client application to check the assembly version that your application uses. The attribute can only be applied once. Some Visual Studio project templates already include the attribute. In those projects, adding the attribute in code causes a compiler error. ## Examples - The following example uses the attribute to assign a version number to an assembly. At compile time, this version information is stored with the assembly's metadata. At run time, the example retrieves the value of the property on a type found in the assembly to get a reference to the executing assembly, and it retrieves the assembly's version information from the property of the object returned by the method. + The following example uses the attribute to assign a version number to an assembly. At compile time, this version information is stored with the assembly's metadata. At run time, the example retrieves the value of the property on a type found in the assembly to get a reference to the executing assembly, and it retrieves the assembly's version information from the property of the object returned by the method. :::code language="csharp" source="~/snippets/csharp/System/Version/Overview/example1.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System/Version/Overview/example1.vb" id="Snippet6"::: diff --git a/xml/System.Reflection/Binder.xml b/xml/System.Reflection/Binder.xml index f466f0e02f3..07d19d8a756 100644 --- a/xml/System.Reflection/Binder.xml +++ b/xml/System.Reflection/Binder.xml @@ -70,13 +70,13 @@ ## Remarks Implementations of the class are used by methods such as , which selects from a set of possible members to execute, based on a set of parameter types and argument values; , which selects a method based on parameter types; and so on. - A default implementation of the class is provided by the property. + A default implementation of the class is provided by the property. ## Examples The following example implements and demonstrates all members of the `Binder` class. The private method `CanConvertFrom` finds compatible types for a given type. - + :::code language="csharp" source="~/snippets/csharp/System.Reflection/Binder/Overview/binder.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/Binder/Overview/binder.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/ConstructorInfo.xml b/xml/System.Reflection/ConstructorInfo.xml index 0f08f9e4149..2734ebef483 100644 --- a/xml/System.Reflection/ConstructorInfo.xml +++ b/xml/System.Reflection/ConstructorInfo.xml @@ -615,12 +615,12 @@ Note: In .NET for Win . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a constructor. + This property overrides . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a constructor. ## Examples - The following example uses the property to identify a object as a constructor. + The following example uses the property to identify a object as a constructor. :::code language="csharp" source="~/snippets/csharp/System.Reflection/ConstructorInfo/MemberType/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ConstructorInfo/MemberType/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/CustomAttributeData.xml b/xml/System.Reflection/CustomAttributeData.xml index f803231f753..518ad51de86 100644 --- a/xml/System.Reflection/CustomAttributeData.xml +++ b/xml/System.Reflection/CustomAttributeData.xml @@ -86,15 +86,15 @@ ## Remarks Code that is being examined in the reflection-only context cannot be executed, so it is not always possible to examine custom attributes by creating instances of them and then examining their properties, using methods like , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. - The class allows examination of custom attributes in the reflection-only context by providing an abstraction for attributes. The members of this class can be used to obtain the positional arguments and named arguments of the attribute. Use the property to get a list of structures that represent the positional arguments, and use the property to get a list of structures that represent the named arguments. + The class allows examination of custom attributes in the reflection-only context by providing an abstraction for attributes. The members of this class can be used to obtain the positional arguments and named arguments of the attribute. Use the property to get a list of structures that represent the positional arguments, and use the property to get a list of structures that represent the named arguments. > [!NOTE] -> The structure only provides information about the attribute property used to get and set the argument value. To obtain the type and value of the argument, use the property to obtain a structure. +> The structure only provides information about the attribute property used to get and set the argument value. To obtain the type and value of the argument, use the property to obtain a structure. - When you have a structure for an argument, whether named or positional, use the property to get the type and the property to get the value. + When you have a structure for an argument, whether named or positional, use the property to get the type and the property to get the value. > [!NOTE] -> For an array argument, the property returns a generic of objects. Each object in the collection represents the corresponding element of the array. +> For an array argument, the property returns a generic of objects. Each object in the collection represents the corresponding element of the array. can be used in the execution context as well as in the reflection-only context. For example, you might want to avoid loading the assembly that contains the code for a custom attribute. Using the class is different from using methods like : @@ -292,7 +292,7 @@ The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, the returned by this property is used to display a text string that describes the constructor, demonstrating that the property returns the constructor that would initialize the attribute. + The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, the returned by this property is used to display a text string that describes the constructor, demonstrating that the property returns the constructor that would initialize the attribute. :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/CustomAttributeData/Overview/source.vb" id="Snippet1"::: @@ -373,7 +373,7 @@ The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, this property is used to display the list of arguments passed to the constructor that initialized the attribute. + The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, this property is used to display the list of arguments passed to the constructor that initialized the attribute. :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/CustomAttributeData/Overview/source.vb" id="Snippet1"::: @@ -854,7 +854,7 @@ The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, this property is used to display the list of named arguments specified for the attribute. + The property is used in the `ShowAttributeData` method that displays custom attribute data. In this code example, this property is used to display the list of named arguments specified for the attribute. :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/CustomAttributeData/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/CustomAttributeFormatException.xml b/xml/System.Reflection/CustomAttributeFormatException.xml index d2d75457a45..f5abb016e49 100644 --- a/xml/System.Reflection/CustomAttributeFormatException.xml +++ b/xml/System.Reflection/CustomAttributeFormatException.xml @@ -297,7 +297,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Reflection/CustomAttributeNamedArgument.xml b/xml/System.Reflection/CustomAttributeNamedArgument.xml index 42c5127cc87..78e316b1ad6 100644 --- a/xml/System.Reflection/CustomAttributeNamedArgument.xml +++ b/xml/System.Reflection/CustomAttributeNamedArgument.xml @@ -95,7 +95,7 @@ ## Remarks Code that is being examined in the reflection-only context cannot be executed, so it is not always possible to examine custom attributes by creating instances of them and then examining their properties, using methods like , , and so on. If the code for the attribute type itself is loaded into the reflection-only context, it cannot be executed. - The structure is used by the class to provide access to a named argument specified for a custom attribute instance, without executing the code of the corresponding property of the custom attribute type. The property returns a structure that contains the type and value of the named argument. + The structure is used by the class to provide access to a named argument specified for a custom attribute instance, without executing the code of the corresponding property of the custom attribute type. The property returns a structure that contains the type and value of the named argument. > [!IMPORTANT] > Whether an argument is named or positional, you must access its type and value by using the structure. @@ -752,7 +752,7 @@ The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - The property is used in the `ShowAttributeData` method that displays custom attribute data, to obtain the types and values of named attributes. + The property is used in the `ShowAttributeData` method that displays custom attribute data, to obtain the types and values of named attributes. :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/CustomAttributeData/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/CustomAttributeTypedArgument.xml b/xml/System.Reflection/CustomAttributeTypedArgument.xml index af696e6c5cf..8467c8a06e4 100644 --- a/xml/System.Reflection/CustomAttributeTypedArgument.xml +++ b/xml/System.Reflection/CustomAttributeTypedArgument.xml @@ -97,9 +97,9 @@ The structure is used by the class to provide access to the type and value of a positional argument specified for a custom attribute instance, without executing the attribute constructor. It also provides access to the type and value of a named argument without executing the code of the corresponding property of the custom attribute type. - The types and values of all the positional and named arguments of an attribute instance are provided by structures. The positional attributes returned by the property are directly represented by structures, but the named arguments returned by the property are represented by structures; to get the structure for a named argument, use the property. + The types and values of all the positional and named arguments of an attribute instance are provided by structures. The positional attributes returned by the property are directly represented by structures, but the named arguments returned by the property are represented by structures; to get the structure for a named argument, use the property. - If an argument is an array of values, the property of the that represents the argument returns a generic of objects. Each object in the collection represents the corresponding element of the array. + If an argument is an array of values, the property of the that represents the argument returns a generic of objects. Each object in the collection represents the corresponding element of the array. To create instances of the class, use the `static` factory method. @@ -296,7 +296,7 @@ property. For array arguments, this property returns the array type, but the property returns a `ReadOnlyCollection` (`ReadOnlyCollection(Of CustomAttributeTypedArgument)` in Visual Basic) in which each element of the collection represents the corresponding element of the array argument. + For simple arguments or for elements of array arguments, this property identifies the actual type of the value returned by the property. For array arguments, this property returns the array type, but the property returns a `ReadOnlyCollection` (`ReadOnlyCollection(Of CustomAttributeTypedArgument)` in Visual Basic) in which each element of the collection represents the corresponding element of the array argument. @@ -307,7 +307,7 @@ The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - The property is used in the `ShowValueOrArray` method that displays custom attribute data, to display the types of attributes. + The property is used in the `ShowValueOrArray` method that displays custom attribute data, to display the types of attributes. :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/CustomAttributeData/Overview/source.vb" id="Snippet1"::: @@ -683,7 +683,7 @@ ## Remarks If the represents an array argument, this property returns a `ReadOnlyCollection` (`ReadOnlyCollection(Of CustomAttributeTypedArgument)` in Visual Basic). Each element of the collection represents the corresponding element of the array argument. - The type of the value can be obtained by using the property. gets the actual type of the value returned by the property for simple arguments or for elements of array arguments. It returns the array type for array arguments. + The type of the value can be obtained by using the property. gets the actual type of the value returned by the property for simple arguments or for elements of array arguments. It returns the array type for array arguments. @@ -694,7 +694,7 @@ The attribute that is applied to the type demonstrates array properties, with both positional and named arguments. - The property is used in the `ShowValueOrArray` method that displays custom attribute data, to display the values of attributes. + The property is used in the `ShowValueOrArray` method that displays custom attribute data, to display the values of attributes. :::code language="csharp" source="~/snippets/csharp/System.Reflection/CustomAttributeData/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/CustomAttributeData/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/EventInfo.xml b/xml/System.Reflection/EventInfo.xml index 1819298eab6..083085ec963 100644 --- a/xml/System.Reflection/EventInfo.xml +++ b/xml/System.Reflection/EventInfo.xml @@ -243,7 +243,7 @@ You might use the `AddEventHandler` method when you load a type after the progra ## Examples The following example creates an instance of the class, creates an event handler using a dynamic assembly, and hooks up the dynamic event handler. All actions are performed using late binding. - The instance is stored in a variable of type , and all code that accesses the does so late-bound. The example uses the method to get the event, and the property to get the delegate type for the event. + The instance is stored in a variable of type , and all code that accesses the does so late-bound. The example uses the method to get the event, and the property to get the delegate type for the event. The example gets a for the `Invoke` method of the delegate type and obtains the signature of the delegate from the instance. The example then creates a dynamic assembly with one module containing a single type named `Handler` and gives the type a `static` method (`Shared` method in Visual Basic) named `DynamicHandler` that handles the event. @@ -496,7 +496,7 @@ Note: In property to discover the delegate type of an event and to display its parameter types. + The following example uses the property to discover the delegate type of an event and to display its parameter types. The example defines a delegate named `MyDelegate` and an event named `ev` of type `MyDelegate`. The code in the `Main` method discovers the event signature by getting the delegate type of the event, getting the `Invoke` method of the delegate type, and then retrieving and displaying the parameters. @@ -1335,7 +1335,7 @@ remove_( handler) . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is an event. + This property overrides . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is an event. ]]> diff --git a/xml/System.Reflection/ExceptionHandlingClause.xml b/xml/System.Reflection/ExceptionHandlingClause.xml index 5394cbe76e3..b8934305a71 100644 --- a/xml/System.Reflection/ExceptionHandlingClause.xml +++ b/xml/System.Reflection/ExceptionHandlingClause.xml @@ -62,19 +62,19 @@ class provides information about the clauses in a `try`…`catch`…`finally` block (`Try`…`Catch`…`Finally` in Visual Basic). To get a list of exception-handling clauses in a method, obtain a that represents the method. Use the method to obtain a object, and then use the property to get the list of clauses. + The class provides information about the clauses in a `try`…`catch`…`finally` block (`Try`…`Catch`…`Finally` in Visual Basic). To get a list of exception-handling clauses in a method, obtain a that represents the method. Use the method to obtain a object, and then use the property to get the list of clauses. > [!NOTE] > Working with exception-handling clauses requires a thorough understanding of metadata and Microsoft intermediate language (MSIL) instruction formats. Information can be found in the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/), especially "Partition II: Metadata Definition and Semantics". ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. You can use Ildasm.exe to examine the MSIL for the compiled code example, to see how the offsets and lengths are calculated. This code is part of a larger example located in the class topic. - + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ExceptionHandlingClause/Overview/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ExceptionHandlingClause/Overview/source.vb" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ExceptionHandlingClause/Overview/source.cs" id="Snippet4"::: @@ -185,7 +185,7 @@ > Working with exception-handling clauses requires a thorough understanding of metadata and Microsoft intermediate language (MSIL) instruction formats. Information can be found in the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/), especially "Partition II: Metadata Definition and Semantics". ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. This code is part of a larger example located in the class topic. @@ -309,7 +309,7 @@ > Working with exception-handling clauses requires a thorough understanding of metadata and Microsoft intermediate language (MSIL) instruction formats. Information can be found in the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/), especially "Partition II: Metadata Definition and Semantics". ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. This code is part of a larger example located in the class topic. @@ -378,7 +378,7 @@ > Working with exception-handling clauses requires a thorough understanding of metadata and Microsoft intermediate language (MSIL) instruction formats. Information can be found in the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/), especially "Partition II: Metadata Definition and Semantics". ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. This code is part of a larger example located in the class topic. @@ -446,7 +446,7 @@ > Working with exception-handling clauses requires a thorough understanding of metadata and Microsoft intermediate language (MSIL) instruction formats. Information can be found in the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/), especially "Partition II: Metadata Definition and Semantics". ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. This code is part of a larger example located in the class topic. @@ -557,7 +557,7 @@ > Working with exception-handling clauses requires a thorough understanding of metadata and Microsoft intermediate language (MSIL) instruction formats. Information can be found in the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/), especially "Partition II: Metadata Definition and Semantics". ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. This code is part of a larger example located in the class topic. @@ -625,7 +625,7 @@ > Working with exception-handling clauses requires a thorough understanding of metadata and Microsoft intermediate language (MSIL) instruction formats. Information can be found in the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/), especially "Partition II: Metadata Definition and Semantics". ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. This code is part of a larger example located in the class topic. diff --git a/xml/System.Reflection/ExceptionHandlingClauseOptions.xml b/xml/System.Reflection/ExceptionHandlingClauseOptions.xml index 000b1f38b8c..0380ee90a81 100644 --- a/xml/System.Reflection/ExceptionHandlingClauseOptions.xml +++ b/xml/System.Reflection/ExceptionHandlingClauseOptions.xml @@ -57,17 +57,17 @@ object and call the method to obtain the method body. Use the property to obtain a list of objects. + To examine the exception-handling clauses in a method, obtain a object and call the method to obtain the method body. Use the property to obtain a list of objects. > [!NOTE] > Working with exception-handling clauses requires a thorough understanding of metadata and Microsoft intermediate language (MSIL) instruction formats. Information can be found in the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/), especially "Partition II: Metadata Definition and Semantics". ## Examples - The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. + The following code example defines a test method named `MethodBodyExample`, and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects and display their properties. This code is part of a larger example provided for the class. - + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ExceptionHandlingClause/Overview/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ExceptionHandlingClause/Overview/source.vb" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ExceptionHandlingClause/Overview/source.cs" id="Snippet4"::: diff --git a/xml/System.Reflection/FieldInfo.xml b/xml/System.Reflection/FieldInfo.xml index 4013c0373a1..cb6f4be5bef 100644 --- a/xml/System.Reflection/FieldInfo.xml +++ b/xml/System.Reflection/FieldInfo.xml @@ -1109,9 +1109,9 @@ Note: In .NET for Win property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. + The actual visibility of a field is limited by the visibility of its type. The property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. - The visibility of a field is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such fields. + The visibility of a field is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such fields. ## Examples The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. @@ -1180,7 +1180,7 @@ Note: In .NET for Win if the only visibility modifier is `protected`. This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such fields. + The visibility of a field is exactly described by if the only visibility modifier is `protected`. This property is `false` for fields that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such fields. ## Examples The following code example defines fields with varying levels of visibility, and displays the values of their , , , and properties. @@ -1324,7 +1324,7 @@ Note: In .NET for Win ## Remarks If a field has level visibility, it can be called from any member in a derived class or any member in the same assembly, but not from any other type. - The actual visibility of a field is limited by the visibility of its type. The property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. + The actual visibility of a field is limited by the visibility of its type. The property might be `true` for a field, but if it is a field of a private nested type then the field is not visible outside the containing type. The visibility of a field is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic). @@ -1606,7 +1606,7 @@ Myfieldb - B readonly field, IsInitOnly = True property value of the field. + The following example creates a class and displays the name, field and property value of the field. :::code language="csharp" source="~/snippets/csharp/System.Reflection/FieldInfo/IsPinvokeImpl/fieldinfo_ispinvokeimpl.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/FieldInfo/IsPinvokeImpl/fieldinfo_ispinvokeimpl.vb" id="Snippet1"::: @@ -2162,7 +2162,7 @@ Myfieldb - B static field; IsStatic - True . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a field. + This property overrides . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a field. diff --git a/xml/System.Reflection/GenericParameterAttributes.xml b/xml/System.Reflection/GenericParameterAttributes.xml index 5faa65871f8..7575bf1765a 100644 --- a/xml/System.Reflection/GenericParameterAttributes.xml +++ b/xml/System.Reflection/GenericParameterAttributes.xml @@ -73,8 +73,8 @@ ## Examples - The following code example defines a generic type `Test` with two type parameters. The second type parameter has a base class constraint and a reference type constraint. When the program executes, the constraints are examined using the property and the method. - + The following code example defines a generic type `Test` with two type parameters. The second type parameter has a base class constraint and a reference type constraint. When the program executes, the constraints are examined using the property and the method. + :::code language="csharp" source="~/snippets/csharp/System/Type/GenericParameterAttributes/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System/Type/GenericParameterAttributes/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/IReflect.xml b/xml/System.Reflection/IReflect.xml index bbe732a2945..a1dc3ff8114 100644 --- a/xml/System.Reflection/IReflect.xml +++ b/xml/System.Reflection/IReflect.xml @@ -856,8 +856,8 @@ On .NET Framework, the interface is used to in ## Examples - The following example obtains the value of the property. - + The following example obtains the value of the property. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/IReflect/InvokeMember/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/IReflect/InvokeMember/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/InvalidFilterCriteriaException.xml b/xml/System.Reflection/InvalidFilterCriteriaException.xml index c7ffbf029e9..d357a49345a 100644 --- a/xml/System.Reflection/InvalidFilterCriteriaException.xml +++ b/xml/System.Reflection/InvalidFilterCriteriaException.xml @@ -207,7 +207,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . @@ -331,7 +331,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Reflection/LocalVariableInfo.xml b/xml/System.Reflection/LocalVariableInfo.xml index 4ee74fdea44..f963255a72e 100644 --- a/xml/System.Reflection/LocalVariableInfo.xml +++ b/xml/System.Reflection/LocalVariableInfo.xml @@ -75,7 +75,7 @@ property. Use the method to obtain the for a object. + To get a list of local variables in a method, use the property. Use the method to obtain the for a object. > [!NOTE] > Local variable names are not persisted in metadata. In Microsoft intermediate language (MSIL), local variables are accessed by their position in the local variable signature. @@ -83,10 +83,10 @@ ## Examples - The following example defines a test method named `MethodBodyExample`, and displays its local variable information. The method is used to obtain a object for the test method. The property is then used to obtain a list of objects and to display their types and index order. + The following example defines a test method named `MethodBodyExample`, and displays its local variable information. The method is used to obtain a object for the test method. The property is then used to obtain a list of objects and to display their types and index order. This code example is part of a larger example provided for the class. - + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ExceptionHandlingClause/Overview/source.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ExceptionHandlingClause/Overview/source.vb" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Reflection/ExceptionHandlingClause/Overview/source.cs" id="Snippet3"::: diff --git a/xml/System.Reflection/MemberInfo.xml b/xml/System.Reflection/MemberInfo.xml index 8bced0a254e..ddf22b8f669 100644 --- a/xml/System.Reflection/MemberInfo.xml +++ b/xml/System.Reflection/MemberInfo.xml @@ -279,16 +279,16 @@ property retrieves a reference to the object for the type that declares this member. A member of a type is either declared by the type or inherited from a base type, so the `Type` object returned by the property might not be the same as the `Type` object used to obtain the current object. + The property retrieves a reference to the object for the type that declares this member. A member of a type is either declared by the type or inherited from a base type, so the `Type` object returned by the property might not be the same as the `Type` object used to obtain the current object. -- If the `Type` object from which this `MemberInfo` object was obtained did not declare this member, the property will represent one of its base types. +- If the `Type` object from which this `MemberInfo` object was obtained did not declare this member, the property will represent one of its base types. - If the `MemberInfo` object is a global member (that is, if it was obtained from the method, which returns global methods on a module), the returned will be `null`. ## Examples - The following example defines an interface, `IValue`, with a single member, `GetValue`. It also defines four classes: `A`, a base class that implements the `IValue` interface; `B`, which inherits from `A` and hides its implementation of `GetValue` from the base class implementation; `C`, which simply inherits from `A`; and `D`, which inherits from `A` and overrides its `GetValue` method. The example then retrieves a object for each member of the type (including members inherited from ) and displays the value of its property. + The following example defines an interface, `IValue`, with a single member, `GetValue`. It also defines four classes: `A`, a base class that implements the `IValue` interface; `B`, which inherits from `A` and hides its implementation of `GetValue` from the base class implementation; `C`, which simply inherits from `A`; and `D`, which inherits from `A` and overrides its `GetValue` method. The example then retrieves a object for each member of the type (including members inherited from ) and displays the value of its property. :::code language="csharp" source="~/snippets/csharp/System.Reflection/MemberInfo/DeclaringType/Example2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/MemberInfo/DeclaringType/Example2.vb" id="Snippet2"::: @@ -871,7 +871,7 @@ For more information, see [How to use and debug assembly unloadability in .NET C objects - for example, the array returned by - the property can be used to determine the member type of any given member. + This property is overridden in derived classes, and the override returns the appropriate member type. Therefore, when you examine a set of objects - for example, the array returned by - the property can be used to determine the member type of any given member. To get the `MemberType` property, get the class . From the `Type`, get the array. From the `MethodInfo` array, get the `MemberTypes`. @@ -992,7 +992,7 @@ For more information, see [How to use and debug assembly unloadability in .NET C property to get the type in which the method is declared, and then calling the property of the resulting object. + This property is provided as a convenience. It is equivalent to using the property to get the type in which the method is declared, and then calling the property of the resulting object. @@ -1062,7 +1062,7 @@ For more information, see [How to use and debug assembly unloadability in .NET C ## Remarks Only the simple name of the member is returned, not the fully qualified name. - To get the property, get the class . From the `Type`, get the array. From a `MemberInfo` element of the array, obtain the `Name` property. + To get the property, get the class . From the `Type`, get the array. From a `MemberInfo` element of the array, obtain the `Name` property. @@ -1240,7 +1240,7 @@ For more information, see [How to use and debug assembly unloadability in .NET C object that was used to obtain this instance of `MemberInfo`. This may differ from the value of the property if this object represents a member that is inherited from a base class. + The `ReflectedType` property retrieves the object that was used to obtain this instance of `MemberInfo`. This may differ from the value of the property if this object represents a member that is inherited from a base class. If the `MemberInfo` object is a global member (that is, if it was obtained from the method, which returns global methods on a module), the returned will be `null`. diff --git a/xml/System.Reflection/MemberTypes.xml b/xml/System.Reflection/MemberTypes.xml index 79933fb223b..1c7027ab0aa 100644 --- a/xml/System.Reflection/MemberTypes.xml +++ b/xml/System.Reflection/MemberTypes.xml @@ -97,7 +97,7 @@ 1. Get a object that represents that type. -2. Retrieve the value of the property. +2. Retrieve the value of the property. To get the values for the members of a type.: @@ -105,7 +105,7 @@ 2. Retrieve the array that represents the members of that type by calling the method. -3. Retrieve the value of the From the property for each member in the array. A `switch` statement in C# or `Select Case` statement in Visual Basic is typically used to process member types. +3. Retrieve the value of the From the property for each member in the array. A `switch` statement in C# or `Select Case` statement in Visual Basic is typically used to process member types. matches CorTypeAttr as defined in the corhdr.h file. @@ -113,7 +113,7 @@ ## Examples The following example displays the names of the members of the class and their associated member types. - + :::code language="csharp" source="~/snippets/csharp/System.Reflection/MemberTypes/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/MemberTypes/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/MethodBase.xml b/xml/System.Reflection/MethodBase.xml index a700c8a0237..4e5f338ae69 100644 --- a/xml/System.Reflection/MethodBase.xml +++ b/xml/System.Reflection/MethodBase.xml @@ -339,13 +339,13 @@ property provides a standard way to distinguish between closed constructed methods, which can be invoked, and open constructed methods, which cannot. If the property returns `true`, the method cannot be invoked. + A generic method can be invoked only if there are no generic type definitions or open constructed types in the type arguments of the method itself or in any enclosing types. Because types can be arbitrarily complex, making this recursive determination is difficult. For convenience, and to reduce the chance of error, the property provides a standard way to distinguish between closed constructed methods, which can be invoked, and open constructed methods, which cannot. If the property returns `true`, the method cannot be invoked. - The property searches recursively for type parameters. For example, it returns `true` for any method in an open type `A` (`A(Of T)` in Visual Basic), even though the method itself is not generic. Contrast this with the behavior of the property, which returns `false` for such a method. + The property searches recursively for type parameters. For example, it returns `true` for any method in an open type `A` (`A(Of T)` in Visual Basic), even though the method itself is not generic. Contrast this with the behavior of the property, which returns `false` for such a method. - Similarly, the property parameter returns `true` for any constructor in an open type, even though constructors cannot have type parameters of their own. + Similarly, the property parameter returns `true` for any constructor in an open type, even though constructors cannot have type parameters of their own. - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. ]]> @@ -544,15 +544,15 @@ ## Remarks The elements of the returned array are in the order in which they appear in the list of type parameters for the generic method. -- If the current method is a closed constructed method (that is, the property returns `false`), the array returned by the method contains the types that have been assigned to the generic type parameters of the generic method definition. +- If the current method is a closed constructed method (that is, the property returns `false`), the array returned by the method contains the types that have been assigned to the generic type parameters of the generic method definition. - If the current method is a generic method definition, the array contains the type parameters. -- If the current method is an open constructed method (that is, the property returns `true`) in which specific types have been assigned to some type parameters and type parameters of enclosing generic types have been assigned to other type parameters, the array contains both types and type parameters. Use the property to tell them apart. For a demonstration of this scenario, see the code example provided for the property. +- If the current method is an open constructed method (that is, the property returns `true`) in which specific types have been assigned to some type parameters and type parameters of enclosing generic types have been assigned to other type parameters, the array contains both types and type parameters. Use the property to tell them apart. For a demonstration of this scenario, see the code example provided for the property. Generic constructors are not supported in the .NET Framework version 2.0. This property throws if not overridden in a derived class, so an exception is thrown if the current instance is of type . - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. ]]> @@ -677,7 +677,7 @@ ## Examples The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. - The property is used to obtain a list of objects and display their types and index order. The property is used to obtain a list of exception-handling clauses. + The property is used to obtain a list of objects and display their types and index order. The property is used to obtain a list of exception-handling clauses. > [!NOTE] > Not all computer languages can generate clauses. The Visual Basic example shows a filter clause, using a Visual Basic `When` expression, which is omitted from the examples for other languages. @@ -1380,9 +1380,9 @@ This method dynamically invokes the method reflected by this instance on `obj`, property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. + The actual visibility of a method is limited by the visibility of its type. The property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. - The visibility of a method or constructor is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such methods. + The visibility of a method or constructor is exactly described by if the only visibility modifier is `internal` (`Friend` in Visual Basic). This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such methods. ## Examples The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. @@ -1498,7 +1498,7 @@ This method dynamically invokes the method reflected by this instance on `obj`, ## Remarks > [!NOTE] -> The property returns `false` for a object in a dynamic type, unless the flag was included in the `attributes` parameter when the constructor was defined. Omitting the flag does not affect the correctness of the emitted constructor. +> The property returns `false` for a object in a dynamic type, unless the flag was included in the `attributes` parameter when the constructor was defined. Omitting the flag does not affect the correctness of the emitted constructor. ]]> @@ -1558,7 +1558,7 @@ This method dynamically invokes the method reflected by this instance on `obj`, if the only visibility modifier is `protected`. This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such methods. + The visibility of a method or constructor is exactly described by if the only visibility modifier is `protected`. This property is `false` for methods that are `protected internal` in C# (`Protected Friend` in Visual Basic); use the property to identify such methods. ## Examples The following code example defines methods with varying levels of visibility, and displays the values of their , , , and properties. @@ -1698,7 +1698,7 @@ This method dynamically invokes the method reflected by this instance on `obj`, ## Remarks If a type member has visibility, it can be called from any member in a derived class or any member in the same assembly, but not from any other type. - The actual visibility of a method is limited by the visibility of its type. The property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. + The actual visibility of a method is limited by the visibility of its type. The property might be `true` for a method, but if it is a method of a private nested type then the method is not visible outside the containing type. The visibility of a method or constructor is exactly described by if the visibility modifier is `protected internal` in C# (`Protected Friend` in Visual Basic). @@ -1772,7 +1772,7 @@ This method dynamically invokes the method reflected by this instance on `obj`, If the virtual method is marked `final`, it can't be overridden in derived classes. The overridden virtual method can be marked `final` using the [sealed](/dotnet/csharp/language-reference/keywords/sealed) keyword in C# or [NotOverridable](/dotnet/visual-basic/language-reference/modifiers/notoverridable) keyword in Visual Basic. The method can also be marked `final` implicitly by the compiler. For example, a method might be defined as non-virtual in your code, but it implements an interface method. The Common Language Runtime requires that all methods that implement interface members must be marked as `virtual`; therefore, the compiler marks the method `virtual final`. -You can use this property, in conjunction with the property, to determine if a method is overridable. For a method to be overridable, property must be `true` and `IsFinal` property must be `false`. To establish with certainty whether a method is overridable, use code such as this: +You can use this property, in conjunction with the property, to determine if a method is overridable. For a method to be overridable, property must be `true` and `IsFinal` property must be `false`. To establish with certainty whether a method is overridable, use code such as this: ```csharp if (MethodInfo.IsVirtual && !MethodInfo.IsFinal) @@ -1844,12 +1844,12 @@ If `IsVirtual` is `false` or `IsFinal` is `true`, then the method cannot be over property to determine whether the current object represents a generic method. Use the property to determine whether the current object represents an open constructed method or a closed constructed method. + Use the property to determine whether the current object represents a generic method. Use the property to determine whether the current object represents an open constructed method or a closed constructed method. > [!NOTE] > Generics are not supported by default; this property returns `false` if not overridden in a derived class. Generic constructors are not supported in the .NET Framework version 2.0, so this property returns `false` if the current instance is of type . -The following table summarizes the invariant conditions for terms specific to generic methods. For other terms used in generic reflection, such as *generic type parameter* and *generic type*, see the property. +The following table summarizes the invariant conditions for terms specific to generic methods. For other terms used in generic reflection, such as *generic type parameter* and *generic type*, see the property. |Term|Invariant condition| |---|---| @@ -1917,20 +1917,20 @@ The following table summarizes the invariant conditions for terms specific to ge ## Remarks If the current represents a generic method definition, then: -- The property is `true`. +- The property is `true`. - For each object in the array returned by the method: - - The property is `true`. + - The property is `true`. - - The property returns the current instance. + - The property returns the current instance. - - The property is the same as the position of the object in the array. + - The property is the same as the position of the object in the array. > [!NOTE] > Generics are not supported by default; this property returns `false` if not overridden in a derived class. Generic constructors are not supported in the .NET Framework version 2.0, so this property returns `false` if the current instance is of type . - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. ]]> @@ -1993,12 +1993,12 @@ The following table summarizes the invariant conditions for terms specific to ge When a member in a derived class is declared with the C# `new` modifier or the Visual Basic `Shadows` modifier, it can hide a member of the same name in the base class. C# hides base class members by signature. That is, if the base class member has multiple overloads, the only one that is hidden is the one that has the identical signature. By contrast, Visual Basic hides all the base class overloads. Thus, returns `false` on a member declared with the Visual Basic `Shadows` modifier, and `true` on a member declared with the C# `new` modifier. > [!WARNING] -> This property does not determine whether a method has the attribute. A method that is declared with either the `new` or the `Shadows` modifier will have the attribute, but only methods declared with `new` (that is, only C# methods) will have the property set to `true`. To determine whether a method has the attribute, use code similar to the following: `if ((myMethodInfo.Attributes & MethodAttributes.VtableLayoutMask) == MethodAttributes.NewSlot)` in C# or `If (myMethodInfo.Attributes And MethodAttributes.VtableLayoutMask) = MethodAttributes.NewSlot` in Visual Basic. Note, however, that although all methods declared with `new` or `Shadows` have the attribute, not all methods that have the attribute are declared with `new` or `Shadows`. +> This property does not determine whether a method has the attribute. A method that is declared with either the `new` or the `Shadows` modifier will have the attribute, but only methods declared with `new` (that is, only C# methods) will have the property set to `true`. To determine whether a method has the attribute, use code similar to the following: `if ((myMethodInfo.Attributes & MethodAttributes.VtableLayoutMask) == MethodAttributes.NewSlot)` in C# or `If (myMethodInfo.Attributes And MethodAttributes.VtableLayoutMask) = MethodAttributes.NewSlot` in Visual Basic. Note, however, that although all methods declared with `new` or `Shadows` have the attribute, not all methods that have the attribute are declared with `new` or `Shadows`. ## Examples - The following code example contains a base class with an overloaded method, and a derived class that hides one of the overloads. In the Visual Basic version of the code example, the property returns `false` for the member in the derived class. In the C# version of the code sample, the property returns `true` for the member in the derived class. + The following code example contains a base class with an overloaded method, and a derived class that hides one of the overloads. In the Visual Basic version of the code example, the property returns `false` for the member in the derived class. In the C# version of the code sample, the property returns `true` for the member in the derived class. :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsHideBySig/hide.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/MethodBase/IsHideBySig/hide.vb" id="Snippet1"::: @@ -2125,7 +2125,7 @@ The following table summarizes the invariant conditions for terms specific to ge ## Examples - The following example uses the property to display a message that indicates whether the specified method is public. + The following example uses the property to display a message that indicates whether the specified method is public. :::code language="csharp" source="~/snippets/csharp/System.Reflection/MethodBase/IsPublic/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/MethodBase/IsPublic/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/MethodBody.xml b/xml/System.Reflection/MethodBody.xml index 226c1152e24..090aca7d5d1 100644 --- a/xml/System.Reflection/MethodBody.xml +++ b/xml/System.Reflection/MethodBody.xml @@ -76,9 +76,9 @@ ## Examples The following code example defines a test method named `MethodBodyExample` and displays its local variable information and exception-handling clauses. The method is used to obtain a object for the test method. - The example uses the property to obtain a list of objects and then displays their types and index order. The property is used to obtain a list of exception-handling clauses. + The example uses the property to obtain a list of objects and then displays their types and index order. The property is used to obtain a list of exception-handling clauses. + - :::code language="csharp" source="~/snippets/csharp/System.Reflection/ExceptionHandlingClause/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ExceptionHandlingClause/Overview/source.vb" id="Snippet1"::: @@ -180,7 +180,7 @@ > Working with exception-handling clauses requires a thorough understanding of metadata and MSIL instruction formats. Information can be found in the [Common Language Infrastructure (CLI) documentation](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/), especially "Partition II: Metadata Definition and Semantics". ## Examples - The following code example defines a test method named `MethodBodyExample` and displays information about its exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects. + The following code example defines a test method named `MethodBodyExample` and displays information about its exception-handling clauses. The method is used to obtain a object for the test method. The property is used to obtain a list of objects. This code example is part of a larger example provided for the class. @@ -306,7 +306,7 @@ property refers to variables that are not explicitly initialized; that is, variables that are declared with syntax such as `int x;` in C# or `Dim x As Integer` in Visual Basic. + The property refers to variables that are not explicitly initialized; that is, variables that are declared with syntax such as `int x;` in C# or `Dim x As Integer` in Visual Basic. Reference variables are initialized to `null` by default. Numeric variables are initialized to zero. @@ -371,7 +371,7 @@ property to obtain information about the method's local variables. + Use the property to obtain information about the method's local variables. > [!NOTE] > Information about local variable signatures 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/). @@ -425,12 +425,12 @@ property. + You do not need the metadata token for the local variable signature provided by the property. ## Examples - The following code example defines a test method named `MethodBodyExample` and displays its local variable information. The method is used to obtain a object for the test method. The property is used to obtain a list of objects. + The following code example defines a test method named `MethodBodyExample` and displays its local variable information. The method is used to obtain a object for the test method. The property is used to obtain a list of objects. This code example is part of a larger example provided for the class. diff --git a/xml/System.Reflection/MethodInfo.xml b/xml/System.Reflection/MethodInfo.xml index edcabb6e2c3..652d497bbc9 100644 --- a/xml/System.Reflection/MethodInfo.xml +++ b/xml/System.Reflection/MethodInfo.xml @@ -101,7 +101,7 @@ - You can determine the method's visibility by retrieving the values of the , , , and properties. -- You can discover what attributes are applied to the method by retrieving the value of the property or calling the method. +- You can discover what attributes are applied to the method by retrieving the value of the property or calling the method. - You can determine whether the method is a generic method, an open constructed generic method, or a closed constructed generic method, by retrieving the values of the and properties. @@ -113,7 +113,7 @@ You can instantiate a instances by calling the or method, or by calling the method of a object that represents a generic method definition. - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. ]]> @@ -554,7 +554,7 @@ For a list of the invariant conditions for other terms used in generic reflectio method returns the first definition of the specified method in the class hierarchy. You can determine the type on which the first definition of the method is found by retrieving the value of the property on the returned object. + The method returns the first definition of the specified method in the class hierarchy. You can determine the type on which the first definition of the method is found by retrieving the value of the property on the returned object. The method behaves as follows: @@ -651,13 +651,13 @@ For a list of the invariant conditions for other terms used in generic reflectio ## Remarks The elements of the returned array are in the order in which they appear in the list of type parameters for the generic method. -- If the current method is a closed constructed method (that is, the property returns `false`), the array returned by the method contains the types that have been assigned to the generic type parameters of the generic method definition. +- If the current method is a closed constructed method (that is, the property returns `false`), the array returned by the method contains the types that have been assigned to the generic type parameters of the generic method definition. - If the current method is a generic method definition, the array contains the type parameters. -- If the current method is an open constructed method (that is, the property returns `true`) in which specific types have been assigned to some type parameters and type parameters of enclosing generic types have been assigned to other type parameters, the array contains both types and type parameters. Use the property to tell them apart. For a demonstration of this scenario, see the code example for the property. +- If the current method is an open constructed method (that is, the property returns `true`) in which specific types have been assigned to some type parameters and type parameters of enclosing generic types have been assigned to other type parameters, the array contains both types and type parameters. Use the property to tell them apart. For a demonstration of this scenario, see the code example for the property. - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. ## Examples The following code example shows how to get the type arguments of a generic method and display them. @@ -756,9 +756,9 @@ Class C(Of T) End Class ``` - In the constructed type `C` (`C(Of Integer)` in Visual Basic), the generic method `M` returns `B`. In the open type `C`, `M` returns `B`. In both cases, the property returns `true` for the that represents `M`, so can be called on both objects. In the case of the constructed type, the result of calling is a that can be invoked. In the case of the open type, the returned by cannot be invoked. + In the constructed type `C` (`C(Of Integer)` in Visual Basic), the generic method `M` returns `B`. In the open type `C`, `M` returns `B`. In both cases, the property returns `true` for the that represents `M`, so can be called on both objects. In the case of the constructed type, the result of calling is a that can be invoked. In the case of the open type, the returned by cannot be invoked. - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. @@ -1157,7 +1157,7 @@ Console::WriteLine("\tIs this a generic method definition? {0}", method allows you to write code that assigns specific types to the type parameters of a generic method definition, thus creating a object that represents a particular constructed method. If the property of this object returns `true`, you can use it to invoke the method or to create a delegate to invoke the method. + The method allows you to write code that assigns specific types to the type parameters of a generic method definition, thus creating a object that represents a particular constructed method. If the property of this object returns `true`, you can use it to invoke the method or to create a delegate to invoke the method. Methods constructed with the method can be open, that is, some of their type arguments can be type parameters of enclosing generic types. You might use such open constructed methods when you generate dynamic assemblies. For example, consider the following code. @@ -1183,9 +1183,9 @@ Class C End Class ``` - The method body of `M` contains a call to method `N`, specifying the type parameter of `M` and the type . The property returns `false` for method `N`. The property returns `true`, so method `N` cannot be invoked. + The method body of `M` contains a call to method `N`, specifying the type parameter of `M` and the type . The property returns `false` for method `N`. The property returns `true`, so method `N` cannot be invoked. - For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. + For a list of the invariant conditions for terms specific to generic methods, see the property. For a list of the invariant conditions for other terms used in generic reflection, see the property. @@ -1273,7 +1273,7 @@ End Class . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a method. + This property overrides . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a method. To get the `MemberType` property, first get the class `Type`. From the `Type`, get the `MethodInfo`. From the `MethodInfo`, get the `MemberType`. diff --git a/xml/System.Reflection/Module.xml b/xml/System.Reflection/Module.xml index b9071f76ffb..0e763ff51a9 100644 --- a/xml/System.Reflection/Module.xml +++ b/xml/System.Reflection/Module.xml @@ -2487,7 +2487,7 @@ property is referred to as the `mvid`, and is stored in the GUID heap. + In unmanaged metadata, the GUID returned by the property is referred to as the `mvid`, and is stored in the GUID heap. > [!NOTE] > More information about metadata 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/). diff --git a/xml/System.Reflection/ObfuscateAssemblyAttribute.xml b/xml/System.Reflection/ObfuscateAssemblyAttribute.xml index 05abab4543b..aa8c6089200 100644 --- a/xml/System.Reflection/ObfuscateAssemblyAttribute.xml +++ b/xml/System.Reflection/ObfuscateAssemblyAttribute.xml @@ -55,28 +55,28 @@ Instructs obfuscation tools to use their standard obfuscation rules for the appropriate assembly type. - and attributes provide a way for assembly authors to annotate their binaries so that obfuscation tools can process them correctly with minimal external configuration. - - Applying this attribute to an assembly tells the obfuscation tool to use its default rules for the assembly type. - + and attributes provide a way for assembly authors to annotate their binaries so that obfuscation tools can process them correctly with minimal external configuration. + + Applying this attribute to an assembly tells the obfuscation tool to use its default rules for the assembly type. + > [!IMPORTANT] -> Applying this attribute does not automatically obfuscate the assembly. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. - - You can apply to types within an assembly, and to members on those types. The innermost attribute controls the way an obfuscation tool treats any particular code entity. - - - -## Examples - The following code example shows a private assembly that has been marked with the . The property is `false`, to prevent the obfuscation tool from stripping the attribute after processing. - - For a code example that shows the use of with , see the class. - +> Applying this attribute does not automatically obfuscate the assembly. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. + + You can apply to types within an assembly, and to members on those types. The innermost attribute controls the way an obfuscation tool treats any particular code entity. + + + +## Examples + The following code example shows a private assembly that has been marked with the . The property is `false`, to prevent the obfuscation tool from stripping the attribute after processing. + + For a code example that shows the use of with , see the class. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.vb" id="Snippet1"::: + ]]> @@ -122,22 +122,22 @@ if the assembly is used within the scope of one application; otherwise, . Initializes a new instance of the class, specifying whether the assembly to be obfuscated is public or private. - [!IMPORTANT] -> Applying this attribute does not automatically obfuscate the assembly. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. - - - -## Examples - The following code example shows how the attribute constructor specifies that an assembly is private. The property is `false`, to prevent the obfuscation tool from stripping the attribute after processing. - +> Applying this attribute does not automatically obfuscate the assembly. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. + + + +## Examples + The following code example shows how the attribute constructor specifies that an assembly is private. The property is `false`, to prevent the obfuscation tool from stripping the attribute after processing. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.vb" id="Snippet1"::: + ]]> @@ -182,22 +182,22 @@ if the assembly was marked private; otherwise, . - [!IMPORTANT] -> Applying this attribute does not automatically obfuscate the assembly. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. - - - -## Examples - The following code example shows how the attribute constructor sets the property to `true`, to specify that an assembly is private. The property is `false`, to prevent the obfuscation tool from stripping the attribute after processing. - +> Applying this attribute does not automatically obfuscate the assembly. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. + + + +## Examples + The following code example shows how the attribute constructor sets the property to `true`, to specify that an assembly is private. The property is `false`, to prevent the obfuscation tool from stripping the attribute after processing. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.vb" id="Snippet1"::: + ]]> @@ -242,24 +242,24 @@ if the obfuscation tool should remove the attribute after processing; otherwise, . The default value for this property is . - does not affect instances of that have been applied to types and members within the assembly. - + does not affect instances of that have been applied to types and members within the assembly. + > [!IMPORTANT] -> Applying this attribute does not automatically obfuscate the assembly. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. - - - -## Examples - The following code example shows the attribute with the property set to `false`, to prevent the obfuscation tool from stripping the attribute after processing. - +> Applying this attribute does not automatically obfuscate the assembly. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. + + + +## Examples + The following code example shows the attribute with the property set to `false`, to prevent the obfuscation tool from stripping the attribute after processing. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscateAssemblyAttribute/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Reflection/ObfuscationAttribute.xml b/xml/System.Reflection/ObfuscationAttribute.xml index f7e7af35747..43d8866ffb5 100644 --- a/xml/System.Reflection/ObfuscationAttribute.xml +++ b/xml/System.Reflection/ObfuscationAttribute.xml @@ -59,38 +59,38 @@ Instructs obfuscation tools to take the specified actions for an assembly, type, or member. - and attributes allow assembly authors to annotate their binaries so that obfuscation tools can process them correctly with minimal external configuration. - + and attributes allow assembly authors to annotate their binaries so that obfuscation tools can process them correctly with minimal external configuration. + > [!IMPORTANT] -> Applying this attribute does not automatically obfuscate the code entity to which you apply it. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. - - The attribute has a string property. Obfuscation tools can map the string values of this property to features they implement, preferably by using an XML configuration file that users can access. The defines two feature strings, "default" and "all". The string "default" should map to the default obfuscation features of a tool, and "all" should map to the complete set of obfuscation features supported by a tool. The default value of the property is "all", enabling the complete set of obfuscation features. - - When applied to an assembly, also applies to all types within the assembly. If the property is not specified, or is set to `true`, the attribute applies to all members as well. does not specify whether an assembly is public or private. To specify whether an assembly is public or private, use the attribute. - - When applied to classes and structures, also applies to all members of the type if the property is not specified, or is set to `true`. - - When applied to methods, parameters, fields, and properties, the attribute affects only the entity to which it is applied. - - - -## Examples - The following code example shows a public assembly with two types: `Type1` and `Type2`. The assembly is marked for obfuscation with the , which marks the assembly to be treated as public (that is, the property is `false`). - - `Type1` is marked for obfuscation because the assembly is marked for obfuscation. One member of `Type1` is excluded from obfuscation, using the property. - - `Type2` is excluded from obfuscation, but its members are marked for obfuscation because the property is `false`. - - The `MethodA` method of `Type2` is marked with the value `"default"` for the property. It is necessary to specify `false` for the property to avoid excluding `MethodA` from obfuscation, because the default for the property is `true`. The obfuscation tool should not strip the attribute after obfuscation because the property is `false`. All the other attributes in this code example are stripped after obfuscation, because the property is not specified, and therefore defaults to `true`. - - The code example includes code to display the attributes and their properties. You can also examine the attributes by opening the DLL with the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler). - +> Applying this attribute does not automatically obfuscate the code entity to which you apply it. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. + + The attribute has a string property. Obfuscation tools can map the string values of this property to features they implement, preferably by using an XML configuration file that users can access. The defines two feature strings, "default" and "all". The string "default" should map to the default obfuscation features of a tool, and "all" should map to the complete set of obfuscation features supported by a tool. The default value of the property is "all", enabling the complete set of obfuscation features. + + When applied to an assembly, also applies to all types within the assembly. If the property is not specified, or is set to `true`, the attribute applies to all members as well. does not specify whether an assembly is public or private. To specify whether an assembly is public or private, use the attribute. + + When applied to classes and structures, also applies to all members of the type if the property is not specified, or is set to `true`. + + When applied to methods, parameters, fields, and properties, the attribute affects only the entity to which it is applied. + + + +## Examples + The following code example shows a public assembly with two types: `Type1` and `Type2`. The assembly is marked for obfuscation with the , which marks the assembly to be treated as public (that is, the property is `false`). + + `Type1` is marked for obfuscation because the assembly is marked for obfuscation. One member of `Type1` is excluded from obfuscation, using the property. + + `Type2` is excluded from obfuscation, but its members are marked for obfuscation because the property is `false`. + + The `MethodA` method of `Type2` is marked with the value `"default"` for the property. It is necessary to specify `false` for the property to avoid excluding `MethodA` from obfuscation, because the default for the property is `true`. The obfuscation tool should not strip the attribute after obfuscation because the property is `false`. All the other attributes in this code example are stripped after obfuscation, because the property is not specified, and therefore defaults to `true`. + + The code example includes code to display the attributes and their properties. You can also examine the attributes by opening the DLL with the [Ildasm.exe (IL Disassembler)](/dotnet/framework/tools/ildasm-exe-il-disassembler). + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ObfuscationAttribute/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscationAttribute/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscationAttribute/Overview/source.vb" id="Snippet1"::: + ]]> @@ -131,11 +131,11 @@ Initializes a new instance of the class. - does not specify whether an assembly is public or private. To specify whether an assembly is public or private, use . - + does not specify whether an assembly is public or private. To specify whether an assembly is public or private, use . + ]]> @@ -180,24 +180,24 @@ if the attribute is to apply to the members of the type; otherwise, . The default is . - [!IMPORTANT] -> Applying this attribute does not automatically obfuscate the code entity to which you apply it. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. - - - -## Examples - The following code example shows a type that is excluded from obfuscation, but the exclusion does not apply to its members because the property is `false`. - - This code is part of a larger example that can be compiled and executed. See the class. - +> Applying this attribute does not automatically obfuscate the code entity to which you apply it. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. + + + +## Examples + The following code example shows a type that is excluded from obfuscation, but the exclusion does not apply to its members because the property is `false`. + + This code is part of a larger example that can be compiled and executed. See the class. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ObfuscationAttribute/Overview/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscationAttribute/Overview/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscationAttribute/Overview/source.vb" id="Snippet2"::: + ]]> @@ -242,25 +242,25 @@ if the type or member to which this attribute is applied should be excluded from obfuscation; otherwise, . The default is . - [!IMPORTANT] -> Applying this attribute does not automatically obfuscate the code entity to which you apply it. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. - - - -## Examples - The following code example shows a type that is marked to be excluded from obfuscation. It is not necessary to specify the property, because it defaults to `true`, but specifying it explicitly makes your intent clear. The is set to `false`, so that the exclusion from obfuscation does not apply to the members of the class. That is, the class name is visible but the members are obfuscated. - - The `MethodA` method is marked with the value `"default"` for the property. It is necessary to specify `false` for the property in order to avoid excluding `MethodA` from obfuscation, because the default for the property is `true`. The property is `false` so that the obfuscation tool will not strip the attribute after obfuscation. - - This code is part of a larger example that can be compiled and executed. See the class. - +> Applying this attribute does not automatically obfuscate the code entity to which you apply it. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. + + + +## Examples + The following code example shows a type that is marked to be excluded from obfuscation. It is not necessary to specify the property, because it defaults to `true`, but specifying it explicitly makes your intent clear. The is set to `false`, so that the exclusion from obfuscation does not apply to the members of the class. That is, the class name is visible but the members are obfuscated. + + The `MethodA` method is marked with the value `"default"` for the property. It is necessary to specify `false` for the property in order to avoid excluding `MethodA` from obfuscation, because the default for the property is `true`. The property is `false` so that the obfuscation tool will not strip the attribute after obfuscation. + + This code is part of a larger example that can be compiled and executed. See the class. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ObfuscationAttribute/Overview/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscationAttribute/Overview/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscationAttribute/Overview/source.vb" id="Snippet4"::: + ]]> @@ -305,24 +305,24 @@ Gets or sets a string value that is recognized by the obfuscation tool, and which specifies processing options. A string value that is recognized by the obfuscation tool, and which specifies processing options. The default is "all". - [!IMPORTANT] -> Applying this attribute does not automatically obfuscate the code entity to which you apply it. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. - - - -## Examples - The following code example shows a method that is marked with the value `"default"` for the property. It is necessary to specify `false` for the property to avoid excluding `MethodA` from obfuscation, because the default for the property is `true`. The property is `false` so that the obfuscation tool will not strip the attribute after obfuscation. - - This code is part of a larger example that can be compiled and executed. See the class. - +> Applying this attribute does not automatically obfuscate the code entity to which you apply it. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. + + + +## Examples + The following code example shows a method that is marked with the value `"default"` for the property. It is necessary to specify `false` for the property to avoid excluding `MethodA` from obfuscation, because the default for the property is `true`. The property is `false` so that the obfuscation tool will not strip the attribute after obfuscation. + + This code is part of a larger example that can be compiled and executed. See the class. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ObfuscationAttribute/Overview/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscationAttribute/Overview/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscationAttribute/Overview/source.vb" id="Snippet3"::: + ]]> @@ -367,24 +367,24 @@ if an obfuscation tool should remove the attribute after processing; otherwise, . The default is . - [!IMPORTANT] -> Applying this attribute does not automatically obfuscate the code entity to which you apply it. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. - - - -## Examples - The following code example shows an whose property is `false` so that the obfuscation tool will not strip the attribute after obfuscation. It is necessary to specify `false` for the property to avoid excluding `MethodA` from obfuscation, because the default for the property is `true`. - - This code is part of a larger example that can be compiled and executed. See the class. - +> Applying this attribute does not automatically obfuscate the code entity to which you apply it. Applying the attribute is an alternative to creating a configuration file for the obfuscation tool. That is, it merely provides instructions for an obfuscation tool. Microsoft recommends that vendors of obfuscation tools follow the semantics described here. However, there is no guarantee that a particular tool follows Microsoft recommendations. + + + +## Examples + The following code example shows an whose property is `false` so that the obfuscation tool will not strip the attribute after obfuscation. It is necessary to specify `false` for the property to avoid excluding `MethodA` from obfuscation, because the default for the property is `true`. + + This code is part of a larger example that can be compiled and executed. See the class. + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ObfuscationAttribute/Overview/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscationAttribute/Overview/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ObfuscationAttribute/Overview/source.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.Reflection/ParameterInfo.xml b/xml/System.Reflection/ParameterInfo.xml index fe655b34cda..da19f064c24 100644 --- a/xml/System.Reflection/ParameterInfo.xml +++ b/xml/System.Reflection/ParameterInfo.xml @@ -232,7 +232,7 @@ To get the array, first get the method or ## Examples -The following example defines a method with three parameters. It uses the property to get the attributes of each parameter and display them in the console. +The following example defines a method with three parameters. It uses the property to get the attributes of each parameter and display them in the console. :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/Attributes/parameterinfo_attributes1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ParameterInfo/Attributes/parameterinfo_attributes1.vb" id="Snippet1"::: @@ -457,7 +457,7 @@ The following example defines a method with three parameters. It uses the property instead. + This property is used only in the execution context. In the reflection-only context, use the property instead. The default value is used when an actual value is not specified in the method call. A parameter can have a default value that is `null`. This is distinct from the case where a default value is not defined. @@ -1575,7 +1575,7 @@ The following example defines a method with three parameters. It uses the property of the member that defines this parameter. + To get the module, use the property of the member that defines this parameter. The tokens obtained using this property can be passed to the unmanaged Reflection API. For more information, please see [Unmanaged Reflection API](https://msdn.microsoft.com/library/0c5bb9de-0cf6-438d-ba47-134e6c775fb8). @@ -1644,12 +1644,12 @@ The following example defines a method with three parameters. It uses the array, first get the method or the constructor and then call the method. > [!WARNING] -> If this represents a return value (that is, if it was obtained by using the property), this property will be `null`. +> If this represents a return value (that is, if it was obtained by using the property), this property will be `null`. ## Examples - The following example shows how to get objects for the parameters of a method, and then use the property to obtain the parameter names. + The following example shows how to get objects for the parameters of a method, and then use the property to obtain the parameter names. :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/Name/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ParameterInfo/Name/source.vb" id="Snippet1"::: @@ -1774,7 +1774,7 @@ The following example defines a method with three parameters. It uses the objects for the parameters of a method, and then use the property to display the type of each parameter. + The following example shows how to get objects for the parameters of a method, and then use the property to display the type of each parameter. :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterInfo/ParameterType/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ParameterInfo/ParameterType/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/ParameterModifier.xml b/xml/System.Reflection/ParameterModifier.xml index c36eadc72ab..8a6916a7298 100644 --- a/xml/System.Reflection/ParameterModifier.xml +++ b/xml/System.Reflection/ParameterModifier.xml @@ -79,13 +79,13 @@ structure is used with the method overload when passing parameters by reference to a COM component that is accessed late bound. The parameters that are to be passed by reference are specified by a single structure, which must be passed in an array containing a single element. The single structure in this array must be initialized with the number of parameters in the member that is to be invoked. To indicate which of these parameters are passed by reference, set the value of the property (the indexer in C#) to `true` for the index number corresponding to the zero-based position of the parameter. + The structure is used with the method overload when passing parameters by reference to a COM component that is accessed late bound. The parameters that are to be passed by reference are specified by a single structure, which must be passed in an array containing a single element. The single structure in this array must be initialized with the number of parameters in the member that is to be invoked. To indicate which of these parameters are passed by reference, set the value of the property (the indexer in C#) to `true` for the index number corresponding to the zero-based position of the parameter. ## Examples The following code example shows this for a member that has three string arguments, the first and third of which are passed by reference. Assume that a variable named `obj` contains a reference to the COM object. - + :::code language="csharp" source="~/snippets/csharp/System.Reflection/ParameterModifier/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/ParameterModifier/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Reflection/PropertyInfo.xml b/xml/System.Reflection/PropertyInfo.xml index 275dda46449..630bd2e92f4 100644 --- a/xml/System.Reflection/PropertyInfo.xml +++ b/xml/System.Reflection/PropertyInfo.xml @@ -100,7 +100,7 @@ Properties are logically the same as fields. A property is a named aspect of an object's state whose value is typically accessible through `get` and `set` accessors. Properties may be read-only, in which case a set routine is not supported. > [!NOTE] -> To determine whether a property is `static`, you must obtain the for the `get` or `set` accessor, by calling the or the method, and examine its property. +> To determine whether a property is `static`, you must obtain the for the `get` or `set` accessor, by calling the or the method, and examine its property. Several methods in this class assume that the `get` accessor and `set` accessor methods of a property have certain formats. The signatures of the `get` and `set` methods must match the following convention: @@ -224,18 +224,18 @@ property returns the attributes associated with the property represented by this object. The attributes are primarily modifiers applied by a compiler when creating a property; they indicate whether a property is the default property, a `SpecialName` property, and so on. Note that, for almost all properties found in types in the .NET Framework class library, the value of the property is . + The property returns the attributes associated with the property represented by this object. The attributes are primarily modifiers applied by a compiler when creating a property; they indicate whether a property is the default property, a `SpecialName` property, and so on. Note that, for almost all properties found in types in the .NET Framework class library, the value of the property is . > [!TIP] -> In most cases, you probably want to retrieve the custom attributes associated with a property. To do this, retrieve the value of the property, or call one of the overloads of the method. +> In most cases, you probably want to retrieve the custom attributes associated with a property. To do this, retrieve the value of the property, or call one of the overloads of the method. - To get the property: + To get the property: 1. Get a object that represents the type to which the property belongs. 2. Get the object by calling an overload of the method. -3. Retrieve the property's attributes from the property. +3. Retrieve the property's attributes from the property. You can define the attributes of a property for a type created dynamically using reflection emit by calling an overload of the method and supplying a value for the `attributes` argument. @@ -369,13 +369,13 @@ ## Remarks returns `true` if the property has a `set` accessor, even if the accessor is `private`, `internal` (or `Friend` in Visual Basic), or `protected`. If the property does not have a `set` accessor, the method returns `false`. - To get the value of the property: + To get the value of the property: 1. Get the object of the type that includes the property. 2. Call the to get the object that represents the property. -3. Retrieve the value of the property. +3. Retrieve the value of the property. @@ -1545,7 +1545,7 @@ Console.WriteLine("CurrCult: " + > This method can be used to access non-public members if the caller has been granted with the flag and if the grant set of the non-public members is restricted to the caller's grant set, or a subset thereof. (See [Security Considerations for Reflection](/dotnet/framework/reflection-and-codedom/security-considerations-for-reflection).) To use this functionality, your application should target .NET Framework 3.5 or later. ## Examples - The following example shows how to get the value of an indexed property. The property is the default property (the indexer in C#) of the class. + The following example shows how to get the value of an indexed property. The property is the default property (the indexer in C#) of the class. :::code language="csharp" source="~/snippets/csharp/System.Reflection/PropertyInfo/GetValue/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Reflection/PropertyInfo/GetValue/source.vb" id="Snippet1"::: @@ -1772,7 +1772,7 @@ Console.WriteLine("CurrCult: " + . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a property. + This property overrides . Therefore, when you examine a set of objects - for example, the array returned by - the property returns only when a given member is a property. `MemberType` is a derived class of `MemberInfo` and specifies the type of member this is. Member types are constructors, properties, fields, and methods. Since this is a `PropertyInfo` property, the returned type is a property. @@ -1962,7 +1962,7 @@ Console.WriteLine("CurrCult: " + 2. Get a object that represents the property in which you're interested. You can do this by getting an array of all properties from the method and then iterating the elements in the array, or you can retrieve the object that represents the property directly by calling the method and specifying the property name. -3. Retrieve the value of the property from the object. +3. Retrieve the value of the property from the object. @@ -2024,7 +2024,7 @@ Console.WriteLine("CurrCult: " + property is equivalent to calling the method with a value of `true` for the `nonPublic` argument. + Retrieving the value of the property is equivalent to calling the method with a value of `true` for the `nonPublic` argument. ]]> diff --git a/xml/System.Reflection/ReflectionTypeLoadException.xml b/xml/System.Reflection/ReflectionTypeLoadException.xml index 2ef79016d56..4547ebe7f17 100644 --- a/xml/System.Reflection/ReflectionTypeLoadException.xml +++ b/xml/System.Reflection/ReflectionTypeLoadException.xml @@ -346,7 +346,7 @@ property retrieves an array of type `Exception` that is parallel to the array. This array will contain null values whenever reflection cannot load a class. + The property retrieves an array of type `Exception` that is parallel to the array. This array will contain null values whenever reflection cannot load a class. ]]> @@ -486,7 +486,7 @@ property retrieves an array of type `Exception` that is parallel to this `Types` array. This array will contain null values whenever reflection cannot load a class. + The property retrieves an array of type `Exception` that is parallel to this `Types` array. This array will contain null values whenever reflection cannot load a class. ]]> diff --git a/xml/System.Reflection/TargetException.xml b/xml/System.Reflection/TargetException.xml index a26ef0d23f4..6160d3ab042 100644 --- a/xml/System.Reflection/TargetException.xml +++ b/xml/System.Reflection/TargetException.xml @@ -81,14 +81,14 @@ Represents the exception that is thrown when an attempt is made to invoke an invalid target. - [!NOTE] -> This exception is not included in the [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. - +> This exception is not included in the [.NET for Windows Store apps](https://go.microsoft.com/fwlink/?LinkID=247912) or the [Portable Class Library](/dotnet/standard/cross-platform/cross-platform-development-with-the-portable-class-library), but it is thrown by some members that are. To catch the exception in that case, write a `catch` statement for instead. + ]]> @@ -144,18 +144,18 @@ Initializes a new instance of the class with an empty message and the root cause of the exception. - . This constructor sets the properties of the `Exception` object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`| -||The empty string ("").| - + . This constructor sets the properties of the `Exception` object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`| +||The empty string ("").| + ]]> @@ -205,16 +205,16 @@ A describing the reason why the exception occurred. Initializes a new instance of the class with the given message and the root cause exception. - . This constructor sets the properties of the `Exception` object as shown in the following table. - -|Property|Value| -|--------------|-----------| -||`null`| -||The message string.| - + . This constructor sets the properties of the `Exception` object as shown in the following table. + +|Property|Value| +|--------------|-----------| +||`null`| +||The message string.| + ]]> @@ -327,18 +327,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 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.Reflection/TargetInvocationException.xml b/xml/System.Reflection/TargetInvocationException.xml index fd1b12aa3c6..89bf79469a5 100644 --- a/xml/System.Reflection/TargetInvocationException.xml +++ b/xml/System.Reflection/TargetInvocationException.xml @@ -91,7 +91,7 @@ `TargetInvocationException` uses the HRESULT COR_E_TARGETINVOCATION, which has the value 0x80131604. - When created, the `TargetInvocationException` is passed a reference to the exception thrown by the method invoked through reflection. The property holds the underlying exception. + When created, the `TargetInvocationException` is passed a reference to the exception thrown by the method invoked through reflection. The property holds the underlying exception. ]]> @@ -161,7 +161,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . @@ -228,7 +228,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Reflection/TargetParameterCountException.xml b/xml/System.Reflection/TargetParameterCountException.xml index ede4114c3dd..170590448ae 100644 --- a/xml/System.Reflection/TargetParameterCountException.xml +++ b/xml/System.Reflection/TargetParameterCountException.xml @@ -275,7 +275,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Reflection/TypeAttributes.xml b/xml/System.Reflection/TypeAttributes.xml index 750fcefe8c7..31e7a1f0656 100644 --- a/xml/System.Reflection/TypeAttributes.xml +++ b/xml/System.Reflection/TypeAttributes.xml @@ -75,29 +75,29 @@ Specifies type attributes. - value retrieved from a property such as . The following table lists the masks and the individual members that they include: - -|Mask|Includes| -|----------|--------------| -|VisibilityMask|NotPublic
Public
NestedPublic
NestedPrivate
NestedFamily
NestedAssembly
NestedFamANDAssem
NestedFamORAssem| -|LayoutMask|AutoLayout
SequentialLayout
ExplicitLayout| -|ClassSemanticsMask|Class
Interface| -|StringFormatMask|AnsiClass
UnicodeClass
AutoClass
CustomFormatClass| -|CustomFormatMask|No members.| - - The members of this enumerator class match the CorTypeAttr enumerator as defined in the corhdr.h file. - - - -## Examples - The following example retrieves the value of the property for objects that represent a number of different types, and then determines whether individual attribute flags have been set. - + value retrieved from a property such as . The following table lists the masks and the individual members that they include: + +|Mask|Includes| +|----------|--------------| +|VisibilityMask|NotPublic
Public
NestedPublic
NestedPrivate
NestedFamily
NestedAssembly
NestedFamANDAssem
NestedFamORAssem| +|LayoutMask|AutoLayout
SequentialLayout
ExplicitLayout| +|ClassSemanticsMask|Class
Interface| +|StringFormatMask|AnsiClass
UnicodeClass
AutoClass
CustomFormatClass| +|CustomFormatMask|No members.| + + The members of this enumerator class match the CorTypeAttr enumerator as defined in the corhdr.h file. + + + +## Examples + The following example retrieves the value of the property for objects that represent a number of different types, and then determines whether individual attribute flags have been set. + :::code language="csharp" source="~/snippets/csharp/System/Type/Attributes/attributes1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/Type/Attributes/attributes1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System/Type/Attributes/attributes1.vb" id="Snippet1"::: + ]]>
diff --git a/xml/System.Reflection/TypeInfo.xml b/xml/System.Reflection/TypeInfo.xml index 60ed35d2ce0..3c20bbd4014 100644 --- a/xml/System.Reflection/TypeInfo.xml +++ b/xml/System.Reflection/TypeInfo.xml @@ -86,17 +86,17 @@ Represents type declarations for class types, interface types, array types, value types, enumeration types, type parameters, generic type definitions, and open or closed constructed generic types. - class is included in the .NET for Windows 8.x Store apps subset for use in creating Windows Store apps. is available in the full .NET Framework as well. For more information about reflection for Windows Store apps, see [System.Reflection namespaces](/dotnet/api/?term=system.reflection) and [Reflection in the .NET Framework for Windows Store Apps](/dotnet/framework/reflection-and-codedom/reflection-for-windows-store-apps). - - contains many of the members available in the class, and many of the reflection properties in the .NET for Windows 8.x Store apps return collections of objects. To get a object from a object, use the extension method. - - A object represents the type definition itself, whereas a object represents a reference to the type definition. Getting a object forces the assembly that contains that type to load. In comparison, you can manipulate objects without necessarily requiring the runtime to load the assembly they reference. - - In the .NET for Windows 8.x Store apps, you use the reflection properties of that return collections instead of methods that return arrays. For example, use the property to get all declared members, or the property to get all declared properties. Reflection contexts can implement lazy traversal of these collections for large assemblies or types. To get specific members, use methods such as and , and pass the name of the method or property you would like to retrieve. - + class is included in the .NET for Windows 8.x Store apps subset for use in creating Windows Store apps. is available in the full .NET Framework as well. For more information about reflection for Windows Store apps, see [System.Reflection namespaces](/dotnet/api/?term=system.reflection) and [Reflection in the .NET Framework for Windows Store Apps](/dotnet/framework/reflection-and-codedom/reflection-for-windows-store-apps). + + contains many of the members available in the class, and many of the reflection properties in the .NET for Windows 8.x Store apps return collections of objects. To get a object from a object, use the extension method. + + A object represents the type definition itself, whereas a object represents a reference to the type definition. Getting a object forces the assembly that contains that type to load. In comparison, you can manipulate objects without necessarily requiring the runtime to load the assembly they reference. + + In the .NET for Windows 8.x Store apps, you use the reflection properties of that return collections instead of methods that return arrays. For example, use the property to get all declared members, or the property to get all declared properties. Reflection contexts can implement lazy traversal of these collections for large assemblies or types. To get specific members, use methods such as and , and pass the name of the method or property you would like to retrieve. + To filter the results of properties, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. ## Examples @@ -104,7 +104,7 @@ The following example uses the reflection types and members in .NET to retrieve the methods and properties of the type, including inherited methods and properties, and then writes them to the console. :::code language="csharp" source="~/snippets/csharp/System.Reflection/TypeInfo/Overview/example.cs" id="Snippet1"::: - + ]]> @@ -401,11 +401,11 @@ The following example uses the reflection types and members in .NET to retrieve Gets a collection of the constructors declared by the current type. A collection of the constructors declared by the current type. - property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. - + property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. + ]]> @@ -460,11 +460,11 @@ The following example uses the reflection types and members in .NET to retrieve Gets a collection of the events defined by the current type. A collection of the events defined by the current type. - property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. - + property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. + ]]> @@ -519,11 +519,11 @@ The following example uses the reflection types and members in .NET to retrieve Gets a collection of the fields defined by the current type. A collection of the fields defined by the current type. - property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. - + property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. + ]]> @@ -582,11 +582,11 @@ The following example uses the reflection types and members in .NET to retrieve Gets a collection of the members defined by the current type. A collection of the members defined by the current type. - property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. - + property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. + ]]> @@ -641,17 +641,17 @@ The following example uses the reflection types and members in .NET to retrieve Gets a collection of the methods defined by the current type. A collection of the methods defined by the current type. - property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. - + property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. + ## Examples The following example uses the reflection types and members in .NET to retrieve the methods and properties of the type, including inherited methods and properties, and then writes them to the console. -:::code language="csharp" source="~/snippets/csharp/System.Reflection/TypeInfo/Overview/example.cs" id="Snippet1"::: - +:::code language="csharp" source="~/snippets/csharp/System.Reflection/TypeInfo/Overview/example.cs" id="Snippet1"::: + ]]> @@ -714,11 +714,11 @@ The following example uses the reflection types and members in .NET to retrieve Gets a collection of the nested types defined by the current type. A collection of nested types defined by the current type. - property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. - + property, use LINQ queries. For reflection objects that originate with the runtime (for example, as the result of `typeof(Object)`), you can traverse the inheritance tree by using the methods in the class. Consumers of objects from customized reflection contexts cannot use these methods and must traverse the inheritance tree themselves. + ]]> @@ -773,14 +773,14 @@ The following example uses the reflection types and members in .NET to retrieve Gets a collection of the properties defined by the current type. A collection of the properties defined by the current type. - type, including inherited methods and properties, and then writes them to the console. :::code language="csharp" source="~/snippets/csharp/System.Reflection/TypeInfo/Overview/example.cs" id="Snippet1"::: - + ]]> @@ -4780,11 +4780,11 @@ The following example uses the reflection types and members in .NET to retrieve Returns a representation of the current type as a object. A reference to the current type. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Resources/MissingManifestResourceException.xml b/xml/System.Resources/MissingManifestResourceException.xml index 4e23c1da6a6..4892df0c690 100644 --- a/xml/System.Resources/MissingManifestResourceException.xml +++ b/xml/System.Resources/MissingManifestResourceException.xml @@ -326,7 +326,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Resources/MissingSatelliteAssemblyException.xml b/xml/System.Resources/MissingSatelliteAssemblyException.xml index 90ca2ea7acd..678b25278b8 100644 --- a/xml/System.Resources/MissingSatelliteAssemblyException.xml +++ b/xml/System.Resources/MissingSatelliteAssemblyException.xml @@ -70,67 +70,67 @@ The exception that is thrown when the satellite assembly for the resources of the default culture is missing. - is thrown if the resource manager tries to retrieve but cannot find a resource for the default culture. However, the .NET Framework will load the resources for an app's default culture from a satellite assembly if the attribute specifies a value of for the location parameter. When this is the case, the exception is thrown when the resource manager tries to retrieve a resource of the default culture and the satellite assembly for the culture specified in the attribute is missing. Note that the exception is thrown by a resource retrieval method such as or , and not when the object is instantiated. - - uses the HRESULT COR_E_MISSINGSATELLITEASSEMBLY, which has the value 0x80131536. - - uses the default implementation, which supports reference equality. - - For a list of initial property values for an instance of the class, see the constructors. - + is thrown if the resource manager tries to retrieve but cannot find a resource for the default culture. However, the .NET Framework will load the resources for an app's default culture from a satellite assembly if the attribute specifies a value of for the location parameter. When this is the case, the exception is thrown when the resource manager tries to retrieve a resource of the default culture and the satellite assembly for the culture specified in the attribute is missing. Note that the exception is thrown by a resource retrieval method such as or , and not when the object is instantiated. + + uses the HRESULT COR_E_MISSINGSATELLITEASSEMBLY, which has the value 0x80131536. + + uses the default implementation, which supports reference equality. + + For a list of initial property values for an instance of the class, see the constructors. + > [!NOTE] -> You should always use the attribute to define your app's default culture so that if a resource for a specific culture is unavailable, your application will display acceptable behavior. - - - -## Examples - The following example uses the attribute to indicate that English is the app's default culture and that its resources are stored in a satellite assembly. The example itself includes resources in .txt files for the English and French cultures, as described in the following table: - -|Culture|Resource name/value|File name| -|-------------|--------------------------|---------------| -|English|Greet=Hello|Greet.en.txt| -|French|Greet=Bonjour|Greet.fr.txt| - - The following source code builds an app that changes the current UI culture first to French (France) and then to Russian (Russia) and displays an appropriate culture-specific resource in both cases. - +> You should always use the attribute to define your app's default culture so that if a resource for a specific culture is unavailable, your application will display acceptable behavior. + + + +## Examples + The following example uses the attribute to indicate that English is the app's default culture and that its resources are stored in a satellite assembly. The example itself includes resources in .txt files for the English and French cultures, as described in the following table: + +|Culture|Resource name/value|File name| +|-------------|--------------------------|---------------| +|English|Greet=Hello|Greet.en.txt| +|French|Greet=Bonjour|Greet.fr.txt| + + The following source code builds an app that changes the current UI culture first to French (France) and then to Russian (Russia) and displays an appropriate culture-specific resource in both cases. + :::code language="csharp" source="~/snippets/csharp/System.Resources/MissingSatelliteAssemblyException/Overview/helloworld.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Resources/MissingSatelliteAssemblyException/Overview/helloworld.vb" id="Snippet1"::: - - You can use the following batch file to build and execute the C# version of the example. If you're using Visual Basic, replace `csc` with `vbc`, and replace the `.cs` extension with `.vb`. When the example is executed, it displays a French language string but throws a exception when the current culture is Russian (Russia). This is because the satellite assembly en\HelloWorld.dll that contains the resources of the default culture does not exist. - -``` - -vbc HelloWorld.vb - -md fr -resgen Greet.fr.txt -al /out:fr\HelloWorld.resources.dll /culture:fr /embed:GreetResources.fr.resources - -HelloWorld - -``` - - You can use the following batch file to build and execute the Visual Basic version of the example. If you're using C#, replace `vbc` with `csc`, and replace the `.vb` extension with `.cs`. When the example is executed, it displays a French language string when the current UI culture is French (France). When the current UI culture is Russia (Russian), it displays an English language string because Russian language resources do not exist, but the resource manager is able to load the resources of the default culture from the satellite assembly en\HelloWorld2.dll. - -``` - -vbc HelloWorld.vb /out:HelloWorld2.exe - -md fr -resgen GreetResources.fr.txt -al /out:fr\HelloWorld2.resources.dll /culture:fr /embed:GreetResources.fr.resources - -md en -resgen GreetResources.en.txt -al /out:en\HelloWorld2.resources.dll /culture:en /embed:GreetResources.en.resources - -HelloWorld2 - -``` - + :::code language="vb" source="~/snippets/visualbasic/System.Resources/MissingSatelliteAssemblyException/Overview/helloworld.vb" id="Snippet1"::: + + You can use the following batch file to build and execute the C# version of the example. If you're using Visual Basic, replace `csc` with `vbc`, and replace the `.cs` extension with `.vb`. When the example is executed, it displays a French language string but throws a exception when the current culture is Russian (Russia). This is because the satellite assembly en\HelloWorld.dll that contains the resources of the default culture does not exist. + +``` + +vbc HelloWorld.vb + +md fr +resgen Greet.fr.txt +al /out:fr\HelloWorld.resources.dll /culture:fr /embed:GreetResources.fr.resources + +HelloWorld + +``` + + You can use the following batch file to build and execute the Visual Basic version of the example. If you're using C#, replace `vbc` with `csc`, and replace the `.vb` extension with `.cs`. When the example is executed, it displays a French language string when the current UI culture is French (France). When the current UI culture is Russia (Russian), it displays an English language string because Russian language resources do not exist, but the resource manager is able to load the resources of the default culture from the satellite assembly en\HelloWorld2.dll. + +``` + +vbc HelloWorld.vb /out:HelloWorld2.exe + +md fr +resgen GreetResources.fr.txt +al /out:fr\HelloWorld2.resources.dll /culture:fr /embed:GreetResources.fr.resources + +md en +resgen GreetResources.en.txt +al /out:en\HelloWorld2.resources.dll /culture:en /embed:GreetResources.en.resources + +HelloWorld2 + +``` + ]]> @@ -187,16 +187,16 @@ HelloWorld2 Initializes a new instance of the class with default properties. - class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message for .| - + class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message for .| + ]]> @@ -244,16 +244,16 @@ HelloWorld2 The error message that explains the reason for the exception. Initializes a new instance of the class with the specified error message. - class. - -|Property|Value| -|--------------|-----------| -||`null`.| -||The `message` string.| - + class. + +|Property|Value| +|--------------|-----------| +||`null`.| +||The `message` string.| + ]]> @@ -316,11 +316,11 @@ HelloWorld2 The contextual information about the source or destination of the exception. Initializes a new instance of the class from serialized data. - @@ -370,18 +370,18 @@ HelloWorld2 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 the class. - -|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 the class. + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> @@ -431,16 +431,16 @@ HelloWorld2 The name of the neutral culture. Initializes a new instance of the class with a specified error message and the name of a neutral culture. - class. - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| - + class. + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> @@ -488,13 +488,13 @@ HelloWorld2 Gets the name of the default culture. The name of the default culture. - attribute. For a list of culture names available on Windows systems, see the **Language tag** column in the [list of language/region names supported by Windows](https://learn.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). - - + + ]]> diff --git a/xml/System.Resources/ResXDataNode.xml b/xml/System.Resources/ResXDataNode.xml index ce8e394aa3f..40cfe54d0dc 100644 --- a/xml/System.Resources/ResXDataNode.xml +++ b/xml/System.Resources/ResXDataNode.xml @@ -39,26 +39,26 @@ Represents an element in an XML resource (.resx) file. - class supports the representation of rich data types within a resource file. It can support the storage of any object in a resource file, so long as the object supports serialization and type editors. - - You can create a object by calling one of its overloaded class constructors. You can then add the resource item or element to a resource file by calling the method. - - To retrieve an existing object, you must enumerate the objects in an XML resource file by instantiating a object, setting the property to `true`, and calling the method to get an enumerator. The example provides an illustration. - -## Examples - The following example uses the method to obtain an object that is used to enumerate the objects in a .resx file. The example includes a `CreateResourceFile` routine that creates the necessary XML resource file. - + The class supports the representation of rich data types within a resource file. It can support the storage of any object in a resource file, so long as the object supports serialization and type editors. + + You can create a object by calling one of its overloaded class constructors. You can then add the resource item or element to a resource file by calling the method. + + To retrieve an existing object, you must enumerate the objects in an XML resource file by instantiating a object, setting the property to `true`, and calling the method to get an enumerator. The example provides an illustration. + +## Examples + The following example uses the method to obtain an object that is used to enumerate the objects in a .resx file. The example includes a `CreateResourceFile` routine that creates the necessary XML resource file. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXDataNode/Overview/resxresourcereader2.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Resources/ResXDataNode/Overview/resxresourcereader2.vb" id="Snippet1"::: - - Because the property is `true`, the value of the property is a object rather than the resource value. This makes a resource item's comment available from the property. - + :::code language="vb" source="~/snippets/visualbasic/System.Resources/ResXDataNode/Overview/resxresourcereader2.vb" id="Snippet1"::: + + Because the property is `true`, the value of the property is a object rather than the resource value. This makes a resource item's comment available from the property. + ]]> Serialization in .NET @@ -297,18 +297,18 @@ Gets or sets an arbitrary comment regarding this resource. A string that represents the comment. - property is . - - You access the property of an data node in an existing XML resource file by instantiating a object, setting the property to `true`, and calling the method to retrieve an object that you use to enumerate the items in the XML resource file. The property returns the object. - - - -## Examples - See the example for the class. - + property is . + + You access the property of an data node in an existing XML resource file by instantiating a object, setting the property to `true`, and calling the method to retrieve an object that you use to enumerate the items in the XML resource file. The property returns the object. + + + +## Examples + See the example for the class. + ]]> @@ -414,11 +414,11 @@ Retrieves the object that is stored by this node by using the specified type resolution service. The object that corresponds to the stored value. - looks for a by using the specified type resolution service that can convert from a string to the appropriate object. If the resource is a file reference, tries to de-serialize it. - + looks for a by using the specified type resolution service that can convert from a string to the appropriate object. If the resource is a file reference, tries to de-serialize it. + ]]> The corresponding type could not be found, or an appropriate type converter is not available. @@ -463,11 +463,11 @@ Retrieves the object that is stored by this node by searching the specified assemblies. The object that corresponds to the stored value. - looks in the assemblies identified by names to find the object's corresponding type, and then looks for a that can convert from a string to the appropriate object. If the resource is a file reference, tries to deserialize it. - + looks in the assemblies identified by names to find the object's corresponding type, and then looks for a that can convert from a string to the appropriate object. If the resource is a file reference, tries to deserialize it. + ]]> The corresponding type could not be found, or an appropriate type converter is not available. @@ -631,11 +631,11 @@ The destination for this serialization. Populates a object with the data needed to serialize the target object. - instance is cast to an interface. - + instance is cast to an interface. + ]]> diff --git a/xml/System.Resources/ResXResourceReader.xml b/xml/System.Resources/ResXResourceReader.xml index 8ca90b87b2f..940349bea19 100644 --- a/xml/System.Resources/ResXResourceReader.xml +++ b/xml/System.Resources/ResXResourceReader.xml @@ -62,16 +62,16 @@ :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/resxresourcereader1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Resources/ResXResourceReader/Overview/resxresourcereader1.vb" id="Snippet1"::: - If the property is `true`, the value of the property is a object rather than the resource value. This makes a resource item's comment available from the property. The following example sets the property to `true` and enumerates the resources in a .resx file, + If the property is `true`, the value of the property is a object rather than the resource value. This makes a resource item's comment available from the property. The following example sets the property to `true` and enumerates the resources in a .resx file, :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/resxresourcereader2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Resources/ResXResourceReader/Overview/resxresourcereader2.vb" id="Snippet2"::: If is `true`, the items in the enumeration can be either: -- Named resources along with their data. In this case, the property is `null`. +- Named resources along with their data. In this case, the property is `null`. -- Named resources along with the name of the file that contains the resource data. In this case, the property returns a object that provides information about the resource, including its filename. If relative file names are used, you should always set the property to provide a reference point for the relative file path. +- Named resources along with the name of the file that contains the resource data. In this case, the property returns a object that provides information about the resource, including its filename. If relative file names are used, you should always set the property to provide a reference point for the relative file path. If you want to retrieve named resources from a .resx file rather than enumerating its resources, you can instantiate a object and call its `GetString` and `GetObject` methods. @@ -503,12 +503,12 @@ property is used to resolve relative file path references that are assigned to the property of objects. By default, its value is , and relative file path references are resolved in relationship to the current directory returned by the property. You should set this property before you begin enumerating resources. + The property is used to resolve relative file path references that are assigned to the property of objects. By default, its value is , and relative file path references are resolved in relationship to the current directory returned by the property. You should set this property before you begin enumerating resources. ## Examples - The following example creates an XML resource file that contains images of dog breeds, and also creates a string resource that specifies the application that created the resource. objects are used to store the path to the images rather than storing the binary images themselves in the resource file. The example sets the property so that the relative file paths in the images' file names are interpreted as subdirectories of a directory named C:\data\\. + The following example creates an XML resource file that contains images of dog breeds, and also creates a string resource that specifies the application that created the resource. objects are used to store the path to the images rather than storing the binary images themselves in the resource file. The example sets the property so that the relative file paths in the images' file names are interpreted as subdirectories of a directory named C:\data\\. :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/BasePath/basepathex1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Resources/ResXResourceReader/BasePath/basepathex1.vb" id="Snippet1"::: @@ -809,7 +809,7 @@ method retrieves the name/value pairs in the XML resource (.resx) stream or string associated with the current object. However, if the property is set to `true` before you call , the resource items are retrieved as objects. In this case, all resource nodes are returned regardless of type. + The method retrieves the name/value pairs in the XML resource (.resx) stream or string associated with the current object. However, if the property is set to `true` before you call , the resource items are retrieved as objects. In this case, all resource nodes are returned regardless of type. @@ -854,12 +854,12 @@ method provides an object that can retrieve the metadata from the resource file or stream associated with the current object. However, if the property is set to `true` before you call , no resource nodes are retrieved. + Resources are stored as name/value pairs in a resource file or stream. Design-time properties, which are called metadata, are stored in the resource file or stream along with runtime data resources. The method provides an object that can retrieve the metadata from the resource file or stream associated with the current object. However, if the property is set to `true` before you call , no resource nodes are retrieved. ## Examples - The following example uses the method to iterate through the metadata resources in an XML resource file. This code example is part of a larger example provided for the property. + The following example uses the method to iterate through the metadata resources in an XML resource file. This code example is part of a larger example provided for the property. :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceReader/Overview/useresxdatanodes.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Resources/ResXResourceReader/Overview/useresxdatanodes.vb" id="Snippet4"::: @@ -993,7 +993,7 @@ property before you begin enumerating resources. By default, its value is `false`. + You can set the property before you begin enumerating resources. By default, its value is `false`. diff --git a/xml/System.Resources/ResXResourceSet.xml b/xml/System.Resources/ResXResourceSet.xml index cce024a43d3..0e18103e837 100644 --- a/xml/System.Resources/ResXResourceSet.xml +++ b/xml/System.Resources/ResXResourceSet.xml @@ -31,24 +31,24 @@ Represents all resources in an XML resource (.resx) file. - class enumerates over an , loads every name and value, and stores them in a hash table. You can then enumerate the resources in the object or retrieve individual resources by name. - + A object provides a convenient way to read all the resources in a .resx file into memory. You can use the method to retrieve a particular resource when the .resx file has been read into a instance. - -## Examples - The following example instantiates a object and illustrates how to enumerate its resources and retrieve individual resources by name. For each resource that it enumerates, the example uses the property in a call to the `GetString` or `GetObject` method, depending on whether the value of the resource is a string or an object. - + +## Examples + The following example instantiates a object and illustrates how to enumerate its resources and retrieve individual resources by name. For each resource that it enumerates, the example uses the property in a call to the `GetString` or `GetObject` method, depending on whether the value of the resource is a string or an object. + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResXResourceSet/Overview/example1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Resources/ResXResourceSet/Overview/example1.vb" id="Snippet1"::: - - The example calls a `CreateResXFile` method to create the necessary XML resource file. It requires a bitmap file named Logo.bmp in the directory in which the example is running. - + :::code language="vb" source="~/snippets/visualbasic/System.Resources/ResXResourceSet/Overview/example1.vb" id="Snippet1"::: + + The example calls a `CreateResXFile` method to create the necessary XML resource file. It requires a bitmap file named Logo.bmp in the directory in which the example is running. + ]]> diff --git a/xml/System.Resources/ResourceManager.xml b/xml/System.Resources/ResourceManager.xml index c6fa4f0fad3..ea60cf8c9e8 100644 --- a/xml/System.Resources/ResourceManager.xml +++ b/xml/System.Resources/ResourceManager.xml @@ -387,12 +387,12 @@ property reflects the fully qualified namespace name and the root resource name of a resource file, without its culture or file name extension. For example, if an app's default resource file is named `SampleApps.StringResources.resources`, the value of the property is "SampleApps.StringResources". If an app's default resource file is named `SampleApps.StringResources.en-US.resources` and is embedded in a satellite assembly, the value of the property is still "SampleApps.StringResources". + The property reflects the fully qualified namespace name and the root resource name of a resource file, without its culture or file name extension. For example, if an app's default resource file is named `SampleApps.StringResources.resources`, the value of the property is "SampleApps.StringResources". If an app's default resource file is named `SampleApps.StringResources.en-US.resources` and is embedded in a satellite assembly, the value of the property is still "SampleApps.StringResources". > [!IMPORTANT] -> The property value of a resource file that is compiled and embedded from the command line does not include a namespace name unless you explicitly include one when compiling the file. On the other hand, the property value of a resource file that is compiled and embedded within the Visual Studio environment typically does include the default namespace name. +> The property value of a resource file that is compiled and embedded from the command line does not include a namespace name unless you explicitly include one when compiling the file. On the other hand, the property value of a resource file that is compiled and embedded within the Visual Studio environment typically does include the default namespace name. - The property value is the same as the string passed to the or constructor when instantiating a instance. + The property value is the same as the string passed to the or constructor when instantiating a instance. @@ -567,7 +567,7 @@ property is useful only if you write your own class that derives from the class. + The property is useful only if you write your own class that derives from the class. You can use the attribute to inform the resource manager where to find the default culture for an app: in the main assembly (default) or in a satellite assembly. @@ -824,7 +824,7 @@ ## Remarks The method is useful only if you write your own class that derives from the class. - This method uses the property as part of the file name for all cultures other than the invariant culture. This method does not look in an assembly's manifest or touch the disk, and is used only to construct a resource file name (suitable for passing to the constructor) or a manifest resource blob name. + This method uses the property as part of the file name for all cultures other than the invariant culture. This method does not look in an assembly's manifest or touch the disk, and is used only to construct a resource file name (suitable for passing to the constructor) or a manifest resource blob name. A derived class can override this method to look for a different extension, such as ".ResX", or a completely different scheme for naming resource files. Note that the method can be used to customize the name of a resource file within a satellite assembly, and not to customize the name of the satellite assembly itself. @@ -1119,9 +1119,9 @@ If you change the value of the `createIfNotExists` argument to `false`, the meth ## Remarks The method takes the name of a resource that is stored as a object, gets the value of the resource, and returns an object. It requires that you work directly with a stream of bytes, which you then convert to an object. This method is useful primarily for performance reasons: Retrieving a resource as a byte stream instead of an explicit object can improve performance. - The returned resource is localized for the UI culture of the current thread, which is defined by the property. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. + The returned resource is localized for the UI culture of the current thread, which is defined by the property. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. - The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. + The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. @@ -1227,9 +1227,9 @@ csc GetStream.cs /resource:AppResources.resources ## Remarks The method takes the name of a resource that is stored as a object, gets the value of the resource, and returns an object. It requires that you work directly with a stream of bytes, which you then convert to an object. This method is useful primarily for performance reasons: Retrieving a resource as a byte stream instead of an explicit object can improve performance. - The returned resource is localized for the culture that is specified by `culture`, or for the culture that is specified by the property if `culture` is `null`. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. + The returned resource is localized for the culture that is specified by `culture`, or for the culture that is specified by the property if `culture` is `null`. If the resource is not localized for that culture, the resource manager uses fallback rules to load an appropriate resource. If no usable set of localized resources is found, the falls back on the default culture's resources. If a resource set for the default culture is not found, the method throws a exception or, if the resource set is expected to reside in a satellite assembly, a exception. If the resource manager can load an appropriate resource set but cannot find a resource named `name`, the method returns `null`. - The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. + The property determines whether the comparison of `name` with the names of resources is case-insensitive (the default) or case-sensitive. ]]> @@ -1478,7 +1478,7 @@ csc GetStream.cs /resource:AppResources.resources property is `false`, a resource with the name "Resource" is not equivalent to the resource with the name "resource". If is `true`, a resource with the name "Resource" is equivalent to the resource with the name "resource". Note, however, that when is `true`, the and methods perform case-insensitive string comparisons by using the invariant culture. The advantage is that results of case-insensitive string comparisons performed by these methods are the same on all computers regardless of culture. The disadvantage is that the results are not consistent with the casing rules of all cultures. + If the value of the property is `false`, a resource with the name "Resource" is not equivalent to the resource with the name "resource". If is `true`, a resource with the name "Resource" is equivalent to the resource with the name "resource". Note, however, that when is `true`, the and methods perform case-insensitive string comparisons by using the invariant culture. The advantage is that results of case-insensitive string comparisons performed by these methods are the same on all computers regardless of culture. The disadvantage is that the results are not consistent with the casing rules of all cultures. For example, the Turkish alphabet has two versions of the character I: one with a dot and one without a dot. In Turkish, the character I (Unicode 0049) is considered the uppercase version of a different character ı (Unicode 0131). The character i (Unicode 0069) is considered the lowercase version of yet another character İ (Unicode 0130). According to these casing rules, a case-insensitive string comparison of the characters i (Unicode 0069) and I (Unicode 0049) should fail for the culture "tr-TR" (Turkish in Turkey). However, because the comparison is conducted by using the casing rules of the invariant culture if is `true`, this comparison succeeds. diff --git a/xml/System.Resources/ResourceReader.xml b/xml/System.Resources/ResourceReader.xml index 57614124f39..d4d3af43edf 100644 --- a/xml/System.Resources/ResourceReader.xml +++ b/xml/System.Resources/ResourceReader.xml @@ -500,9 +500,9 @@ Label11="Mobile Phone:" 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. + Typically, you enumerate resources by calling the 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 implementation of the property by the class can throw the following exceptions: - @@ -610,7 +610,7 @@ Label11="Mobile Phone:" 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. + The 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: diff --git a/xml/System.Resources/ResourceSet.xml b/xml/System.Resources/ResourceSet.xml index 888b039d8ba..a5e24e4b058 100644 --- a/xml/System.Resources/ResourceSet.xml +++ b/xml/System.Resources/ResourceSet.xml @@ -309,7 +309,7 @@ ## Examples The following code example defines a new instance of the class for a specific file, iterates through the resources used by that file, and displays their contents to the console. - + :::code language="csharp" source="~/snippets/csharp/System.Resources/ResourceSet/.ctor/getenumerator.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Resources/ResourceSet/.ctor/getenumerator.vb" id="Snippet1"::: @@ -669,7 +669,7 @@ 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 . If the collection is modified between and , will return the element that it is set to, even if the enumerator is already invalidated. - You can use the property to access the value stored in the current element. Use the property to access the key of the current element. Use the property to access the value of the current element. + You can use the property to access the value stored in the current element. Use the property to access the key of the current element. Use the property to access the value of the current element. The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. diff --git a/xml/System.Resources/ResourceWriter.xml b/xml/System.Resources/ResourceWriter.xml index 4d88a696f51..8d6f3673d14 100644 --- a/xml/System.Resources/ResourceWriter.xml +++ b/xml/System.Resources/ResourceWriter.xml @@ -378,7 +378,7 @@ property for `value`. + You can specify any stream that supports the property for `value`. You can retrieve the resources written by the method by calling the method. @@ -630,7 +630,7 @@ property for `value`. + You can specify any stream that supports the property for `value`. You can retrieve the resources written by the method by calling the method. diff --git a/xml/System.Resources/SatelliteContractVersionAttribute.xml b/xml/System.Resources/SatelliteContractVersionAttribute.xml index 701f8b47856..335cb48853d 100644 --- a/xml/System.Resources/SatelliteContractVersionAttribute.xml +++ b/xml/System.Resources/SatelliteContractVersionAttribute.xml @@ -125,7 +125,7 @@ property with the `version` parameter. + This constructor initializes the property with the `version` parameter. ]]> diff --git a/xml/System.Runtime.Caching.Configuration/CachingSectionGroup.xml b/xml/System.Runtime.Caching.Configuration/CachingSectionGroup.xml index 4bf9a806c56..f9cdc5d2e91 100644 --- a/xml/System.Runtime.Caching.Configuration/CachingSectionGroup.xml +++ b/xml/System.Runtime.Caching.Configuration/CachingSectionGroup.xml @@ -16,11 +16,11 @@ Defines a configuration section for .NET Framework caching. This class cannot be inherited. - class defines a caching section (`system.runtime.caching`) for configuration files. This section contains elements that are used to configure various types of caches. In ASP.NET, the only element that is available in the caching section is the [\](/dotnet/framework/configure-apps/file-schema/runtime/memorycache-element-cache-settings) element. This element configures caches that are based on the class. - + class defines a caching section (`system.runtime.caching`) for configuration files. This section contains elements that are used to configure various types of caches. In ASP.NET, the only element that is available in the caching section is the [\](/dotnet/framework/configure-apps/file-schema/runtime/memorycache-element-cache-settings) element. This element configures caches that are based on the class. + ]]> <memoryCache> Element (Cache Settings) @@ -74,11 +74,11 @@ Gets the collection of objects. The collection of cache-section objects. - property returns the collection of objects from the parent caching section. - + property returns the collection of objects from the parent caching section. + ]]> <memoryCache> Element (Cache Settings) diff --git a/xml/System.Runtime.Caching.Configuration/MemoryCacheElement.xml b/xml/System.Runtime.Caching.Configuration/MemoryCacheElement.xml index c5e6ec30902..fdbc7250750 100644 --- a/xml/System.Runtime.Caching.Configuration/MemoryCacheElement.xml +++ b/xml/System.Runtime.Caching.Configuration/MemoryCacheElement.xml @@ -16,13 +16,13 @@ Defines an element that is used to configure a cache that is based on the class. This class cannot be inherited. - class defines a `memoryCache` element that you can use to configure the cache. Multiple instances of the class can be used in a single application. Each `memoryCache` element in the configuration file can contain settings for a named instance. - - The `memoryCache` element requires a `namedCaches` child element. To define named configurations of the cache in addition to the default configuration, you can add `namedCaches` elements. For more information about how to add named cache configurations, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). - + class defines a `memoryCache` element that you can use to configure the cache. Multiple instances of the class can be used in a single application. Each `memoryCache` element in the configuration file can contain settings for a named instance. + + The `memoryCache` element requires a `namedCaches` child element. To define named configurations of the cache in addition to the default configuration, you can add `namedCaches` elements. For more information about how to add named cache configurations, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). + ]]> <memoryCache> Element (Cache Settings) @@ -79,19 +79,19 @@ Gets or sets the maximum memory size, in megabytes, that an instance of a object can grow to. The amount of maximum memory size, in megabytes. The default is zero, which indicates that instances manage their own memory based on the amount of memory that is installed on the computer. - property value represents the `cacheMemoryLimitMegabytes` configuration attribute in the `namedCaches` configuration element. - - If the cache size exceeds the specified limit, the memory cache implementation removes cache entries. - - This property can be set individually in `namedCaches` elements, with each `namedCaches` element corresponding to a unique cache configuration. - - The settings for the property can be read from the `cacheMemoryLimitMegabytes` configuration attribute in the configuration file. Alternatively, the settings can be passed when the class is initialized. - - For more information about how to configure the cache, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). - + property value represents the `cacheMemoryLimitMegabytes` configuration attribute in the `namedCaches` configuration element. + + If the cache size exceeds the specified limit, the memory cache implementation removes cache entries. + + This property can be set individually in `namedCaches` elements, with each `namedCaches` element corresponding to a unique cache configuration. + + The settings for the property can be read from the `cacheMemoryLimitMegabytes` configuration attribute in the configuration file. Alternatively, the settings can be passed when the class is initialized. + + For more information about how to configure the cache, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). + ]]> <namedCaches> Element (Cache Settings) @@ -130,15 +130,15 @@ Gets or sets the name of a particular cache configuration. The name of a cache configuration. - property value is the unique identifier for a particular named cache configuration. Each cache configuration must have a unique ID. - - In the `memoryCache` section of a configuration file, a unique cache configuration is defined by a `namedCaches` configuration collection. Each named cache entry requires a unique name in the configuration file. This value must be at least one character long. - - For more information about how to configure the cache, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). - + property value is the unique identifier for a particular named cache configuration. Each cache configuration must have a unique ID. + + In the `memoryCache` section of a configuration file, a unique cache configuration is defined by a `namedCaches` configuration collection. Each named cache entry requires a unique name in the configuration file. This value must be at least one character long. + + For more information about how to configure the cache, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). + ]]> <namedCaches> Element (Cache Settings) @@ -173,15 +173,15 @@ Gets or sets the percentage of total system physical memory usage at which the cache will begin evicting entries. The percentage of physical memory in use, expressed as an integer value from 1 to 100. The default is zero, which indicates that instances manage their own memory based on the amount of memory that is installed on the computer. - property can be read from `physicalMemoryLimitPercentage` configuration attribute in the application configuration file. Alternatively, the value can be passed when the class is initialized. - - For more information about how to configure the cache, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). - + property can be read from `physicalMemoryLimitPercentage` configuration attribute in the application configuration file. Alternatively, the value can be passed when the class is initialized. + + For more information about how to configure the cache, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). + ]]> <namedCaches> Element (Cache Settings) @@ -216,13 +216,13 @@ Gets or sets a value that indicates the time interval after which the cache implementation compares the current memory load against the absolute and percentage-based memory limits that are set for the cache instance. The time interval after which the cache implementation compares the current memory load against the absolute and percentage-based memory limits that are set for the cache instance. The default is two minutes. - property corresponds to the `pollingInterval` configuration attribute of the `namedCaches` element. The settings for this configuration attribute are specified in the format `HH:MM:SS` and can be read from the `pollingInterval` configuration attribute in the application configuration. Alternatively, the value can be passed when the class is initialized. - - For more information about how to configure the cache, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). - + property corresponds to the `pollingInterval` configuration attribute of the `namedCaches` element. The settings for this configuration attribute are specified in the format `HH:MM:SS` and can be read from the `pollingInterval` configuration attribute in the application configuration. Alternatively, the value can be passed when the class is initialized. + + For more information about how to configure the cache, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). + ]]> <namedCaches> Element (Cache Settings) diff --git a/xml/System.Runtime.Caching.Configuration/MemoryCacheSection.xml b/xml/System.Runtime.Caching.Configuration/MemoryCacheSection.xml index 45fa2ec1ef4..71f4ed03cc3 100644 --- a/xml/System.Runtime.Caching.Configuration/MemoryCacheSection.xml +++ b/xml/System.Runtime.Caching.Configuration/MemoryCacheSection.xml @@ -16,13 +16,13 @@ Defines a configuration section for a cache based on the class. This class cannot be inherited. - class defines the settings that are available in the `memoryCache` section of a configuration file. In this section, the `namedCaches` element is used to configure a default instance of the cache and to configure any additional named instances. - - For more information, see [<memoryCache> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/memorycache-element-cache-settings). - + class defines the settings that are available in the `memoryCache` section of a configuration file. In this section, the `namedCaches` element is used to configure a default instance of the cache and to configure any additional named instances. + + For more information, see [<memoryCache> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/memorycache-element-cache-settings). + ]]> <memoryCache> Element (Cache Settings) @@ -77,11 +77,11 @@ Gets the collection of configuration settings for the named instances. A collection of settings for each named cache. - property references the collection of configuration settings from one or more `namedCaches` elements of the configuration file. For more information about configuration options that are related to this property, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). - + property references the collection of configuration settings from one or more `namedCaches` elements of the configuration file. For more information about configuration options that are related to this property, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). + ]]> <namedCaches> Element (Cache Settings) diff --git a/xml/System.Runtime.Caching.Hosting/IApplicationIdentifier.xml b/xml/System.Runtime.Caching.Hosting/IApplicationIdentifier.xml index ad7e89063a5..9b2dd3841cb 100644 --- a/xml/System.Runtime.Caching.Hosting/IApplicationIdentifier.xml +++ b/xml/System.Runtime.Caching.Hosting/IApplicationIdentifier.xml @@ -23,13 +23,13 @@ Defines an identifier for application domains that a cache implementation can use to interact with a host environment. - interface to define strings that identify individual application domains. The host environment implements the interface. This interface is then available to implementations through the property. - - A cache implementation uses this reference to obtain an identifier for the application domain. In ASP.NET, cache implementations use the application identifier to construct identifiers for cache performance counters. This provides names for performance counter instances that can be distinguished between application domains when multiple application domains are running. - + interface to define strings that identify individual application domains. The host environment implements the interface. This interface is then available to implementations through the property. + + A cache implementation uses this reference to obtain an identifier for the application domain. In ASP.NET, cache implementations use the application identifier to construct identifiers for cache performance counters. This provides names for performance counter instances that can be distinguished between application domains when multiple application domains are running. + ]]> @@ -55,13 +55,13 @@ Gets an identifier for an application domain. A unique identifier for the current application domain. - method is typically implemented by a .NET Framework host environment in order to construct an application identifier for an implementation. A implementation uses this information to identify the application domain that is currently running. - - For example, in ASP.NET, the cache uses an application identifier to construct identifiers for cache performance counters. The cache calls the method that is implemented by the host environment and the host returns the identifier. This provides names for performance counter instances that can be distinguished between application domains when multiple application domains are running. - + method is typically implemented by a .NET Framework host environment in order to construct an application identifier for an implementation. A implementation uses this information to identify the application domain that is currently running. + + For example, in ASP.NET, the cache uses an application identifier to construct identifiers for cache performance counters. The cache calls the method that is implemented by the host environment and the host returns the identifier. This provides names for performance counter instances that can be distinguished between application domains when multiple application domains are running. + ]]> diff --git a/xml/System.Runtime.Caching.Hosting/IFileChangeNotificationSystem.xml b/xml/System.Runtime.Caching.Hosting/IFileChangeNotificationSystem.xml index 6d7fe354a64..0e2d454f1ea 100644 --- a/xml/System.Runtime.Caching.Hosting/IFileChangeNotificationSystem.xml +++ b/xml/System.Runtime.Caching.Hosting/IFileChangeNotificationSystem.xml @@ -23,17 +23,17 @@ Defines a way to expose a custom object to a cache implementation. - interface provides access to internal file-change notification management. - - The interface is used internally by the class. - - When a cache implementation runs in an ASP.NET application domain, ASP.NET implements an interface through the property. The class detects this property and uses the ASP.NET file-change notification system to evict cache entries based on file-change notification. - - In non-ASP.NET applications, there is no host environment that implements a custom interface. As a result, the class uses the class of the CLR. - + interface provides access to internal file-change notification management. + + The interface is used internally by the class. + + When a cache implementation runs in an ASP.NET application domain, ASP.NET implements an interface through the property. The class detects this property and uses the ASP.NET file-change notification system to evict cache entries based on file-change notification. + + In non-ASP.NET applications, there is no host environment that implements a custom interface. As a result, the class uses the class of the CLR. + ]]> @@ -69,11 +69,11 @@ When this method returns, contains the total size of the monitored . This parameter is passed uninitialized. This parameter is returned from the host environment. Registers a file path to monitor with the host environment. - interface in order to register file paths for monitoring with the host environment. The method is called by implementers of the interface in order to register a file or directory for change monitoring. - + interface in order to register file paths for monitoring with the host environment. The method is called by implementers of the interface in order to register a file or directory for change monitoring. + ]]> @@ -103,11 +103,11 @@ The state information that was originally supplied by the host environment during an earlier call to the method. Ends change monitoring. - method must be called by custom caches and custom change monitors that are being disposed by the host environment in order to stop monitoring file paths and directories. - + method must be called by custom caches and custom change monitors that are being disposed by the host environment in order to stop monitoring file paths and directories. + ]]> diff --git a/xml/System.Runtime.Caching/CacheEntryChangeMonitor.xml b/xml/System.Runtime.Caching/CacheEntryChangeMonitor.xml index c757acdd4b2..9369c451bbd 100644 --- a/xml/System.Runtime.Caching/CacheEntryChangeMonitor.xml +++ b/xml/System.Runtime.Caching/CacheEntryChangeMonitor.xml @@ -25,11 +25,11 @@ Provides a base class that represents a type that can be implemented in order to monitor changes to cache entries. - class provides abstract, read-only properties that can be implemented for monitoring cache entries. This class is used when a cache implementation has to monitor changes to entries in its own cache. For caches that are cache implementations, an instance of the type is returned by the method. - + class provides abstract, read-only properties that can be implemented for monitoring cache entries. This class is used when a cache implementation has to monitor changes to entries in its own cache. For caches that are cache implementations, an instance of the type is returned by the method. + ]]> @@ -59,11 +59,11 @@ Initializes a new instance of the class. This constructor is called from constructors in derived classes to initialize the base class. - class has a parameterless constructor. - + class has a parameterless constructor. + ]]> @@ -91,11 +91,11 @@ Gets a collection of cache keys that are monitored for changes. A collection of cache keys. - type. - + type. + ]]> @@ -120,13 +120,13 @@ Gets a value that indicates the latest time (in UTC time) that the monitored cache entry was changed. The elapsed time. - property returns the latest time a modification occurred in any of the cache entries. - - The value of the property is typically calculated during initialization of a derived class. - + property returns the latest time a modification occurred in any of the cache entries. + + The value of the property is typically calculated during initialization of a derived class. + ]]> @@ -151,11 +151,11 @@ Gets the name of a region of the cache. The name of a region in the cache. - property provides the option to configure change monitors so that they monitor cache entries only in a specific cache region. - + property provides the option to configure change monitors so that they monitor cache entries only in a specific cache region. + ]]> diff --git a/xml/System.Runtime.Caching/CacheEntryUpdateArguments.xml b/xml/System.Runtime.Caching/CacheEntryUpdateArguments.xml index 8ec9b7e86fc..1e52742af34 100644 --- a/xml/System.Runtime.Caching/CacheEntryUpdateArguments.xml +++ b/xml/System.Runtime.Caching/CacheEntryUpdateArguments.xml @@ -25,13 +25,13 @@ Provides information about a cache entry that will be removed from the cache. - class contain details about an entry that the cache implementation is about to remove. The arguments include a key to the cache entry, a reference to the instance that the entry will be removed from, a reason for the removal, and the region name in the cache that contains the entry. The constructor of the class uses these arguments to create a new instance of the class. - - A object is passed to a handler, which notifies the cache about the entry to remove. - + class contain details about an entry that the cache implementation is about to remove. The arguments include a key to the cache entry, a reference to the instance that the entry will be removed from, a reason for the removal, and the region name in the cache that contains the entry. The constructor of the class uses these arguments to create a new instance of the class. + + A object is passed to a handler, which notifies the cache about the entry to remove. + ]]> @@ -213,11 +213,11 @@ Gets or sets the value of entry that is used to update the cache object. The cache entry to update in the cache object. The default is . - object to the property and assign a object to the property. The value must be a value other than `null`. Cache implementations will interpret a `null` value for the property as a notice that the current cache entry should be removed but not replaced. - + object to the property and assign a object to the property. The value must be a value other than `null`. Cache implementations will interpret a `null` value for the property as a notice that the current cache entry should be removed but not replaced. + ]]> @@ -252,13 +252,13 @@ Gets or sets the cache eviction or expiration policy of the entry that is updated. The cache eviction or expiration policy of the cache item that was updated. The default is . - object to the property. The object enables you to specify cache policy (such as expiration details) for the updated cache entry. - - For more information about how to replace a removed cache entry by using an updated one, see the class overview and the property. - + object to the property. The object enables you to specify cache policy (such as expiration details) for the updated cache entry. + + For more information about how to replace a removed cache entry by using an updated one, see the class overview and the property. + ]]> diff --git a/xml/System.Runtime.Caching/CacheItem.xml b/xml/System.Runtime.Caching/CacheItem.xml index 56d2ab5898c..df64a59857b 100644 --- a/xml/System.Runtime.Caching/CacheItem.xml +++ b/xml/System.Runtime.Caching/CacheItem.xml @@ -25,23 +25,23 @@ Represents an individual cache entry in the cache. - class provides a logical representation of a cache entry, which can include regions by using the property. In the default ASP.NET cache implementation, a cache entry is a key/value pair. - - Entries in the cache are not instances. Instead, the cache provider can store cache entries in any internal format that is convenient. However, the cache API requires cache providers to be able to convert cache entries into instances (and vice versa). - - Custom cache implementations can inherit from the class provide additional information about cache entries. - - - -## Examples - The following example shows how to use the class to store the contents of a file as a cache entry. - + class provides a logical representation of a cache entry, which can include regions by using the property. In the default ASP.NET cache implementation, a cache entry is a key/value pair. + + Entries in the cache are not instances. Instead, the cache provider can store cache entries in any internal format that is convenient. However, the cache API requires cache providers to be able to convert cache entries into instances (and vice versa). + + Custom cache implementations can inherit from the class provide additional information about cache entries. + + + +## Examples + The following example shows how to use the class to store the contents of a file as a cache entry. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/system.runtime.caching.cacheitem/cs/default.aspx.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.runtime.caching.cacheitem/vb/default.aspx.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/system.runtime.caching.cacheitem/vb/default.aspx.vb" id="Snippet1"::: + ]]> @@ -79,11 +79,11 @@ A unique identifier for a entry. Initializes a new instance using the specified key of a cache entry. - method overload is called, the property values for and are set to `null`. - + method overload is called, the property values for and are set to `null`. + ]]> @@ -110,11 +110,11 @@ The data for a entry. Initializes a new instance using the specified key and a value of the cache entry. - method overload is called, the property value for is set to `null`. - + method overload is called, the property value for is set to `null`. + ]]> diff --git a/xml/System.Runtime.Caching/CacheItemPolicy.xml b/xml/System.Runtime.Caching/CacheItemPolicy.xml index c99de03a79a..4aad8e37baf 100644 --- a/xml/System.Runtime.Caching/CacheItemPolicy.xml +++ b/xml/System.Runtime.Caching/CacheItemPolicy.xml @@ -25,73 +25,73 @@ Represents a set of eviction and expiration details for a specific cache entry. - instance contains information that can be associated with a cache entry. For example, when a cache entry is about to be removed from the cache, a object is passed to a callback method. The property of the object can pass a reference to a instance that can include eviction and expiration details about the cache entry. - - Some methods in the and classes accept a instance to describe eviction or expiration policy. - - - -## Examples - The following example shows how to create an in-memory cache item that monitors the path for a text file. The cache creates a object and sets the property to evict the cache after 60 seconds. - -```vb -Protected Sub Button1_Click(ByVal sender As Object, _ - ByVal e As System.EventArgs) Handles Button1.Click - Dim cache As ObjectCache = MemoryCache.Default - Dim fileContents As String = TryCast(cache("filecontents"), _ - String) - If fileContents Is Nothing Then - Dim policy As New CacheItemPolicy() - policy.AbsoluteExpiration = _ - DateTimeOffset.Now.AddSeconds(60.0) - Dim filePaths As New List(Of String)() - Dim cachedFilePath As String = Server.MapPath("~") & _ - "\cacheText.txt" - filePaths.Add(cachedFilePath) - policy.ChangeMonitors.Add(New _ - HostFileChangeMonitor(filePaths)) - - ' Fetch the file contents. - fileContents = File.ReadAllText(cachedFilePath) - cache.Set("filecontents", fileContents, policy) - End If - Label1.Text = fileContents -End Sub -``` - -```csharp -protected void Button1_Click(object sender, EventArgs e) - { - ObjectCache cache = MemoryCache.Default; - string fileContents = cache["filecontents"] as string; - if (fileContents == null) - { - CacheItemPolicy policy = new CacheItemPolicy(); - policy.AbsoluteExpiration = - DateTimeOffset.Now.AddSeconds(60.0); - - List filePaths = new List(); - string cachedFilePath = Server.MapPath("~") + - "\\cacheText.txt"; - filePaths.Add(cachedFilePath); - - policy.ChangeMonitors.Add(new - HostFileChangeMonitor(filePaths)); - - // Fetch the file contents. - fileContents = File.ReadAllText(cachedFilePath); - - cache.Set("filecontents", fileContents, policy); - - } - - Label1.Text = fileContents; - } -``` - + instance contains information that can be associated with a cache entry. For example, when a cache entry is about to be removed from the cache, a object is passed to a callback method. The property of the object can pass a reference to a instance that can include eviction and expiration details about the cache entry. + + Some methods in the and classes accept a instance to describe eviction or expiration policy. + + + +## Examples + The following example shows how to create an in-memory cache item that monitors the path for a text file. The cache creates a object and sets the property to evict the cache after 60 seconds. + +```vb +Protected Sub Button1_Click(ByVal sender As Object, _ + ByVal e As System.EventArgs) Handles Button1.Click + Dim cache As ObjectCache = MemoryCache.Default + Dim fileContents As String = TryCast(cache("filecontents"), _ + String) + If fileContents Is Nothing Then + Dim policy As New CacheItemPolicy() + policy.AbsoluteExpiration = _ + DateTimeOffset.Now.AddSeconds(60.0) + Dim filePaths As New List(Of String)() + Dim cachedFilePath As String = Server.MapPath("~") & _ + "\cacheText.txt" + filePaths.Add(cachedFilePath) + policy.ChangeMonitors.Add(New _ + HostFileChangeMonitor(filePaths)) + + ' Fetch the file contents. + fileContents = File.ReadAllText(cachedFilePath) + cache.Set("filecontents", fileContents, policy) + End If + Label1.Text = fileContents +End Sub +``` + +```csharp +protected void Button1_Click(object sender, EventArgs e) + { + ObjectCache cache = MemoryCache.Default; + string fileContents = cache["filecontents"] as string; + if (fileContents == null) + { + CacheItemPolicy policy = new CacheItemPolicy(); + policy.AbsoluteExpiration = + DateTimeOffset.Now.AddSeconds(60.0); + + List filePaths = new List(); + string cachedFilePath = Server.MapPath("~") + + "\\cacheText.txt"; + filePaths.Add(cachedFilePath); + + policy.ChangeMonitors.Add(new + HostFileChangeMonitor(filePaths)); + + // Fetch the file contents. + fileContents = File.ReadAllText(cachedFilePath); + + cache.Set("filecontents", fileContents, policy); + + } + + Label1.Text = fileContents; + } +``` + ]]> @@ -169,11 +169,11 @@ protected void Button1_Click(object sender, EventArgs e) Gets a collection of objects that are associated with a cache entry. A collection of change monitors. The default is an empty collection. - instance to an implementation. If you change the set of change monitors on a object after the object has been passed to an implementation, the changes have no effect. - + instance to an implementation. If you change the set of change monitors on a object after the object has been passed to an implementation, the changes have no effect. + ]]> @@ -208,14 +208,14 @@ protected void Button1_Click(object sender, EventArgs e) Gets or sets a priority setting that is used to determine whether to evict a cache entry. One of the enumeration values that indicates the priority for eviction. The default priority value is , which means no priority. - (which means no priority), and (which means the entry cannot be removed). Therefore, the only priority that can be set is whether a cache entry should remain in the cache forever. - + (which means no priority), and (which means the entry cannot be removed). Therefore, the only priority that can be set is whether a cache entry should remain in the cache forever. + > [!IMPORTANT] -> Adding an entry to the cache with a priority level of can cause the cache to overflow with entries that can never be removed. Cache implementations should set the priority for a cache entry only if the cache implementation provides ways to evict entries from the cache and to manage the number of cache entries. - +> Adding an entry to the cache with a priority level of can cause the cache to overflow with entries that can never be removed. Cache implementations should set the priority for a cache entry only if the cache implementation provides ways to evict entries from the cache and to manage the number of cache entries. + ]]> @@ -250,11 +250,11 @@ protected void Button1_Click(object sender, EventArgs e) Gets or sets a reference to a delegate that is called after an entry is removed from the cache. A reference to a delegate that is called by a cache implementation. - property. A cache implementation can use this callback to notify the calling method that a cache entry has been removed. - + property. A cache implementation can use this callback to notify the calling method that a cache entry has been removed. + ]]> diff --git a/xml/System.Runtime.Caching/ChangeMonitor.xml b/xml/System.Runtime.Caching/ChangeMonitor.xml index e4e8129d895..2ed862a761a 100644 --- a/xml/System.Runtime.Caching/ChangeMonitor.xml +++ b/xml/System.Runtime.Caching/ChangeMonitor.xml @@ -172,7 +172,7 @@ Note: This automatic call to the dispose method during the event firing only occ method invokes the method of derived classes only one time, the first time it is called. Subsequent calls to the method have no effect. After the method has been called, the property is set to `true`. + The method invokes the method of derived classes only one time, the first time it is called. Subsequent calls to the method have no effect. After the method has been called, the property is set to `true`. The overload must be called to dispose of a instance. The following are the rules for calling the dispose method: @@ -272,10 +272,10 @@ Note: This automatic call to the dispose method during the event firing only occ ## Remarks You can check the value of this property in a derived class to see whether a dependency has changed. - The value is set to `true` when a dependency change occurs (that is, when the method is called). After the method is called by the derived class, the value of the property will be `true`, regardless of whether a instance has been notified by a call to the method. + The value is set to `true` when a dependency change occurs (that is, when the method is called). After the method is called by the derived class, the value of the property will be `true`, regardless of whether a instance has been notified by a call to the method. > [!NOTE] -> Callers can check the property to see whether a dependency has changed. However, in a multi-threaded environment, a simpler and more maintainable approach is to insert data into a cache implementation without checking the property. Cache implementations must check the property for you and must not perform an insert or set operation if one or more associated dependencies have already changed. +> Callers can check the property to see whether a dependency has changed. However, in a multi-threaded environment, a simpler and more maintainable approach is to insert data into a cache implementation without checking the property. Cache implementations must check the property for you and must not perform an insert or set operation if one or more associated dependencies have already changed. ]]> @@ -308,7 +308,7 @@ Note: This automatic call to the dispose method during the event firing only occ ## Remarks If a dependency changes before initialization is complete in a derived class, the constructor of the derived class must invoke the method. - When the method is invoked, the property is automatically set to `true` by the change monitor. As a result, when the change monitor's constructor calls the method, the base class will automatically call the method. If initialization is complete, the method automatically disposes the derived change-monitor instance. + When the method is invoked, the property is automatically set to `true` by the change monitor. As a result, when the change monitor's constructor calls the method, the base class will automatically call the method. If initialization is complete, the method automatically disposes the derived change-monitor instance. ]]> @@ -373,14 +373,14 @@ Note: This automatic call to the dispose method during the event firing only occ instance with a populated change monitors property to the cache item. A cache implementer that supports change monitors is responsible for iterating over the property and register the delegates with each change monitor that it finds. + Cache implementers use this method to wire themselves up to a change monitor. If you associate one or more change monitors with the cache item, you pass a instance with a populated change monitors property to the cache item. A cache implementer that supports change monitors is responsible for iterating over the property and register the delegates with each change monitor that it finds. Because the delegate includes an optional state parameter, a concrete change monitor implementation can pass optional state information. The cache implementer determines whether an explicit dependency on the type of state that a custom change monitor passes as part of the callback can be taken. > [!NOTE] > The base cache extensibility API has no requirement for explicit dependency on the type of state. - The implementation of the method automatically determines whether the state of the monitor has already changed at the time method is called. If the property is `true`, then the method automatically calls the event handler, that was registered, through the method. This occurs because it is possible that from the time a cache implementation creates a change monitor, to the time a cache implementation gets the monitor and wires itself up to it, the underlying monitored state has changed. If the state has already changed then the object that is passed to the method is `null`. + The implementation of the method automatically determines whether the state of the monitor has already changed at the time method is called. If the property is `true`, then the method automatically calls the event handler, that was registered, through the method. This occurs because it is possible that from the time a cache implementation creates a change monitor, to the time a cache implementation gets the monitor and wires itself up to it, the underlying monitored state has changed. If the state has already changed then the object that is passed to the method is `null`. The method can be invoked only one time, and will throw an exception on subsequent calls. @@ -457,7 +457,7 @@ Note: This automatic call to the dispose method during the event firing only occ property value typically consists of dependency names combined string data that uniquely identifiers the data that is being monitored by a instance. The value of the property is a string. The value of the string is used to assign the unique ID of the instance. + The property value typically consists of dependency names combined string data that uniquely identifiers the data that is being monitored by a instance. The value of the property is a string. The value of the string is used to assign the unique ID of the instance. ]]> diff --git a/xml/System.Runtime.Caching/FileChangeMonitor.xml b/xml/System.Runtime.Caching/FileChangeMonitor.xml index b3601af76d5..0261f4578eb 100644 --- a/xml/System.Runtime.Caching/FileChangeMonitor.xml +++ b/xml/System.Runtime.Caching/FileChangeMonitor.xml @@ -25,19 +25,19 @@ Represents an object that monitors changes to files. - class is a base type for classes that monitor changes to files. To create a monitor for changes in the file system, you can inherit from this class. - - - -## Examples - The following example shows how to create a cache item that uses a object to monitor the state of the source data (a file) on the file system. The class inherits from the class. The cache entry is defined using a object that provides eviction and expiration details for the cache entry. - + class is a base type for classes that monitor changes to files. To create a monitor for changes in the file system, you can inherit from this class. + + + +## Examples + The following example shows how to create a cache item that uses a object to monitor the state of the source data (a file) on the file system. The class inherits from the class. The cache entry is defined using a object that provides eviction and expiration details for the cache entry. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_WebNet/cachingaspnetapplications/cs/default.aspx.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/cachingaspnetapplications/vb/default.aspx.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_WebNet/cachingaspnetapplications/vb/default.aspx.vb" id="Snippet1"::: + ]]> @@ -89,13 +89,13 @@ Gets a collection that contains the paths of files that are monitored for changes. A collection of file paths. - type. - - To provide custom file-change monitoring, you must override this method in a derived class. - + type. + + To provide custom file-change monitoring, you must override this method in a derived class. + ]]> @@ -120,13 +120,13 @@ Gets a value that indicates the last time that a file that is being monitored was changed. If multiple files are monitored, the last modified time of the most recently modified file; otherwise, the last time that the file that is being monitored was changed. - property is typically calculated during the initialization phase of a derived class. - - To provide custom file change monitoring, you must override this method in a derived class. - + property is typically calculated during the initialization phase of a derived class. + + To provide custom file change monitoring, you must override this method in a derived class. + ]]> diff --git a/xml/System.Runtime.Caching/HostFileChangeMonitor.xml b/xml/System.Runtime.Caching/HostFileChangeMonitor.xml index fbcd91b3634..26332e9575d 100644 --- a/xml/System.Runtime.Caching/HostFileChangeMonitor.xml +++ b/xml/System.Runtime.Caching/HostFileChangeMonitor.xml @@ -232,7 +232,7 @@ property value is constructed from the following parts: + The string that makes up the property value is constructed from the following parts: - A file or directory path. diff --git a/xml/System.Runtime.Caching/MemoryCache.xml b/xml/System.Runtime.Caching/MemoryCache.xml index cb1e9d2b2a8..4020b2cdf2f 100644 --- a/xml/System.Runtime.Caching/MemoryCache.xml +++ b/xml/System.Runtime.Caching/MemoryCache.xml @@ -154,7 +154,7 @@ private void btnGet_Click(object sender, EventArgs e) > There is no mechanism to enforce unique names for cache instances. Therefore, it is possible to have multiple cache instances with the same name. > [!CAUTION] - > Do not create instances unless it is required. If you create cache instances in client and Web applications, the instances should be created early in the application life cycle. You must create only the number of cache instances that will be used in your application, and store references to the cache instances in variables that can be accessed globally. For example, in ASP.NET applications, you can store the references in application state. If you create only a single cache instance in your application, use the default cache and get a reference to it from the property when you need to access the cache. + > Do not create instances unless it is required. If you create cache instances in client and Web applications, the instances should be created early in the application life cycle. You must create only the number of cache instances that will be used in your application, and store references to the cache instances in variables that can be accessed globally. For example, in ASP.NET applications, you can store the references in application state. If you create only a single cache instance in your application, use the default cache and get a reference to it from the property when you need to access the cache. ]]> @@ -222,7 +222,7 @@ private void btnGet_Click(object sender, EventArgs e) ## Remarks > [!WARNING] -> The and method overloads do not support the property. Therefore, to set the property for a cache entry, use the method overloads instead. +> The and method overloads do not support the property. Therefore, to set the property for a cache entry, use the method overloads instead. ]]> @@ -277,7 +277,7 @@ private void btnGet_Click(object sender, EventArgs e) The `item` parameter supplies the key and the value that is used by the method. If the cache has a cache entry with the same key as the key of the `item` parameter, the method returns the existing entry as a instance. If there is no existing cache entry, the method creates a new one by using the key and value supplied by the `item` parameter, and with the eviction details specified by `policy`. > [!WARNING] -> The and method overloads do not support the property. Therefore, to set the property for a cache entry, use the method overloads instead. +> The and method overloads do not support the property. Therefore, to set the property for a cache entry, use the method overloads instead. ]]> @@ -329,7 +329,7 @@ private void btnGet_Click(object sender, EventArgs e) If the cache does not have a cache entry whose key matches the `key` parameter, a new cache entry is created, and the method overload returns `null`. If a matching cache entry exists, the existing entry is returned. > [!WARNING] -> The and method overloads do not support the property. Therefore, to set the property for a cache entry, use the method overloads instead. +> The and method overloads do not support the property. Therefore, to set the property for a cache entry, use the method overloads instead. ]]> @@ -383,7 +383,7 @@ private void btnGet_Click(object sender, EventArgs e) ## Remarks > [!WARNING] -> The and method overloads do not support the property. Therefore, to set the property for a cache entry, use the method overloads instead. +> The and method overloads do not support the property. Therefore, to set the property for a cache entry, use the method overloads instead. ]]> @@ -429,11 +429,11 @@ private void btnGet_Click(object sender, EventArgs e) ## Remarks > [!IMPORTANT] -> In .NET Core and .NET 5.0 and later, the property does not have any effect. The underlying implementation for enforcing this limit is not functional outside of .NET Framework. +> In .NET Core and .NET 5.0 and later, the property does not have any effect. The underlying implementation for enforcing this limit is not functional outside of .NET Framework. -In .NET Framework (4.x), if the current instance of the cache exceeds the limit on memory set by the property, the cache implementation removes cache entries. Each cache instance in the application can use the amount of memory that is specified by the property. In .NET Core and later, this property returns the value from configuration or constructor parameters but is not enforced. +In .NET Framework (4.x), if the current instance of the cache exceeds the limit on memory set by the property, the cache implementation removes cache entries. Each cache instance in the application can use the amount of memory that is specified by the property. In .NET Core and later, this property returns the value from configuration or constructor parameters but is not enforced. -You can specify the settings for the property in the application configuration file. Alternatively, they can be passed in the constructor or by a caller when the instance is initialized. +You can specify the settings for the property in the application configuration file. Alternatively, they can be passed in the constructor or by a caller when the instance is initialized. ]]> @@ -701,7 +701,7 @@ You can specify the settings for the method returns it as a instance. The and properties of the instance will be set. However, the property will be `null`, because regions are not implemented in the class. + If the cache entry specified by `key` exists in the cache, the method returns it as a instance. The and properties of the instance will be set. However, the property will be `null`, because regions are not implemented in the class. ]]>
@@ -909,7 +909,7 @@ You can specify the settings for the property returns the name of the current instance of the class. In an application that uses multiple cache instances, you can use the property to help distinguish instances. For more information, see the method. The default memory-based cache returns the default name. + The property returns the name of the current instance of the class. In an application that uses multiple cache instances, you can use the property to help distinguish instances. For more information, see the method. The default memory-based cache returns the default name. ]]>
@@ -938,9 +938,9 @@ You can specify the settings for the property specifies the percentage of total physical memory usage on the system (by all processes) at which the cache will begin to evict entries. This setting is not a limit on the memory that a single instance can use. Instead, when overall system physical memory usage exceeds this percentage, the cache proactively removes entries to help reduce memory pressure and avoid exhausting system memory, even if the cache itself is not over its other size limits. + The property specifies the percentage of total physical memory usage on the system (by all processes) at which the cache will begin to evict entries. This setting is not a limit on the memory that a single instance can use. Instead, when overall system physical memory usage exceeds this percentage, the cache proactively removes entries to help reduce memory pressure and avoid exhausting system memory, even if the cache itself is not over its other size limits. - You can specify the settings for the property in the application configuration file. Alternatively, they can be passed by a caller when the instance is initialized. + You can specify the settings for the property in the application configuration file. Alternatively, they can be passed by a caller when the instance is initialized. ]]>
@@ -970,7 +970,7 @@ You can specify the settings for the property can be specified in the application configuration file. Alternatively they can be passed when the class is initialized. For more information about how to configure this property, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). For more information about how to configure the property when the class is being initialized, see the method. + The settings for the property can be specified in the application configuration file. Alternatively they can be passed when the class is initialized. For more information about how to configure this property, see [<namedCaches> Element (Cache Settings)](/dotnet/framework/configure-apps/file-schema/runtime/namedcaches-element-cache-settings). For more information about how to configure the property when the class is being initialized, see the method. ]]>
@@ -1318,7 +1318,7 @@ You can specify the settings for the property first removes entries that have exceeded either an absolute or sliding expiration. Any callbacks that are registered for items that are removed will be passed a removed reason of . + The property first removes entries that have exceeded either an absolute or sliding expiration. Any callbacks that are registered for items that are removed will be passed a removed reason of . If removing expired entries is insufficient to reach the specified trim percentage, additional entries will be removed from the cache based on a least-recently used (LRU) algorithm until the requested trim percentage is reached. Any callbacks that are registered for items that are removed this way will be passed a remove reason of . diff --git a/xml/System.Runtime.Caching/ObjectCache.xml b/xml/System.Runtime.Caching/ObjectCache.xml index c1df082857b..0ce92e840a0 100644 --- a/xml/System.Runtime.Caching/ObjectCache.xml +++ b/xml/System.Runtime.Caching/ObjectCache.xml @@ -32,24 +32,24 @@ Represents an object cache and provides the base methods and properties for accessing the object cache. - type is the primary type for the in-memory object cache. To develop a custom cache implementation, you derive from the class. - + type is the primary type for the in-memory object cache. To develop a custom cache implementation, you derive from the class. + > [!NOTE] -> The class is new as of the .NET Framework 4. - - The built-in class derives from the class. The class is the only concrete object cache implementation in the .NET Framework 4 that derives from the class. - +> The class is new as of the .NET Framework 4. + + The built-in class derives from the class. The class is the only concrete object cache implementation in the .NET Framework 4 that derives from the class. + ]]> This type is thread safe. - Because the type represents only common cache functions, there is no requirement for how an instance must be instantiated and obtained. In addition, there is no requirement that concrete implementations of the class must be singletons. - + Because the type represents only common cache functions, there is no requirement for how an instance must be instantiated and obtained. In addition, there is no requirement that concrete implementations of the class must be singletons. + Note: is not a singleton, but you should create only a few or potentially only one instance and code that caches items should use those instances. - + When you inherit from the class, you must override its methods. @@ -86,13 +86,13 @@ Note: is not a singleton, bu When overridden in a derived class, inserts a cache entry into the cache, without requiring that an existing cache entry with a matching key be returned. - method overloads try to insert a cache entry into the cache, without overwriting or removing an existing cache entry that has the same key. The cache entry can be a typed object or a generic object. - - The method overloads and the method overloads have one significant difference. When these methods insert a cache entry, if a matching entry is found in the cache, the method overloads return the existing cache entry, but the method overloads do not. Having these different method overloads enables callers to optimize their code based on whether they need the existing cache entry. In distributed caches, returning an existing value by using the method might be more expensive than returning a Boolean value by using method. - + method overloads try to insert a cache entry into the cache, without overwriting or removing an existing cache entry that has the same key. The cache entry can be a typed object or a generic object. + + The method overloads and the method overloads have one significant difference. When these methods insert a cache entry, if a matching entry is found in the cache, the method overloads return the existing cache entry, but the method overloads do not. Having these different method overloads enables callers to optimize their code based on whether they need the existing cache entry. In distributed caches, returning an existing value by using the method might be more expensive than returning a Boolean value by using method. + ]]> @@ -124,11 +124,11 @@ Note: is not a singleton, bu if insertion succeeded, or if there is an already an entry in the cache that has the same key as . - method overloads are virtual (not abstract) on the class, because the method internally calls . This reduces the number of method overloads that a cache implementer has to provide. If a cache implementation does not require any special behavior for the method, it can just implement the method overloads. - + method overloads are virtual (not abstract) on the class, because the method internally calls . This reduces the number of method overloads that a cache implementer has to provide. If a cache implementation does not require any special behavior for the method, it can just implement the method overloads. + ]]> @@ -163,11 +163,11 @@ Note: is not a singleton, bu if insertion succeeded, or if there is an already an entry in the cache that has the same key as . - method overloads are virtual (not abstract) on the class, because the method internally calls . This reduces the number of method overloads that a cache implementer has to provide. If a cache implementation does not require any special behavior for the method, it can just implement the method overloads. - + method overloads are virtual (not abstract) on the class, because the method internally calls . This reduces the number of method overloads that a cache implementer has to provide. If a cache implementation does not require any special behavior for the method, it can just implement the method overloads. + ]]> @@ -202,11 +202,11 @@ Note: is not a singleton, bu if the insertion try succeeds, or if there is an already an entry in the cache with the same key as . - method overloads are virtual (not abstract) on the class, because the method internally calls . This reduces the number of method overloads that a cache implementer has to provide. If a cache implementation does not require any special behavior for the method, it can just implement the method overloads. - + method overloads are virtual (not abstract) on the class, because the method internally calls . This reduces the number of method overloads that a cache implementer has to provide. If a cache implementation does not require any special behavior for the method, it can just implement the method overloads. + ]]> @@ -219,13 +219,13 @@ Note: is not a singleton, bu When overridden in a derived class, tries to insert a cache entry into the cache, and returns an existing cache entry with a matching key. - method overloads insert an entry into the cache. If a cache entry with a matching key already exists, they return the existing entry. The cache entry can be a object or a generic object. - - There is one difference between the overloads and the overloads. When these overloaded methods try to insert a cache entry, if an existing entry is found that has a key that matches an existing inserted cache entry, the overloads return the existing cache entry. The overloads do not. - + method overloads insert an entry into the cache. If a cache entry with a matching key already exists, they return the existing entry. The cache entry can be a object or a generic object. + + There is one difference between the overloads and the overloads. When these overloaded methods try to insert a cache entry, if an existing entry is found that has a key that matches an existing inserted cache entry, the overloads return the existing cache entry. The overloads do not. + ]]> @@ -287,11 +287,11 @@ Note: is not a singleton, bu When overridden in a derived class, inserts a cache entry into the cache, by using a key, an object for the cache entry, an absolute expiration value, and an optional region to add the cache into. If a cache entry with the same key exists, the specified cache entry's value; otherwise, . - method overload returns an object value, not a object. - + method overload returns an object value, not a object. + ]]> @@ -325,11 +325,11 @@ Note: is not a singleton, bu When overridden in a derived class, inserts a cache entry into the cache, specifying a key and a value for the cache entry, and information about how the entry will be evicted. If a cache entry with the same key exists, the specified cache entry's value; otherwise, . - method returns an object value, not a object. - + method returns an object value, not a object. + ]]> @@ -387,16 +387,16 @@ Note: is not a singleton, bu When overridden in a derived class, creates a object that can trigger events in response to changes to specified cache entries. A change monitor that monitors cache entries in the cache. - class overrides the base method, the cache implementation must create a object. This specialized change monitor notifies callers when there are changes to the cache entries that are specified in the `keys` parameter. For example, if a monitored item in the `keys` parameter is updated or removed from the cache, the change monitor created by this method triggers an event. - - If a cache implementation supports named cache regions, a string value can be specified as the `regionName` parameter. Otherwise, the parameter defaults to `null`. - + class overrides the base method, the cache implementation must create a object. This specialized change monitor notifies callers when there are changes to the cache entries that are specified in the `keys` parameter. For example, if a monitored item in the `keys` parameter is updated or removed from the cache, the change monitor created by this method triggers an event. + + If a cache implementation supports named cache regions, a string value can be specified as the `regionName` parameter. Otherwise, the parameter defaults to `null`. + > [!NOTE] -> Not all cache implementations support cache-entry change monitors. To determine whether your cache implementation supports objects, see the documentation for the specific cache implementation. - +> Not all cache implementations support cache-entry change monitors. To determine whether your cache implementation supports objects, see the documentation for the specific cache implementation. + ]]> @@ -475,13 +475,13 @@ Note: is not a singleton, bu When overridden in a derived class, gets the specified cache entry from the cache as a instance. The cache entry that is identified by . - class. In that case, the method overload will not necessarily return all the information about cached data. However, the method overload enables custom caches to return more than just the cache value. - - The method is like the method, except that the method returns return the cache entry as a instance. - + class. In that case, the method overload will not necessarily return all the information about cached data. However, the method overload enables custom caches to return more than just the cache value. + + The method is like the method, except that the method returns return the cache entry as a instance. + ]]> @@ -535,16 +535,16 @@ Note: is not a singleton, bu When overridden in a derived class, creates an enumerator that can be used to iterate through a collection of cache entries. The enumerator object that provides access to the cache entries in the cache. - [!NOTE] -> Returning an enumerator is typically a more expensive operation than returning the entire cache entry. - - This method is called by the explicit interface implementations that the class has for the and methods. - +> Returning an enumerator is typically a more expensive operation than returning the entire cache entry. + + This method is called by the explicit interface implementations that the class has for the and methods. + ]]> @@ -583,13 +583,13 @@ Note: is not a singleton, bu When overridden in a derived class, gets a set of cache entries that correspond to the specified keys. A dictionary of key/value pairs that represent cache entries. - method overload is a performance optimization for distributed caches that support fetching multiple cache entries from the cache during a single network call. - - Although a caller can pass one or more keys to the method, there is no guarantee that all keys represent entries in the cache. Therefore, the returned dictionary might contain fewer items than the number of keys that were passed to the method. - + method overload is a performance optimization for distributed caches that support fetching multiple cache entries from the cache during a single network call. + + Although a caller can pass one or more keys to the method, there is no guarantee that all keys represent entries in the cache. Therefore, the returned dictionary might contain fewer items than the number of keys that were passed to the method. + ]]> @@ -633,13 +633,13 @@ Note: is not a singleton, bu Gets a set of cache entries that correspond to the specified keys. A dictionary of key/value pairs that represent cache entries. - method overload is like the method overload, but lets you pass the named region by using optional parameter syntax that is supported by managed languages such as C#. - - This method is a virtual method because the class provides a default implementation that passes the `params` array to the method overload. - + method overload is like the method overload, but lets you pass the named region by using optional parameter syntax that is supported by managed languages such as C#. + + This method is a virtual method because the class provides a default implementation that passes the `params` array to the method overload. + ]]> @@ -678,22 +678,22 @@ Note: is not a singleton, bu Gets or sets a reference to a managed hosting environment that is available to implementations and that can provide host-specific services to implementations. A reference to a cache-aware managed hosting environment. - property is intended for use by .NET Framework host environments and by cache implementations that implement behavior that depends on the .NET Framework host environment. - - The following table lists the set of host environment services that might be available from a managed hosting environment and that are available to implementations through the property: - -|Service|Description| -|-------------|-----------------| -||Lets host environments provide application domain identifiers that might be needed by a cache implementation for features such as identifying performance counters.| -||Lets host environments provide a custom file-change notification system, instead of using the one provided in the .NET Framework.| -||Lets cache implementations report cache memory consumption to the host environment. This enables host environments to centrally manage memory consumption across multiple cache implementations.| - + property is intended for use by .NET Framework host environments and by cache implementations that implement behavior that depends on the .NET Framework host environment. + + The following table lists the set of host environment services that might be available from a managed hosting environment and that are available to implementations through the property: + +|Service|Description| +|-------------|-----------------| +||Lets host environments provide application domain identifiers that might be needed by a cache implementation for features such as identifying performance counters.| +||Lets host environments provide a custom file-change notification system, instead of using the one provided in the .NET Framework.| +||Lets cache implementations report cache memory consumption to the host environment. This enables host environments to centrally manage memory consumption across multiple cache implementations.| + > [!NOTE] -> Callers of this property value require unrestricted code access security permissions. - +> Callers of this property value require unrestricted code access security permissions. + ]]> The value being assigned to the property is . @@ -719,11 +719,11 @@ Note: is not a singleton, bu Gets a value that indicates that a cache entry has no absolute expiration. - field value set as the expiration value should never expire based on an absolute point in time. However, a cache entry with this setting can be evicted from the cache for other reasons that are determined by a particular cache implementation, such as a change-monitor event eviction caused by memory pressure. - + field value set as the expiration value should never expire based on an absolute point in time. However, a cache entry with this setting can be evicted from the cache for other reasons that are determined by a particular cache implementation, such as a change-monitor event eviction caused by memory pressure. + ]]> @@ -752,13 +752,13 @@ Note: is not a singleton, bu Gets or sets the default indexer for the class. A key that serves as an indexer into the cache instance. - method. Internally, a cache implementation could set the absolute expiration of the specified value to the method. However this behavior is ultimately up to the cache implementation. - - The behavior of get accessor is like calling the method and using `null` for the region name. - + method. Internally, a cache implementation could set the absolute expiration of the specified value to the method. However this behavior is ultimately up to the cache implementation. + + The behavior of get accessor is like calling the method and using `null` for the region name. + ]]> @@ -783,11 +783,11 @@ Note: is not a singleton, bu Gets the name of a specific instance. The name of a specific cache instance. - @@ -811,13 +811,13 @@ Note: is not a singleton, bu Indicates that a cache entry has no sliding expiration time. - field value set as the expiration value should never be evicted because of non-activity in a sliding time window. However, a cache item can be evicted if it has an absolute expiration, or if some other eviction event occurs, such a change monitor or memory pressure. - + field value set as the expiration value should never be evicted because of non-activity in a sliding time window. However, a cache item can be evicted if it has an absolute expiration, or if some other eviction event occurs, such a change monitor or memory pressure. + ]]> @@ -847,14 +847,14 @@ Note: is not a singleton, bu When overridden in a derived class, removes the cache entry from the cache. An object that represents the value of the removed cache entry that was specified by the key, or if the specified entry was not found. - [!NOTE] -> Some distributed cache implementations might not support the ability to return the value that was removed from the cache. This might be because the cache implementation does not support returning the value of a removed cache item. It might also be because marshaling the object as a return value is too expensive. In such cases, cache implementations can return `null`. - +> Some distributed cache implementations might not support the ability to return the value that was removed from the cache. This might be because the cache implementation does not support returning the value of a removed cache item. It might also be because marshaling the object as a return value is too expensive. In such cases, cache implementations can return `null`. + ]]> @@ -867,11 +867,11 @@ Note: is not a singleton, bu When overridden in a derived class, inserts a cache entry into the cache. - overload methods is an insert-or-update operation. A cache entry is either inserted as a new entry if the specified entry does not exist, or the cache entry is updated with a new value if it already exists. - + overload methods is an insert-or-update operation. A cache entry is either inserted as a new entry if the specified entry does not exist, or the cache entry is updated with a new value if it already exists. + ]]> @@ -901,11 +901,11 @@ Note: is not a singleton, bu An object that contains eviction details for the cache entry. This object provides more options for eviction than a simple absolute expiration. When overridden in a derived class, inserts the cache entry into the cache as a instance, specifying information about how the entry will be evicted. - @@ -938,11 +938,11 @@ Note: is not a singleton, bu Optional. A named region in the cache to which the cache entry can be added, if regions are implemented. The default value for the optional parameter is . When overridden in a derived class, inserts a cache entry into the cache, specifying time-based expiration details. - @@ -975,13 +975,13 @@ Note: is not a singleton, bu Optional. A named region in the cache to which the cache entry can be added, if regions are implemented. The default value for the optional parameter is . When overridden in a derived class, inserts a cache entry into the cache. - @@ -1042,15 +1042,15 @@ Note: is not a singleton, bu Supports iteration over a generic collection. The enumerator object that provides access to the items in the cache. - instance is cast to an interface. - - Developers can use this method to iterate through a generic collection of cache entries. - - This is the default implementation that internally calls the method. - + instance is cast to an interface. + + Developers can use this method to iterate through a generic collection of cache entries. + + This is the default implementation that internally calls the method. + ]]> diff --git a/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2.xml b/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2.xml index 82af8cf60ad..389c82ce934 100644 --- a/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2.xml +++ b/xml/System.Runtime.CompilerServices/ConditionalWeakTable`2.xml @@ -130,7 +130,7 @@ ## Examples - The following example illustrates that a key stored in the table does not persist after references to it outside the table are destroyed. The example defines two classes: `ManagedClass`, which represents the key in the table, and `ClassData`, which represents the key's value. The example instantiates three objects of each type. It also instantiates a object that represents the second `ManagedClass`, and then destroys the second `ManagedClass` instance. The attempt to retrieve the second `ManagedClass` object from the property indicates that no references to the object remain. + The following example illustrates that a key stored in the table does not persist after references to it outside the table are destroyed. The example defines two classes: `ManagedClass`, which represents the key in the table, and `ClassData`, which represents the key's value. The example instantiates three objects of each type. It also instantiates a object that represents the second `ManagedClass`, and then destroys the second `ManagedClass` instance. The attempt to retrieve the second `ManagedClass` object from the property indicates that no references to the object remain. :::code language="csharp" source="~/snippets/csharp/System.Runtime.CompilerServices/ConditionalWeakTableTKey,TValue/Overview/example1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Runtime.CompilerServices/ConditionalWeakTableTKey,TValue/Overview/example1.vb" id="Snippet1"::: diff --git a/xml/System.Runtime.CompilerServices/ITuple.xml b/xml/System.Runtime.CompilerServices/ITuple.xml index 43854d12bba..a259c739d4d 100644 --- a/xml/System.Runtime.CompilerServices/ITuple.xml +++ b/xml/System.Runtime.CompilerServices/ITuple.xml @@ -40,13 +40,13 @@ Defines a general-purpose Tuple implementation that allows access to Tuple instance members without knowing the underlying Tuple type. - property. You can then enumerate its elements by passing an index that ranges from zero to one less than value of the property to the property. - - `ITuple` is an explicit interface implementation of the `Tuple` classes and the `ValueTuple` structures. You must cast the `Tuple` object to an `ITuple` interface object before you can access its properties. - + property. You can then enumerate its elements by passing an index that ranges from zero to one less than value of the property to the property. + + `ITuple` is an explicit interface implementation of the `Tuple` classes and the `ValueTuple` structures. You must cast the `Tuple` object to an `ITuple` interface object before you can access its properties. + ]]> diff --git a/xml/System.Runtime.CompilerServices/RuntimeWrappedException.xml b/xml/System.Runtime.CompilerServices/RuntimeWrappedException.xml index ae2c34c3f86..53939d306ae 100644 --- a/xml/System.Runtime.CompilerServices/RuntimeWrappedException.xml +++ b/xml/System.Runtime.CompilerServices/RuntimeWrappedException.xml @@ -217,7 +217,7 @@ property gets an object that was thrown as an exception from a language that allows exceptions that do not derive from the class. + The property gets an object that was thrown as an exception from a language that allows exceptions that do not derive from the class. ]]> diff --git a/xml/System.Runtime.DurableInstancing/InstanceCollisionException.xml b/xml/System.Runtime.DurableInstancing/InstanceCollisionException.xml index f52179e74e2..3ee9bfdf492 100644 --- a/xml/System.Runtime.DurableInstancing/InstanceCollisionException.xml +++ b/xml/System.Runtime.DurableInstancing/InstanceCollisionException.xml @@ -22,11 +22,11 @@ A persistence provider throws this exception when it expects an instance to be in an uninitialized state but the instance is not in that state. - @@ -144,11 +144,11 @@ The exception that caused the current exception. Initializes an instance of the class using the error message and the inner exception information. - property. - + property. + ]]> diff --git a/xml/System.Runtime.DurableInstancing/InstanceLockedException.xml b/xml/System.Runtime.DurableInstancing/InstanceLockedException.xml index 258ba537e02..df3ef3b585c 100644 --- a/xml/System.Runtime.DurableInstancing/InstanceLockedException.xml +++ b/xml/System.Runtime.DurableInstancing/InstanceLockedException.xml @@ -136,7 +136,7 @@ property. + An exception that is thrown as a result of a previous exception typically includes a reference to the previous exception in the property. ]]> diff --git a/xml/System.Runtime.Hosting/ActivationArguments.xml b/xml/System.Runtime.Hosting/ActivationArguments.xml index b08288bef20..2dc8e68a0df 100644 --- a/xml/System.Runtime.Hosting/ActivationArguments.xml +++ b/xml/System.Runtime.Hosting/ActivationArguments.xml @@ -34,21 +34,21 @@ Provides data for manifest-based activation of an application. This class cannot be inherited. - class is used by the class. - - The manifest-based activation model uses an application manifest rather than an assembly for activation. A manifest fully describes the application, its dependencies, security requirements, and so forth. The manifest model has several advantages over the assembly-based activation model, especially for Web applications. For example, the manifest contains the security requirements of the application, which enables the user to decide whether to allow the application to execute before downloading the code. The manifest also contains information about the application dependencies. - - - -## Examples - The following code example shows how to obtain the current object from the for the of a manifest-based application. - + class is used by the class. + + The manifest-based activation model uses an application manifest rather than an assembly for activation. A manifest fully describes the application, its dependencies, security requirements, and so forth. The manifest model has several advantages over the assembly-based activation model, especially for Web applications. For example, the manifest contains the security requirements of the application, which enables the user to decide whether to allow the application to execute before downloading the code. The manifest also contains information about the application dependencies. + + + +## Examples + The following code example shows how to obtain the current object from the for the of a manifest-based application. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Hosting/ActivationArguments/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Hosting/ActivationArguments/Overview/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Hosting/ActivationArguments/Overview/program.vb" id="Snippet1"::: + ]]> @@ -83,11 +83,11 @@ An object that identifies the manifest-based activation application. Initializes a new instance of the class with the specified activation context. - object represented by the `activationData` parameter contains the and context information for manifest-based activation. - + object represented by the `activationData` parameter contains the and context information for manifest-based activation. + ]]> @@ -114,11 +114,11 @@ An object that identifies the manifest-based activation application. Initializes a new instance of the class with the specified application identity. - @@ -147,11 +147,11 @@ An array of strings containing host-provided activation data. Initializes a new instance of the class with the specified activation context and activation data. - object represented by the `activationContext` parameter contains the and context information for manifest-based activation. The activation data consists of information such as the query string portion of a URL. - + object represented by the `activationContext` parameter contains the and context information for manifest-based activation. The activation data consists of information such as the query string portion of a URL. + ]]> @@ -180,11 +180,11 @@ An array of strings containing host-provided activation data. Initializes a new instance of the class with the specified application identity and activation data. - @@ -211,21 +211,21 @@ Gets the activation context for manifest-based activation of an application. An object that identifies a manifest-based activation application. - object contains an and provides internal-only access to the application manifest. The activation context is used during manifest-based activation to set up the domain policy and provide an application-based security model. - - - -## Examples - The following code example shows how to obtain the value of the property from the for a manifest-based application. - - This code example is part of a larger example provided for the class. - + object contains an and provides internal-only access to the application manifest. The activation context is used during manifest-based activation to set up the domain policy and provide an application-based security model. + + + +## Examples + The following code example shows how to obtain the value of the property from the for a manifest-based application. + + This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Hosting/ActivationArguments/Overview/program.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Hosting/ActivationArguments/Overview/program.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Hosting/ActivationArguments/Overview/program.vb" id="Snippet4"::: + ]]> @@ -250,11 +250,11 @@ Gets activation data from the host. An array of strings containing host-provided activation data. - @@ -279,11 +279,11 @@ Gets the application identity for a manifest-activated application. An object that identifies an application for manifest-based activation. - @@ -308,11 +308,11 @@ Produces a copy of the current object. A copy of the current object. - object, and then populates it with copies of the members of the current object - + object, and then populates it with copies of the members of the current object + ]]> diff --git a/xml/System.Runtime.Hosting/ApplicationActivator.xml b/xml/System.Runtime.Hosting/ApplicationActivator.xml index 9a30e108cd7..47105bb2fc3 100644 --- a/xml/System.Runtime.Hosting/ApplicationActivator.xml +++ b/xml/System.Runtime.Hosting/ApplicationActivator.xml @@ -24,45 +24,45 @@ Provides the base class for the activation of manifest-based assemblies. - class in each to which all activation calls are routed. The for the current can provide its own custom for this purpose. If a custom is not provided, an instance of the default is created. - - The following steps describe the behavior of the default method implementation: - -1. Checks if the of the add-in to be activated matches the of the current domain; if not, proceeds to step 2. Otherwise, executes the assembly and returns the result wrapped in an object handle. - -2. Activates the add-in in a new . The following steps are taken to initialize a new using the for the add-in. - - 1. Creates a new object using an object containing the activation context for the add-in. - - 2. Calls the method to create a new domain using the object. - - 3. The method calls the method to acquire an object for the add-in. If the property returns `true`, the add-in is executed. If not, throws a indicating that execution permission could not be acquired. - - 4. If the add-in is trusted to run, then a new is created and configured for the of the add-in, and the add-in is loaded and executed. - - 5. The result of the activation of the add-in is returned, wrapped in an object handle. - - A custom activator can tailor the activation of an add-in to a particular set of circumstances. For example, a custom activator could find an existing to activate this add-in instead of creating a new domain every time. - - The following steps describe the behavior of a custom that activates an add-in in an existing : - -1. The custom activator finds a domain that has the same as the add-in that is being activated. - -2. If the has never been seen before in the process, the custom activator creates a new for this by calling the method directly, or delegating this activity to the in the base class. - -3. If there is an existing domain with the same , then the activator can delegate the method call to the in the target domain. Note that this would be a cross-domain call to an that resides in the target . - - - -## Examples - The following code example shows how to obtain an object from the current for a manifest-based application. - + class in each to which all activation calls are routed. The for the current can provide its own custom for this purpose. If a custom is not provided, an instance of the default is created. + + The following steps describe the behavior of the default method implementation: + +1. Checks if the of the add-in to be activated matches the of the current domain; if not, proceeds to step 2. Otherwise, executes the assembly and returns the result wrapped in an object handle. + +2. Activates the add-in in a new . The following steps are taken to initialize a new using the for the add-in. + + 1. Creates a new object using an object containing the activation context for the add-in. + + 2. Calls the method to create a new domain using the object. + + 3. The method calls the method to acquire an object for the add-in. If the property returns `true`, the add-in is executed. If not, throws a indicating that execution permission could not be acquired. + + 4. If the add-in is trusted to run, then a new is created and configured for the of the add-in, and the add-in is loaded and executed. + + 5. The result of the activation of the add-in is returned, wrapped in an object handle. + + A custom activator can tailor the activation of an add-in to a particular set of circumstances. For example, a custom activator could find an existing to activate this add-in instead of creating a new domain every time. + + The following steps describe the behavior of a custom that activates an add-in in an existing : + +1. The custom activator finds a domain that has the same as the add-in that is being activated. + +2. If the has never been seen before in the process, the custom activator creates a new for this by calling the method directly, or delegating this activity to the in the base class. + +3. If there is an existing domain with the same , then the activator can delegate the method call to the in the target domain. Note that this would be a cross-domain call to an that resides in the target . + + + +## Examples + The following code example shows how to obtain an object from the current for a manifest-based application. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Hosting/ActivationArguments/Overview/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Hosting/ActivationArguments/Overview/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Hosting/ActivationArguments/Overview/program.vb" id="Snippet1"::: + ]]> @@ -119,11 +119,11 @@ Creates an instance of the application to be activated, using the specified activation context. An that is a wrapper for the return value of the application execution. The return value must be unwrapped to access the real object. - @@ -162,11 +162,11 @@ Creates an instance of the application to be activated, using the specified activation context and custom activation data. An that is a wrapper for the return value of the application execution. The return value must be unwrapped to access the real object. - @@ -203,11 +203,11 @@ Creates an instance of an application using the specified object. An that is a wrapper for the return value of the application execution. The return value must be unwrapped to access the real object. - The property of is . diff --git a/xml/System.Runtime.InteropServices.WindowsRuntime/EventRegistrationTokenTable`1.xml b/xml/System.Runtime.InteropServices.WindowsRuntime/EventRegistrationTokenTable`1.xml index d15c7634fed..2fa49620a6c 100644 --- a/xml/System.Runtime.InteropServices.WindowsRuntime/EventRegistrationTokenTable`1.xml +++ b/xml/System.Runtime.InteropServices.WindowsRuntime/EventRegistrationTokenTable`1.xml @@ -34,13 +34,13 @@ The type of the event handler delegate for a particular event. Stores mappings between delegates and event tokens, to support the implementation of a Windows Runtime event in managed code. - property, if it is not `null`. An instance of this table is required for each event. - + property, if it is not `null`. An instance of this table is required for each event. + ]]> @@ -135,11 +135,11 @@ Returns the specified event registration token table, if it is not ; otherwise, returns a new event registration token table. The event registration token table that is specified by , if it is not ; otherwise, a new event registration token table. - method to initialize an event registration token table in scenarios where any of several threads can create the table. If this method is called on multiple threads at the same time, the same event registration token table is returned on all threads. - + method to initialize an event registration token table in scenarios where any of several threads can create the table. If this method is called on multiple threads at the same time, the same event registration token table is returned on all threads. + ]]> @@ -212,11 +212,11 @@ The token that was returned when the event handler was added. Removes the event handler that is associated with the specified token from the table and the invocation list. - @@ -251,11 +251,11 @@ The event handler to remove. Removes the specified event handler delegate from the table and the invocation list. - diff --git a/xml/System.Runtime.InteropServices.WindowsRuntime/NamespaceResolveEventArgs.xml b/xml/System.Runtime.InteropServices.WindowsRuntime/NamespaceResolveEventArgs.xml index bc113ec7fb7..9ee0df2539f 100644 --- a/xml/System.Runtime.InteropServices.WindowsRuntime/NamespaceResolveEventArgs.xml +++ b/xml/System.Runtime.InteropServices.WindowsRuntime/NamespaceResolveEventArgs.xml @@ -109,11 +109,11 @@ Gets a collection of assemblies; when the event handler for the event is invoked, the collection is empty, and the event handler is responsible for adding the necessary assemblies. A collection of assemblies that define the requested namespace. - property. - + property. + ]]> diff --git a/xml/System.Runtime.InteropServices/Architecture.xml b/xml/System.Runtime.InteropServices/Architecture.xml index 1c688acb9ae..13123a94419 100644 --- a/xml/System.Runtime.InteropServices/Architecture.xml +++ b/xml/System.Runtime.InteropServices/Architecture.xml @@ -57,9 +57,9 @@ ## Remarks A member of the enumeration is returned by the following properties: -- The property. +- The property. -- The property. +- The property. ]]>
diff --git a/xml/System.Runtime.InteropServices/COMException.xml b/xml/System.Runtime.InteropServices/COMException.xml index abe498b4e9f..eb884081099 100644 --- a/xml/System.Runtime.InteropServices/COMException.xml +++ b/xml/System.Runtime.InteropServices/COMException.xml @@ -327,7 +327,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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. diff --git a/xml/System.Runtime.InteropServices/CriticalHandle.xml b/xml/System.Runtime.InteropServices/CriticalHandle.xml index 12d5af18631..89230102cde 100644 --- a/xml/System.Runtime.InteropServices/CriticalHandle.xml +++ b/xml/System.Runtime.InteropServices/CriticalHandle.xml @@ -569,7 +569,7 @@ method returns a value indicating whether the object's handle is no longer associated with a native resource. This differs from the definition of the property, which computes whether a given handle is always considered invalid. The method returns a `true` value in the following cases: + The method returns a value indicating whether the object's handle is no longer associated with a native resource. This differs from the definition of the property, which computes whether a given handle is always considered invalid. The method returns a `true` value in the following cases: - The method was called. @@ -638,9 +638,9 @@ property so that the common language runtime can determine whether critical finalization is required. Derived classes must provide an implementation that suits the general type of handle they support (0 or -1 is invalid). These classes can then be further derived for specific safe handle types. + Derived classes must implement the property so that the common language runtime can determine whether critical finalization is required. Derived classes must provide an implementation that suits the general type of handle they support (0 or -1 is invalid). These classes can then be further derived for specific safe handle types. - Unlike the property, which reports whether the object has finished using the underlying handle, the property calculates whether the given handle value is always considered invalid. Therefore, the property always returns the same value for any one handle value. + Unlike the property, which reports whether the object has finished using the underlying handle, the property calculates whether the given handle value is always considered invalid. Therefore, the property always returns the same value for any one handle value. ]]> @@ -706,7 +706,7 @@ method is guaranteed to be called only once, provided that you employ proper synchronization mechanisms to ensure that only one call to the or method is made. The method will not be called if the or property is `true`. Implement this method in your derived classes to execute any code that is required to free the handle. Because one of the functions of is to guarantee prevention of resource leaks, the code in your implementation of must never fail. The garbage collector calls after normal finalizers have been run for objects that were garbage collected at the same time, and guarantees the resources to invoke it and that it will not be interrupted while it is in progress. This method will be prepared as a constrained execution region (CER) at instance construction time (along with all the methods in its statically determinable call graph). Although this prevents thread abort interrupts, you must still be careful not to introduce any fault paths in your overridden method. In particular, apply the attribute to any methods you call from . In most cases this code should be: + The method is guaranteed to be called only once, provided that you employ proper synchronization mechanisms to ensure that only one call to the or method is made. The method will not be called if the or property is `true`. Implement this method in your derived classes to execute any code that is required to free the handle. Because one of the functions of is to guarantee prevention of resource leaks, the code in your implementation of must never fail. The garbage collector calls after normal finalizers have been run for objects that were garbage collected at the same time, and guarantees the resources to invoke it and that it will not be interrupted while it is in progress. This method will be prepared as a constrained execution region (CER) at instance construction time (along with all the methods in its statically determinable call graph). Although this prevents thread abort interrupts, you must still be careful not to introduce any fault paths in your overridden method. In particular, apply the attribute to any methods you call from . In most cases this code should be: `ReliabilityContract(Consistency.WillNotCorruptState, Cer.Success)` diff --git a/xml/System.Runtime.InteropServices/ExternalException.xml b/xml/System.Runtime.InteropServices/ExternalException.xml index 8561fc1b872..d1a571874ad 100644 --- a/xml/System.Runtime.InteropServices/ExternalException.xml +++ b/xml/System.Runtime.InteropServices/ExternalException.xml @@ -64,7 +64,7 @@ property stores an integer value (HRESULT) that identifies the error. User defined exceptions should never derive from `ExternalException`, and an `ExternalException` should never be thrown by user code. Use the specific exceptions that derive from `ExternalException` instead. + To enhance interoperability between legacy systems and the common language runtime, the property stores an integer value (HRESULT) that identifies the error. User defined exceptions should never derive from `ExternalException`, and an `ExternalException` should never be thrown by user code. Use the specific exceptions that derive from `ExternalException` instead. `ExternalException` uses the HRESULT E_FAIL, which has the value 0x80004005. @@ -306,7 +306,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Runtime.InteropServices/InvalidComObjectException.xml b/xml/System.Runtime.InteropServices/InvalidComObjectException.xml index ec14af76af1..8a355487b1e 100644 --- a/xml/System.Runtime.InteropServices/InvalidComObjectException.xml +++ b/xml/System.Runtime.InteropServices/InvalidComObjectException.xml @@ -335,7 +335,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml b/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml index 07340d63c44..dec18e7471c 100644 --- a/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml +++ b/xml/System.Runtime.InteropServices/InvalidOleVariantTypeException.xml @@ -333,7 +333,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Runtime.InteropServices/Marshal.xml b/xml/System.Runtime.InteropServices/Marshal.xml index 4a09d19ddcc..47d52a67bc2 100644 --- a/xml/System.Runtime.InteropServices/Marshal.xml +++ b/xml/System.Runtime.InteropServices/Marshal.xml @@ -2798,7 +2798,7 @@ provides the same functionality as the property. + If the type has a GUID in the metadata, it is returned. Otherwise, a GUID is automatically generated. You can use this method to programmatically determine the COM GUID for any managed type, including COM-invisible types. Class interfaces are the only exception because they do not correspond to a managed type. provides the same functionality as the property. ]]> diff --git a/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml b/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml index b0969c6582d..303e888acb6 100644 --- a/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml +++ b/xml/System.Runtime.InteropServices/MarshalDirectiveException.xml @@ -331,7 +331,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Runtime.InteropServices/ProgIdAttribute.xml b/xml/System.Runtime.InteropServices/ProgIdAttribute.xml index 47521052f0a..59926c39157 100644 --- a/xml/System.Runtime.InteropServices/ProgIdAttribute.xml +++ b/xml/System.Runtime.InteropServices/ProgIdAttribute.xml @@ -60,22 +60,22 @@ Allows the user to specify the ProgID of a class. - . - - - -## Examples - The following example demonstrates how to apply `ProgIdAttribute` on a class. The application then gets all attributes of `MyClass`, and prints the property of `ProgIdAttribute`. - + . + + + +## Examples + The following example demonstrates how to apply `ProgIdAttribute` on a class. The application then gets all attributes of `MyClass`, and prints the property of `ProgIdAttribute`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ProgIdAttribute_Value/CPP/progidattribute_value.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/ProgIdAttribute/Overview/progidattribute_value.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.InteropServices/ProgIdAttribute/Overview/progidattribute_value.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.InteropServices/ProgIdAttribute/Overview/progidattribute_value.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.InteropServices/RuntimeEnvironment.xml b/xml/System.Runtime.InteropServices/RuntimeEnvironment.xml index 862a6100bee..7be2a6467b1 100644 --- a/xml/System.Runtime.InteropServices/RuntimeEnvironment.xml +++ b/xml/System.Runtime.InteropServices/RuntimeEnvironment.xml @@ -479,7 +479,7 @@ The following table shows the supported combinations for `clsid` and `riid`. property. This code example is part of a larger example provided for the class. + The following code example demonstrates the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/RuntimeEnvironment/cpp/RuntimeEnvironment.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.InteropServices/RuntimeEnvironment/Overview/RuntimeEnvironment.cs" id="Snippet5"::: diff --git a/xml/System.Runtime.InteropServices/SEHException.xml b/xml/System.Runtime.InteropServices/SEHException.xml index 5779d3f20a6..65ac630d8fb 100644 --- a/xml/System.Runtime.InteropServices/SEHException.xml +++ b/xml/System.Runtime.InteropServices/SEHException.xml @@ -370,7 +370,7 @@ catch(…) 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml b/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml index 23d6e8e39e9..625c610c81f 100644 --- a/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml +++ b/xml/System.Runtime.InteropServices/SafeArrayRankMismatchException.xml @@ -335,7 +335,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Runtime.InteropServices/SafeArrayTypeMismatchException.xml b/xml/System.Runtime.InteropServices/SafeArrayTypeMismatchException.xml index aa2bbd42da0..cae6b997cc6 100644 --- a/xml/System.Runtime.InteropServices/SafeArrayTypeMismatchException.xml +++ b/xml/System.Runtime.InteropServices/SafeArrayTypeMismatchException.xml @@ -333,7 +333,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Runtime.InteropServices/SafeHandle.xml b/xml/System.Runtime.InteropServices/SafeHandle.xml index 984234012cf..9372e08d525 100644 --- a/xml/System.Runtime.InteropServices/SafeHandle.xml +++ b/xml/System.Runtime.InteropServices/SafeHandle.xml @@ -807,7 +807,7 @@ If this call is successful, it will set the `ref bool success` parameter to `tru method returns a value indicating whether the object's handle is no longer associated with a native resource. This differs from the definition of the property, which computes whether a given handle is always considered invalid. The method returns a `true` value in the following cases: + The method returns a value indicating whether the object's handle is no longer associated with a native resource. This differs from the definition of the property, which computes whether a given handle is always considered invalid. The method returns a `true` value in the following cases: - The method was called. @@ -875,9 +875,9 @@ If this call is successful, it will set the `ref bool success` parameter to `tru property so that the common language runtime can determine whether critical finalization is required. Derived classes must provide an implementation that suits the general type of handle they support (0 or -1 is invalid). These classes can then be further derived for specific safe handle types. + Derived classes must implement the property so that the common language runtime can determine whether critical finalization is required. Derived classes must provide an implementation that suits the general type of handle they support (0 or -1 is invalid). These classes can then be further derived for specific safe handle types. - Unlike the property, which reports whether the object has finished using the underlying handle, the property calculates whether the given handle value is always considered invalid. Therefore, the property always returns the same value for any one handle value. + Unlike the property, which reports whether the object has finished using the underlying handle, the property calculates whether the given handle value is always considered invalid. Therefore, the property always returns the same value for any one handle value. @@ -949,7 +949,7 @@ If this call is successful, it will set the `ref bool success` parameter to `tru method is guaranteed to be called only once and only if the handle is valid as defined by the property. Implement this method in your derived classes to execute any code that is required to free the handle. Because one of the functions of is to guarantee prevention of resource leaks, the code in your implementation of must never fail. The garbage collector calls after normal finalizers have been run for objects that were garbage collected at the same time. The garbage collector guarantees the resources to invoke this method and that the method will not be interrupted while it is in progress. + The method is guaranteed to be called only once and only if the handle is valid as defined by the property. Implement this method in your derived classes to execute any code that is required to free the handle. Because one of the functions of is to guarantee prevention of resource leaks, the code in your implementation of must never fail. The garbage collector calls after normal finalizers have been run for objects that were garbage collected at the same time. The garbage collector guarantees the resources to invoke this method and that the method will not be interrupted while it is in progress. Additionally, for simple cleanup (for example, calling the Windows API `CloseHandle` on a file handle) you can check the return value for the single platform invoke call. For complex cleanup, you may have a lot of program logic and many method calls, some of which might fail. You must ensure that your program logic has fallback code for each of those cases. diff --git a/xml/System.Runtime.InteropServices/_Assembly.xml b/xml/System.Runtime.InteropServices/_Assembly.xml index aa57de70614..e6d95c9cdeb 100644 --- a/xml/System.Runtime.InteropServices/_Assembly.xml +++ b/xml/System.Runtime.InteropServices/_Assembly.xml @@ -42,13 +42,13 @@ Exposes the public members of the class to unmanaged code. - class members that can be accessed by unmanaged COM objects. - + class members that can be accessed by unmanaged COM objects. + ]]> @@ -75,13 +75,13 @@ Provides COM objects with version-independent access to the property. The location of the assembly as specified originally. - property gets the location of the assembly as specified originally, for example, in an object. - + property gets the location of the assembly as specified originally, for example, in an object. + ]]> @@ -96,13 +96,13 @@ Provides COM objects with version-independent access to the methods. - methods locate a type from this assembly and create an instance of it using the system activator. - + methods locate a type from this assembly and create an instance of it using the system activator. + ]]> @@ -133,13 +133,13 @@ Provides COM objects with version-independent access to the method. An instance of representing the type, with culture, arguments, binder, and activation attributes set to , and set to Public or Instance, or if is not found. - method locates the specified type from this assembly and creates an instance of it using the system activator, using case-sensitive search. - + method locates the specified type from this assembly and creates an instance of it using the system activator, using case-sensitive search. + ]]> @@ -173,13 +173,13 @@ Provides COM objects with version-independent access to the method. An instance of representing the type, with culture, arguments, binder, and activation attributes set to , and set to Public or Instance, or if is not found. - method locates the specified type from this assembly and creates an instance of it using the system activator, with optional case-sensitive search. - + method locates the specified type from this assembly and creates an instance of it using the system activator, with optional case-sensitive search. + ]]> @@ -223,15 +223,15 @@ Provides COM objects with version-independent access to the method. An instance of representing the type and matching the specified criteria, or if is not found. - method locates the specified type from this assembly and creates an instance of it using the system activator, with optional case-sensitive search and having the specified culture, arguments, and binding and activation attributes. + method locates the specified type from this assembly and creates an instance of it using the system activator, with optional case-sensitive search and having the specified culture, arguments, and binding and activation attributes. An example of an activation attribute for the `activationAttributes` parameter is: `URLAttribute(http://hostname/appname/objectURI)`. - + ]]> @@ -258,13 +258,13 @@ Provides COM objects with version-independent access to the property. A object that represents the entry point of this assembly. If no entry point is found (for example, the assembly is a DLL), is returned. - property gets the entry point of this assembly. - + property gets the entry point of this assembly. + ]]> @@ -296,13 +296,13 @@ if the specified is equal to the current ; otherwise, . - method determines whether the specified is equal to the current . - + method determines whether the specified is equal to the current . + ]]> @@ -329,13 +329,13 @@ Provides COM objects with version-independent access to the property. A Uniform Resource Identifier (URI) with escape characters. - property gets the URI, including escape characters, that represents the codebase. - + property gets the URI, including escape characters, that represents the codebase. + ]]> @@ -362,13 +362,13 @@ Provides COM objects with version-independent access to the property. An object for this assembly. - property gets the evidence for this assembly. - + property gets the evidence for this assembly. + ]]> @@ -395,13 +395,13 @@ Provides COM objects with version-independent access to the property. The display name of the assembly. - property gets the display name of the assembly. - + property gets the display name of the assembly. + ]]> @@ -416,13 +416,13 @@ Provides COM objects with version-independent access to the methods. - methods get the custom attributes for this assembly. - + methods get the custom attributes for this assembly. + ]]> @@ -453,13 +453,13 @@ Provides COM objects with version-independent access to the method. An array of type containing the custom attributes for this assembly. - method gets all the custom attributes for this assembly. - + method gets all the custom attributes for this assembly. + ]]> @@ -492,13 +492,13 @@ Provides COM objects with version-independent access to the method. An array of type containing the custom attributes for this assembly as specified by . - method gets all the custom attributes for this assembly. - + method gets all the custom attributes for this assembly. + ]]> @@ -526,13 +526,13 @@ Provides COM objects with version-independent access to the property. An array of objects that represent the types defined in this assembly that are visible outside the assembly. - property gets the exported types defined in this assembly that are visible outside the assembly. - + property gets the exported types defined in this assembly that are visible outside the assembly. + ]]> @@ -563,13 +563,13 @@ Provides COM objects with version-independent access to the method. A for the specified file, or if the file is not found. - method gets a for the specified file in the file table of the manifest of this assembly. - + method gets a for the specified file in the file table of the manifest of this assembly. + ]]> @@ -584,13 +584,13 @@ Provides COM objects with version-independent access to the methods. - methods get the files in the file table of an assembly manifest. - + methods get the files in the file table of an assembly manifest. + ]]> @@ -618,13 +618,13 @@ Provides COM objects with version-independent access to the method. An array of objects. - method gets the files in the file table of an assembly manifest. - + method gets the files in the file table of an assembly manifest. + ]]> @@ -656,13 +656,13 @@ Provides COM objects with version-independent access to the method. An array of objects. - method gets the files in the file table of an assembly manifest, specifying whether to include resource modules. - + method gets the files in the file table of an assembly manifest, specifying whether to include resource modules. + ]]> @@ -690,13 +690,13 @@ Provides COM objects with version-independent access to the method. A hash code for the current . - method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. - + method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + ]]> @@ -711,13 +711,13 @@ Provides COM objects with version-independent access to the methods. - methods get all the loaded modules that are part of this assembly. - + methods get all the loaded modules that are part of this assembly. + ]]> @@ -745,13 +745,13 @@ Provides COM objects with version-independent access to the method. An array of modules. - method gets all the loaded modules that are part of this assembly. - + method gets all the loaded modules that are part of this assembly. + ]]> @@ -783,13 +783,13 @@ Provides COM objects with version-independent access to the method. An array of modules. - method gets all the loaded modules that are part of this assembly, specifying whether to include resource modules. - + method gets all the loaded modules that are part of this assembly, specifying whether to include resource modules. + ]]> @@ -820,13 +820,13 @@ Provides COM objects with version-independent access to the method. A object populated with information about the resource's topology, or if the resource is not found. - method returns information about how the given resource has been persisted. - + method returns information about how the given resource has been persisted. + ]]> @@ -854,13 +854,13 @@ Provides COM objects with version-independent access to the method. An array of type containing the names of all the resources. - method returns the names of all the resources in this assembly. - + method returns the names of all the resources in this assembly. + ]]> @@ -875,13 +875,13 @@ Provides COM objects with version-independent access to the methods. - methods load the specified manifest resource from this assembly. - + methods load the specified manifest resource from this assembly. + ]]> @@ -912,13 +912,13 @@ Provides COM objects with version-independent access to the method. A representing this manifest resource. - method loads the specified manifest resource from this assembly. - + method loads the specified manifest resource from this assembly. + ]]> @@ -951,13 +951,13 @@ Provides COM objects with version-independent access to the method. A representing this manifest resource. - method loads the specified manifest resource, scoped by the namespace of the specified type, from this assembly. - + method loads the specified manifest resource, scoped by the namespace of the specified type, from this assembly. + ]]> @@ -988,13 +988,13 @@ Provides COM objects with version-independent access to the method. The module being requested, or if the module is not found. - method gets the specified module in this assembly. - + method gets the specified module in this assembly. + ]]> @@ -1009,13 +1009,13 @@ Provides COM objects with version-independent access to the methods. - methods get all the modules that are part of this assembly. - + methods get all the modules that are part of this assembly. + ]]> @@ -1043,13 +1043,13 @@ Provides COM objects with version-independent access to the method. An array of modules. - method gets all the modules that are part of this assembly. - + method gets all the modules that are part of this assembly. + ]]> @@ -1081,13 +1081,13 @@ Provides COM objects with version-independent access to the method. An array of modules. - method gets all the modules that are part of this assembly, specifying whether to include resource modules. - + method gets all the modules that are part of this assembly, specifying whether to include resource modules. + ]]> @@ -1102,13 +1102,13 @@ Provides COM objects with version-independent access to the methods. - methods get an for this assembly. - + methods get an for this assembly. + ]]> @@ -1136,13 +1136,13 @@ Provides COM objects with version-independent access to the method. An for this assembly. - method gets an for this assembly. - + method gets an for this assembly. + ]]> @@ -1174,13 +1174,13 @@ Provides COM objects with version-independent access to the method. An for this assembly. - method gets an for this assembly, setting the codebase as specified by the `copiedName` parameter. - + method gets an for this assembly, setting the codebase as specified by the `copiedName` parameter. + ]]> @@ -1218,13 +1218,13 @@ The destination context of the serialization. Provides COM objects with version-independent access to the method. - method gets serialization information with all of the data needed to reinstantiate this assembly. - + method gets serialization information with all of the data needed to reinstantiate this assembly. + ]]> @@ -1252,13 +1252,13 @@ Provides COM objects with version-independent access to the method. An array of type containing all the assemblies referenced by this assembly. - method gets the objects for all the assemblies referenced by this assembly. - + method gets the objects for all the assemblies referenced by this assembly. + ]]> @@ -1273,13 +1273,13 @@ Provides COM objects with version-independent access to the methods. - methods get the satellite assembly. - + methods get the satellite assembly. + ]]> @@ -1310,13 +1310,13 @@ Provides COM objects with version-independent access to the method. The specified satellite assembly. - method gets the satellite assembly for the specified culture. - + method gets the satellite assembly for the specified culture. + ]]> @@ -1349,13 +1349,13 @@ Provides COM objects with version-independent access to the method. The specified satellite assembly. - method gets the specified version of the satellite assembly for the specified culture. - + method gets the specified version of the satellite assembly for the specified culture. + ]]> @@ -1370,13 +1370,13 @@ Provides COM objects with version-independent access to the methods. - methods get the object that represents the specified type. - + methods get the object that represents the specified type. + ]]> @@ -1404,13 +1404,13 @@ Provides COM objects with version-independent access to the method. A object. - method gets the type of the current instance. - + method gets the type of the current instance. + ]]> @@ -1441,13 +1441,13 @@ Provides COM objects with version-independent access to the method. A object that represents the specified class, or if the class is not found. - method gets the object with the specified name in the assembly instance. - + method gets the object with the specified name in the assembly instance. + ]]> @@ -1481,13 +1481,13 @@ Provides COM objects with version-independent access to the method. A object that represents the specified class. - method gets the object with the specified name in the assembly instance and optionally throws an exception if the type is not found. - + method gets the object with the specified name in the assembly instance and optionally throws an exception if the type is not found. + ]]> @@ -1524,13 +1524,13 @@ Provides COM objects with version-independent access to the method. A object that represents the specified class. - method gets the object with the specified name in the assembly instance, with the options of ignoring the case, and of throwing an exception if the type is not found. - + method gets the object with the specified name in the assembly instance, with the options of ignoring the case, and of throwing an exception if the type is not found. + ]]> @@ -1558,13 +1558,13 @@ Provides COM objects with version-independent access to the method. An array of type containing objects for all the types defined in this assembly. - method gets the types defined in this assembly. - + method gets the types defined in this assembly. + ]]> @@ -1592,13 +1592,13 @@ if the assembly was loaded from the global assembly cache; otherwise, . - property gets a value indicating whether the assembly was loaded from the global assembly cache. - + property gets a value indicating whether the assembly was loaded from the global assembly cache. + ]]> @@ -1632,13 +1632,13 @@ if a custom attribute identified by the specified is defined; otherwise, . - method indicates whether a custom attribute identified by the specified is defined. - + method indicates whether a custom attribute identified by the specified is defined. + ]]> @@ -1653,13 +1653,13 @@ Provides COM objects with version-independent access to the members. - members load the module internal to this assembly. - + members load the module internal to this assembly. + ]]> @@ -1692,13 +1692,13 @@ Provides COM objects with version-independent access to the method. The loaded Module. - method loads the module, internal to this assembly, with a Common Object File Format (COFF)-based image containing an emitted module, or a resource file. - + method loads the module, internal to this assembly, with a Common Object File Format (COFF)-based image containing an emitted module, or a resource file. + ]]> @@ -1733,13 +1733,13 @@ Provides COM objects with version-independent access to the method. The loaded module. - method loads the module, internal to this assembly, with a Common Object File Format (COFF)-based image containing an emitted module, or a resource file. The raw bytes representing the symbols for the module are also loaded. - + method loads the module, internal to this assembly, with a Common Object File Format (COFF)-based image containing an emitted module, or a resource file. The raw bytes representing the symbols for the module are also loaded. + ]]> @@ -1766,13 +1766,13 @@ Provides COM objects with version-independent access to the property. The location of the loaded file that contains the manifest. If the loaded file was shadow-copied, the location is that of the file after being shadow-copied. If the assembly is loaded from a byte array, such as when using the method overload, the value returned is an empty string (""). - property gets the path or Universal Naming Convention (UNC) location of the loaded file that contains the manifest. - + property gets the path or Universal Naming Convention (UNC) location of the loaded file that contains the manifest. + ]]> @@ -1808,13 +1808,13 @@ Provides COM objects with version-independent access to the event. - event occurs when the common language runtime class loader cannot resolve a reference to an internal module of an assembly through normal means. - + event occurs when the common language runtime class loader cannot resolve a reference to an internal module of an assembly through normal means. + ]]> @@ -1842,13 +1842,13 @@ Provides COM objects with version-independent access to the method. The full name of the assembly, or the class name if the full name of the assembly cannot be determined. - method returns the full name of the assembly, also known as the display name. - + method returns the full name of the assembly, also known as the display name. + ]]> diff --git a/xml/System.Runtime.InteropServices/_ConstructorInfo.xml b/xml/System.Runtime.InteropServices/_ConstructorInfo.xml index 689525f457f..aeb216af496 100644 --- a/xml/System.Runtime.InteropServices/_ConstructorInfo.xml +++ b/xml/System.Runtime.InteropServices/_ConstructorInfo.xml @@ -38,15 +38,15 @@ Exposes the public members of the class to unmanaged code. - class discovers the attributes of a class constructor and provides access to constructor metadata. - - The interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. - + class discovers the attributes of a class constructor and provides access to constructor metadata. + + The interface preserves the vtable order of the class members that can be accessed by unmanaged COM objects. + ]]> @@ -72,13 +72,13 @@ Provides COM objects with version-independent access to the property. One of the values. - property gets the attributes associated with this method. - + property gets the attributes associated with this method. + ]]> @@ -104,13 +104,13 @@ Provides COM objects with version-independent access to the property. The for this method. - property gets a value indicating the calling conventions for this method. - + property gets a value indicating the calling conventions for this method. + ]]> @@ -136,13 +136,13 @@ Provides COM objects with version-independent access to the property. The object for the class that declares this member. - property gets the class that declares this member. - + property gets the class that declares this member. + ]]> @@ -173,13 +173,13 @@ if the specified is equal to the current ; otherwise, . - method determines whether the specified is equal to the current . - + method determines whether the specified is equal to the current . + ]]> @@ -193,11 +193,11 @@ Provides COM objects with version-independent access to the members. - members return all attributes applied to this member. - + members return all attributes applied to this member. + ]]> @@ -227,13 +227,13 @@ Provides COM objects with version-independent access to the method. An array that contains all the custom attributes, or an array with zero elements if no attributes are defined. - method returns an array containing all the custom attributes. - + method returns an array containing all the custom attributes. + ]]> @@ -265,13 +265,13 @@ Provides COM objects with version-independent access to the method. An array of custom attributes applied to this member, or an array with zero (0) elements if no attributes have been applied. - method returns an array of custom attributes identified by . - + method returns an array of custom attributes identified by . + ]]> @@ -298,13 +298,13 @@ Provides COM objects with version-independent access to the method. The hash code for the current instance. - method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. - + method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + ]]> @@ -341,11 +341,11 @@ Caller-allocated array that receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - @@ -372,13 +372,13 @@ Provides COM objects with version-independent access to the member. The flags. - member returns the flags. - + member returns the flags. + ]]> @@ -405,13 +405,13 @@ Provides COM objects with version-independent access to the method. An array of type containing information that matches the signature of the method (or constructor) reflected by this instance. - method gets the parameters of the specified method or constructor. - + method gets the parameters of the specified method or constructor. + ]]> @@ -438,13 +438,13 @@ Provides COM objects with version-independent access to the method. A object. - method gets the type of the current instance. - + method gets the type of the current instance. + ]]> @@ -477,11 +477,11 @@ 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. - @@ -510,11 +510,11 @@ 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). - @@ -557,11 +557,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - @@ -599,13 +599,13 @@ Provides COM objects with version-independent access to the method. An instance of the class associated with the constructor. - method invokes the constructor reflected by this with the specified arguments, under the constraints of the specified . - + method invokes the constructor reflected by this with the specified arguments, under the constraints of the specified . + ]]> @@ -633,19 +633,19 @@ The instance that created this method. - An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, should be . - + An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, should be . + If the method or constructor represented by this instance takes a parameter ( in Visual Basic), no special attribute is required for that parameter in order to invoke the method or constructor using this function. Any object in this array that is not explicitly initialized with a value will contain the default value for that object type. For reference-type elements, this value is . For value-type elements, this value is 0, 0.0, or , depending on the specific element type. Provides COM objects with version-independent access to the method. An instance of the class associated with the constructor. - method invokes the method or constructor represented by this object, using the specified parameters. - + method invokes the method or constructor represented by this object, using the specified parameters. + ]]> @@ -681,13 +681,13 @@ Provides COM objects with version-independent access to the method. An instance of the class associated with the constructor. - method invokes the constructor reflected by this object with the specified arguments, under the constraints of the specified object. - + method invokes the constructor reflected by this object with the specified arguments, under the constraints of the specified object. + ]]> @@ -717,13 +717,13 @@ Provides COM objects with version-independent access to the method. An instance of the class associated with the constructor. - method invokes the constructor reflected by the instance that has the specified parameters, providing default values for the parameters not commonly used. - + method invokes the constructor reflected by the instance that has the specified parameters, providing default values for the parameters not commonly used. + ]]> @@ -750,13 +750,13 @@ if the method is abstract; otherwise, . - property gets a value indicating whether the method is abstract. - + property gets a value indicating whether the method is abstract. + ]]> @@ -783,13 +783,13 @@ if this method can be called by other classes in the same assembly; otherwise, . - property gets a value indicating whether this method can be called by other classes in the same assembly. - + property gets a value indicating whether this method can be called by other classes in the same assembly. + ]]> @@ -816,13 +816,13 @@ if this method is a constructor; otherwise, . - property gets a value indicating whether the method is a constructor. - + property gets a value indicating whether the method is a constructor. + ]]> @@ -855,13 +855,13 @@ if one or more instances of is applied to this member; otherwise . - member indicates whether one or more instances of `attributeType` is applied to this member. - + member indicates whether one or more instances of `attributeType` is applied to this member. + ]]> @@ -888,13 +888,13 @@ if access to the class is restricted to members of the class itself and to members of its derived classes; otherwise, . - property gets a value indicating whether access to this method is restricted to members of the class and members of its derived classes. - + property gets a value indicating whether access to this method is restricted to members of the class and members of its derived classes. + ]]> @@ -921,13 +921,13 @@ if access to this method is restricted to members of the class itself and to members of derived classes that are in the same assembly; otherwise, . - property gets a value indicating whether this method can be called by derived classes if they are in the same assembly. - + property gets a value indicating whether this method can be called by derived classes if they are in the same assembly. + ]]> @@ -954,13 +954,13 @@ if access to this method is restricted to members of the class itself, members of derived classes wherever they are, and members of other classes in the same assembly; otherwise, . - property gets a value indicating whether this method can be called by derived classes, wherever they are, and by all classes in the same assembly. - + property gets a value indicating whether this method can be called by derived classes, wherever they are, and by all classes in the same assembly. + ]]> @@ -987,13 +987,13 @@ if this method is ; otherwise, . - property gets a value indicating whether this method is `final`. - + property gets a value indicating whether this method is `final`. + ]]> @@ -1020,13 +1020,13 @@ if the member is hidden by signature; otherwise, . - property gets a value indicating whether only a member of the same kind with exactly the same signature is hidden in the derived class. - + property gets a value indicating whether only a member of the same kind with exactly the same signature is hidden in the derived class. + ]]> @@ -1053,13 +1053,13 @@ if access to this method is restricted to other members of the class itself; otherwise, . - property gets a value indicating whether this member is private. - + property gets a value indicating whether this member is private. + ]]> @@ -1086,13 +1086,13 @@ if this method is public; otherwise, . - property gets a value indicating whether this is a public method. - + property gets a value indicating whether this is a public method. + ]]> @@ -1119,13 +1119,13 @@ if this method has a special name; otherwise, . - property gets a value indicating whether this method has a special name. - + property gets a value indicating whether this method has a special name. + ]]> @@ -1152,13 +1152,13 @@ if this method is ; otherwise, . - property gets a value indicating whether the method is `static`. - + property gets a value indicating whether the method is `static`. + ]]> @@ -1185,13 +1185,13 @@ if this method is ; otherwise, . - property gets a value indicating whether the method is `virtual`. - + property gets a value indicating whether the method is `virtual`. + ]]> @@ -1217,13 +1217,13 @@ Provides COM objects with version-independent access to the property. A value indicating the type of member. - property gets a value indicating the type of the member - method, constructor, event, and so on. - + property gets a value indicating the type of the member - method, constructor, event, and so on. + ]]> @@ -1249,13 +1249,13 @@ Provides COM objects with version-independent access to the property. A object. - property gets a handle to the internal metadata representation of a method. - + property gets a handle to the internal metadata representation of a method. + ]]> @@ -1281,13 +1281,13 @@ Provides COM objects with version-independent access to the property. A containing the name of this member. - property gets the name of the current member. - + property gets the name of the current member. + ]]> @@ -1313,13 +1313,13 @@ Provides COM objects with version-independent access to the property. The object through which this object was obtained. - property gets the class object that was used to obtain this instance of . - + property gets the class object that was used to obtain this instance of . + ]]> @@ -1346,11 +1346,11 @@ Provides COM objects with version-independent access to the method. A string that represents the current . - diff --git a/xml/System.Runtime.InteropServices/_EventInfo.xml b/xml/System.Runtime.InteropServices/_EventInfo.xml index f0aa3010c8c..2c5cf5befed 100644 --- a/xml/System.Runtime.InteropServices/_EventInfo.xml +++ b/xml/System.Runtime.InteropServices/_EventInfo.xml @@ -38,13 +38,13 @@ Exposes the public members of the class to unmanaged code. - class members that can be accessed by unmanaged COM objects. - + class members that can be accessed by unmanaged COM objects. + ]]> @@ -75,13 +75,13 @@ A method or methods to be invoked when the event is raised by the target. Provides COM objects with version-independent access to the method. - method adds an event handler to an event source. - + method adds an event handler to an event source. + ]]> @@ -107,13 +107,13 @@ Provides COM objects with version-independent access to the property. The read-only attributes for this event. - property gets the attributes for this event. - + property gets the attributes for this event. + ]]> @@ -139,13 +139,13 @@ Provides COM objects with version-independent access to the property. The object for the class that declares this member. - property gets the class that declares this member. - + property gets the class that declares this member. + ]]> @@ -176,13 +176,13 @@ if the specified is equal to the current ; otherwise, . - method determines whether the specified is equal to the current . - + method determines whether the specified is equal to the current . + ]]> @@ -208,13 +208,13 @@ Provides COM objects with version-independent access to the property. A read-only object representing the delegate event handler. - property gets the object of the underlying event-handler delegate associated with this event. - + property gets the object of the underlying event-handler delegate associated with this event. + ]]> @@ -228,13 +228,13 @@ Provides COM objects with version-independent access to the methods. - methods return the method used to add an event-handler delegate to the event source. - + methods return the method used to add an event-handler delegate to the event source. + ]]> @@ -261,13 +261,13 @@ Provides COM objects with version-independent access to the method. A object representing the method used to add an event-handler delegate to the event source. - method returns the method used to add an event-handler delegate to the event source. - + method returns the method used to add an event-handler delegate to the event source. + ]]> @@ -298,13 +298,13 @@ Provides COM objects with version-independent access to the method. A object representing the method used to add an event-handler delegate to the event source. - method retrieves the object for the method of the event and specifies whether to return non-public methods - + method retrieves the object for the method of the event and specifies whether to return non-public methods + ]]> @@ -318,13 +318,13 @@ Provides COM objects with version-independent access to the methods. - methods return all attributes applied to this member. - + methods return all attributes applied to this member. + ]]> @@ -355,13 +355,13 @@ Provides COM objects with version-independent access to the method. An array that contains all the custom attributes, or an array with zero (0) elements if no attributes are defined. - method retrieves the object for the method of the event and specifies whether to return non-public methods - + method retrieves the object for the method of the event and specifies whether to return non-public methods + ]]> @@ -394,13 +394,13 @@ Provides COM objects with version-independent access to the method. An array of custom attributes applied to this member, or an array with zero (0) elements if no attributes have been applied. - method returns an array of custom attributes identified by . - + method returns an array of custom attributes identified by . + ]]> @@ -427,13 +427,13 @@ Provides COM objects with version-independent access to the method. The hash code for the current instance. - method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. - + method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> @@ -470,11 +470,11 @@ An array allocated by the caller that receives the identifiers corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - @@ -488,13 +488,13 @@ Provides COM objects with version-independent access to the methods. - methods return the method that is called when the event is raised. - + methods return the method that is called when the event is raised. + ]]> @@ -521,13 +521,13 @@ Provides COM objects with version-independent access to the method. The method that is called when the event is raised. - method returns the method that is called when the event is raised. - + method returns the method that is called when the event is raised. + ]]> @@ -558,13 +558,13 @@ Provides COM objects with version-independent access to the method. The object that was called when the event was raised. - method returns the method that is called when the event is raised and specifies whether to return non-public methods. - + method returns the method that is called when the event is raised and specifies whether to return non-public methods. + ]]> @@ -578,13 +578,13 @@ Provides COM objects with version-independent access to the method. - method returns the method used to remove an event-handler delegate from the event source. - + method returns the method used to remove an event-handler delegate from the event source. + ]]> @@ -611,13 +611,13 @@ Provides COM objects with version-independent access to the method. A object representing the method used to remove an event-handler delegate from the event source. - method returns the method used to remove an event-handler delegate from the event source. - + method returns the method used to remove an event-handler delegate from the event source. + ]]> @@ -648,13 +648,13 @@ Provides COM objects with version-independent access to the method. A object representing the method used to remove an event-handler delegate from the event source. - method retrieves the object for removing a method of the event and specifies whether to return non-public methods. - + method retrieves the object for removing a method of the event and specifies whether to return non-public methods. + ]]> @@ -681,13 +681,13 @@ Provides COM objects with version-independent access to the method. A object. - method gets the type of the current instance. - + method gets the type of the current instance. + ]]> @@ -720,11 +720,11 @@ A pointer to the requested type information object. Retrieves the type information for an object, which can be used to get the type information for an interface. - @@ -753,11 +753,11 @@ When this method returns, contains a pointer to a location that receives the number of type information interfaces provided by the object. This parameter is passed uninitialized. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - @@ -800,11 +800,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - @@ -838,13 +838,13 @@ if one or more instance of the parameter is applied to this member; otherwise, . - method indicates whether one or more instances of the `attributeType` parameter are applied to this member. - + method indicates whether one or more instances of the `attributeType` parameter are applied to this member. + ]]> @@ -871,13 +871,13 @@ if the delegate is an instance of a multicast delegate; otherwise, . - property gets a value indicating whether the event is multicast. - + property gets a value indicating whether the event is multicast. + ]]> @@ -904,13 +904,13 @@ if this event has a special name; otherwise, . - property gets a value indicating whether the object has a name with a special meaning. - + property gets a value indicating whether the object has a name with a special meaning. + ]]> @@ -936,13 +936,13 @@ Provides COM objects with version-independent access to the property. A value indicating that this member is an event. - property gets a value indicating that this member is an event. - + property gets a value indicating that this member is an event. + ]]> @@ -968,13 +968,13 @@ Provides COM objects with version-independent access to the property. A object containing the name of this member. - property gets the name of the current member. - + property gets the name of the current member. + ]]> @@ -1000,13 +1000,13 @@ Provides COM objects with version-independent access to the property. The object that was used to obtain this object. - property gets the class object that was used to obtain this instance. - + property gets the class object that was used to obtain this instance. + ]]> @@ -1037,13 +1037,13 @@ The delegate to be disassociated from the events raised by target. Provides COM objects with version-independent access to the method. - method removes an event handler from an event source. - + method removes an event handler from an event source. + ]]> @@ -1070,11 +1070,11 @@ Provides COM objects with version-independent access to the method. A string that represents the current . - diff --git a/xml/System.Runtime.InteropServices/_Exception.xml b/xml/System.Runtime.InteropServices/_Exception.xml index 571cac0a186..a915efd39d3 100644 --- a/xml/System.Runtime.InteropServices/_Exception.xml +++ b/xml/System.Runtime.InteropServices/_Exception.xml @@ -33,13 +33,13 @@ Exposes the public members of the class to unmanaged code. - class members that can be accessed by unmanaged COM objects. - + class members that can be accessed by unmanaged COM objects. + ]]> @@ -70,13 +70,13 @@ if the specified is equal to the current ; otherwise, . - method determines whether the specified is equal to the current . - + method determines whether the specified is equal to the current . + ]]> @@ -103,13 +103,13 @@ Provides COM objects with version-independent access to the method. The first exception thrown in a chain of exceptions. If the property of the current exception is a null reference ( in Visual Basic), this property returns the current exception. - method returns the that is the root cause of one or more subsequent exceptions. - + method returns the that is the root cause of one or more subsequent exceptions. + ]]> @@ -136,13 +136,13 @@ Provides COM objects with version-independent access to the method. The hash code for the current instance. - method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. - + method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> @@ -179,13 +179,13 @@ The structure that contains contextual information about the source or destination. Provides COM objects with version-independent access to the method. - method sets the object with information about the exception. - + method sets the object with information about the exception. + ]]> @@ -212,13 +212,13 @@ Provides COM objects with version-independent access to the method. A object that represents the exact runtime type of the current instance. - method gets the runtime type of the current instance. - + method gets the runtime type of the current instance. + ]]> @@ -244,13 +244,13 @@ Provides COM objects with version-independent access to the property. The Uniform Resource Name (URN) or Uniform Resource Locator (URL) to a help file. - property gets or sets a link to the help file associated with this exception. - + property gets or sets a link to the help file associated with this exception. + ]]> @@ -276,13 +276,13 @@ Provides COM objects with version-independent access to the property. An instance of that describes the error that caused the current exception. The property returns the same value that was passed to the constructor, or a null reference ( in Visual Basic) if the inner exception value was not supplied to the constructor. This property is read-only. - property gets the instance that caused the current exception. - + property gets the instance that caused the current exception. + ]]> @@ -308,13 +308,13 @@ Provides COM objects with version-independent access to the property. The error message that explains the reason for the exception, or an empty string(""). - property gets a message that describes the current exception. - + property gets a message that describes the current exception. + ]]> @@ -340,13 +340,13 @@ Provides COM objects with version-independent access to the property. The name of the application or the object that causes the error. - property gets or sets the name of the application or the object that causes the error. - + property gets or sets the name of the application or the object that causes the error. + ]]> @@ -372,13 +372,13 @@ Provides COM objects with version-independent access to the property. A string that describes the contents of the call stack, with the most recent method call appearing first. - property gets a string representation of the frames on the call stack at the time the current exception was thrown. - + property gets a string representation of the frames on the call stack at the time the current exception was thrown. + ]]> @@ -404,13 +404,13 @@ Provides COM objects with version-independent access to the property. The object that threw the current exception. - property gets the method that throws the current exception. - + property gets the method that throws the current exception. + ]]> @@ -437,13 +437,13 @@ Provides COM objects with version-independent access to the method. A string that represents the current object. - method creates and returns a string representation of the current exception. - + method creates and returns a string representation of the current exception. + ]]> diff --git a/xml/System.Runtime.InteropServices/_FieldInfo.xml b/xml/System.Runtime.InteropServices/_FieldInfo.xml index 1e4f69d9f71..c603d403b96 100644 --- a/xml/System.Runtime.InteropServices/_FieldInfo.xml +++ b/xml/System.Runtime.InteropServices/_FieldInfo.xml @@ -38,13 +38,13 @@ Exposes the public members of the class to unmanaged code. - class members that can be accessed by unmanaged COM objects. - + class members that can be accessed by unmanaged COM objects. + ]]> @@ -70,13 +70,13 @@ Provides COM objects with version-independent access to the property. The for this field. - property gets the attributes associated with this field. - + property gets the attributes associated with this field. + ]]> @@ -102,13 +102,13 @@ Provides COM objects with version-independent access to the property. The object for the class that declares this member. - property gets the class that declares this member. - + property gets the class that declares this member. + ]]> @@ -139,13 +139,13 @@ if the specified is equal to the current ; otherwise, . - method determines whether the specified is equal to the current . - + method determines whether the specified is equal to the current . + ]]> @@ -171,13 +171,13 @@ Provides COM objects with version-independent access to the property. A handle to the internal metadata representation of a field. - property gets a , which is a handle to the internal metadata representation of a field. - + property gets a , which is a handle to the internal metadata representation of a field. + ]]> @@ -203,13 +203,13 @@ Provides COM objects with version-independent access to the property. The type of this field object. - property gets the type of this field object. - + property gets the type of this field object. + ]]> @@ -223,13 +223,13 @@ Provides COM objects with version-independent access to the methods. - methods return all attributes applied to this member. - + methods return all attributes applied to this member. + ]]> @@ -259,13 +259,13 @@ Provides COM objects with version-independent access to the method. An array that contains all the custom attributes, or an array with zero elements if no attributes are defined. - method returns an array containing all the custom attributes. - + method returns an array containing all the custom attributes. + ]]> @@ -297,13 +297,13 @@ Provides COM objects with version-independent access to the method. An array of custom attributes applied to this member, or an array with zero (0) elements if no attributes have been applied. - method returns an array of custom attributes identified by . - + method returns an array of custom attributes identified by . + ]]> @@ -330,13 +330,13 @@ Provides COM objects with version-independent access to the method. The hash code for the current instance. - method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. - + method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures like a hash table. + ]]> @@ -373,11 +373,11 @@ Caller-allocated array that receives the IDs corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - @@ -404,13 +404,13 @@ Provides COM objects with version-independent access to the method. A object. - method gets the type of the current instance. - + method gets the type of the current instance. + ]]> @@ -443,11 +443,11 @@ 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. - @@ -476,11 +476,11 @@ 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). - @@ -510,13 +510,13 @@ Provides COM objects with version-independent access to the method. An object containing the value of the field reflected by this instance. - method returns the value of a field supported by a given object. - + method returns the value of a field supported by a given object. + ]]> @@ -552,13 +552,13 @@ Provides COM objects with version-independent access to the method. An containing a field value. - method returns the value of a field supported by a given object. - + method returns the value of a field supported by a given object. + ]]> @@ -601,11 +601,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - @@ -632,13 +632,13 @@ if the field has the attribute set; otherwise, . - property gets a value indicating whether this field has `Assembly` level visibility. - + property gets a value indicating whether this field has `Assembly` level visibility. + ]]> @@ -671,13 +671,13 @@ if one or more instance of is applied to this member; otherwise, . - method indicates whether one or more instance of `attributeType` is applied to this member. - + method indicates whether one or more instance of `attributeType` is applied to this member. + ]]> @@ -704,13 +704,13 @@ if the field has the attribute set; otherwise, . - property gets a value indicating whether this field has `Family` level visibility. - + property gets a value indicating whether this field has `Family` level visibility. + ]]> @@ -737,13 +737,13 @@ if the field has the attribute set; otherwise, . - property gets a value indicating whether this field has `FamilyAndAssembly` level visibility. - + property gets a value indicating whether this field has `FamilyAndAssembly` level visibility. + ]]> @@ -770,13 +770,13 @@ if the field has the attribute set; otherwise, . - property gets a value indicating whether this field has `FamilyOrAssembly` level visibility. - + property gets a value indicating whether this field has `FamilyOrAssembly` level visibility. + ]]> @@ -803,13 +803,13 @@ if the field has the attribute set; otherwise, . - property gets a value indicating whether the field can only be set in the body of the constructor. - + property gets a value indicating whether the field can only be set in the body of the constructor. + ]]> @@ -836,13 +836,13 @@ if the field has the attribute set; otherwise, . - property gets a value indicating whether the value is written at compile time and cannot be changed. - + property gets a value indicating whether the value is written at compile time and cannot be changed. + ]]> @@ -869,13 +869,13 @@ if the field has the attribute set; otherwise, . - property gets a value indicating whether this field has the `NotSerialized` attribute. - + property gets a value indicating whether this field has the `NotSerialized` attribute. + ]]> @@ -902,13 +902,13 @@ if the attribute is set in ; otherwise, . - property gets a value indicating whether the corresponding `PinvokeImpl` attribute is set in . - + property gets a value indicating whether the corresponding `PinvokeImpl` attribute is set in . + ]]> @@ -935,13 +935,13 @@ if the field is private; otherwise; . - property gets a value indicating whether the field is private. - + property gets a value indicating whether the field is private. + ]]> @@ -968,13 +968,13 @@ if this field is public; otherwise, . - property gets a value indicating whether the field is public. - + property gets a value indicating whether the field is public. + ]]> @@ -1001,13 +1001,13 @@ if the attribute is set in ; otherwise, . - property gets a value indicating whether the corresponding `SpecialName` attribute is set in the enumerator. - + property gets a value indicating whether the corresponding `SpecialName` attribute is set in the enumerator. + ]]> @@ -1034,13 +1034,13 @@ if this field is static; otherwise, . - property gets a value indicating whether the field is static. - + property gets a value indicating whether the field is static. + ]]> @@ -1066,13 +1066,13 @@ Provides COM objects with version-independent access to the property. A value indicating that this member is a field. - property gets a value indicating that this member is a field. - + property gets a value indicating that this member is a field. + ]]> @@ -1098,13 +1098,13 @@ Provides COM objects with version-independent access to the property. A containing the name of this member. - property gets the name of the current member. - + property gets the name of the current member. + ]]> @@ -1130,13 +1130,13 @@ Provides COM objects with version-independent access to the property. The object through which this object was obtained. - property gets the class object that was used to obtain this instance of . - + property gets the class object that was used to obtain this instance of . + ]]> @@ -1150,13 +1150,13 @@ Provides COM objects with version-independent access to the methods. - methods set the value of the field for the given object to the given value. - + methods set the value of the field for the given object to the given value. + ]]> @@ -1187,13 +1187,13 @@ The value to assign to the field. Provides COM objects with version-independent access to the method. - method sets the value of the field supported by the given object. - + method sets the value of the field supported by the given object. + ]]> @@ -1230,13 +1230,13 @@ The software preferences of a particular culture. Provides COM objects with version-independent access to the method. - method sets the value of the field supported by the given object. - + method sets the value of the field supported by the given object. + ]]> @@ -1273,13 +1273,13 @@ The value to assign to the field. Provides COM objects with version-independent access to the method. - method sets the value of the field supported by the given object. - + method sets the value of the field supported by the given object. + ]]> @@ -1306,11 +1306,11 @@ Provides COM objects with version-independent access to the method. A string that represents the current . - diff --git a/xml/System.Runtime.InteropServices/_MemberInfo.xml b/xml/System.Runtime.InteropServices/_MemberInfo.xml index 5d600bbc55f..4f1d91c0a0d 100644 --- a/xml/System.Runtime.InteropServices/_MemberInfo.xml +++ b/xml/System.Runtime.InteropServices/_MemberInfo.xml @@ -42,13 +42,13 @@ Exposes the public members of the class to unmanaged code. - class members that can be accessed by unmanaged COM objects. - + class members that can be accessed by unmanaged COM objects. + ]]> @@ -74,13 +74,13 @@ Provides COM objects with version-independent access to the property. The object for the class that declares this member. - property gets the class that declares this member. - + property gets the class that declares this member. + ]]> @@ -111,13 +111,13 @@ if the specified is equal to the current ; otherwise, . - method determines whether the specified is equal to the current . - + method determines whether the specified is equal to the current . + ]]> @@ -131,13 +131,13 @@ Provides COM objects with version-independent access to the method. - method returns all attributes applied to this member. - + method returns all attributes applied to this member. + ]]> @@ -168,13 +168,13 @@ Provides COM objects with version-independent access to the method. An array that contains all the custom attributes, or an array with zero (0) elements if no attributes are defined. - method returns an array containing all the custom attributes. - + method returns an array containing all the custom attributes. + ]]> @@ -207,13 +207,13 @@ Provides COM objects with version-independent access to the method. An array of custom attributes applied to this member, or an array with zero (0) elements if no attributes have been applied. - method returns an array of custom attributes identified by . - + method returns an array of custom attributes identified by . + ]]> @@ -240,13 +240,13 @@ Provides COM objects with version-independent access to the method. The hash code for the current instance. - method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. - + method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> @@ -283,11 +283,11 @@ An array allocated by the caller that receives the identifiers corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - @@ -314,13 +314,13 @@ Provides COM objects with version-independent access to the method. A object. - method gets the type of the current instance. - + method gets the type of the current instance. + ]]> @@ -353,11 +353,11 @@ A pointer to the requested type information object. Retrieves the type information for an object, which can be used to get the type information for an interface. - @@ -386,11 +386,11 @@ When this method returns, contains a pointer to a location that receives the number of type information interfaces provided by the object. This parameter is passed uninitialized. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - @@ -433,11 +433,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - @@ -471,13 +471,13 @@ if one or more instance of the parameter is applied to this member; otherwise, . - method indicates whether one or more instances of the `attributeType` parameter are applied to this member. - + method indicates whether one or more instances of the `attributeType` parameter are applied to this member. + ]]> @@ -503,13 +503,13 @@ Provides COM objects with version-independent access to the property. One of the values indicating the type of member. - property gets a value indicating the type of the member - method, constructor, event, and so on. - + property gets a value indicating the type of the member - method, constructor, event, and so on. + ]]> @@ -535,13 +535,13 @@ Provides COM objects with version-independent access to the property. A object containing the name of this member. - property gets the name of the current member. - + property gets the name of the current member. + ]]> @@ -567,13 +567,13 @@ Provides COM objects with version-independent access to the property. The object that was used to obtain this object. - property gets the class object that was used to obtain this instance of . - + property gets the class object that was used to obtain this instance of . + ]]> @@ -600,11 +600,11 @@ Provides COM objects with version-independent access to the method. A string that represents the current . - diff --git a/xml/System.Runtime.InteropServices/_MethodBase.xml b/xml/System.Runtime.InteropServices/_MethodBase.xml index 3ca7a02325c..7f1e320b230 100644 --- a/xml/System.Runtime.InteropServices/_MethodBase.xml +++ b/xml/System.Runtime.InteropServices/_MethodBase.xml @@ -38,13 +38,13 @@ Exposes the public members of the class to unmanaged code. - class members that can be accessed by unmanaged COM objects. - + class members that can be accessed by unmanaged COM objects. + ]]> @@ -70,13 +70,13 @@ Provides COM objects with version-independent access to the property. One of the values. - property gets the attributes associated with this method. - + property gets the attributes associated with this method. + ]]> @@ -102,13 +102,13 @@ Provides COM objects with version-independent access to the property. One of the values. - property gets a value indicating the calling conventions for this method. - + property gets a value indicating the calling conventions for this method. + ]]> @@ -134,13 +134,13 @@ Provides COM objects with version-independent access to the property. The object for the class that declares this member. - property gets the class that declares this member. - + property gets the class that declares this member. + ]]> @@ -171,13 +171,13 @@ if the specified is equal to the current ; otherwise, . - method determines whether the specified is equal to the current . - + method determines whether the specified is equal to the current . + ]]> @@ -191,13 +191,13 @@ Provides COM objects with version-independent access to the method. - members return all attributes applied to this member. - + members return all attributes applied to this member. + ]]> @@ -228,13 +228,13 @@ Provides COM objects with version-independent access to the method. An array that contains all the custom attributes, or an array with zero (0) elements if no attributes are defined. - method returns an array containing all the custom attributes. - + method returns an array containing all the custom attributes. + ]]> @@ -267,13 +267,13 @@ Provides COM objects with version-independent access to the method. An array of custom attributes applied to this member, or an array with zero (0) elements if no attributes have been applied. - method returns an array of custom attributes identified by . - + method returns an array of custom attributes identified by . + ]]> @@ -300,13 +300,13 @@ Provides COM objects with version-independent access to the method. The hash code for the current instance. - method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. - + method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> @@ -343,11 +343,11 @@ An array allocated by the caller that receives the identifiers corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - @@ -374,13 +374,13 @@ Provides COM objects with version-independent access to the method. One of the values. - member returns the flags. - + member returns the flags. + ]]> @@ -407,13 +407,13 @@ Provides COM objects with version-independent access to the method. An array of type containing information that matches the signature of the method (or constructor) reflected by this instance. - method gets the parameters of the specified method or constructor. - + method gets the parameters of the specified method or constructor. + ]]> @@ -440,13 +440,13 @@ Provides COM objects with version-independent access to the method. A object. - method gets the type of the current instance. - + method gets the type of the current instance. + ]]> @@ -479,11 +479,11 @@ A pointer to the requested type information object. Retrieves the type information for an object, which can be used to get the type information for an interface. - @@ -512,11 +512,11 @@ When this method returns, contains a pointer to a location that receives the number of type information interfaces provided by the object. This parameter is passed uninitialized. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - @@ -530,13 +530,13 @@ Provides COM objects with version-independent access to the method. - methods invoke the constructor reflected by the instance that has the specified parameters. - + methods invoke the constructor reflected by the instance that has the specified parameters. + ]]> @@ -564,19 +564,19 @@ The instance that created this method. - An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, should be . - + An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, should be . + If the method or constructor represented by this instance takes a parameter ( in Visual Basic), no special attribute is required for that parameter to invoke the method or constructor using this function. Any object in this array that is not explicitly initialized with a value will contain the default value for that object type. For reference type elements, this value is . For value type elements, this value is 0, 0.0, or , depending on the specific element type. Provides COM objects with version-independent access to the method. An instance of the class associated with the constructor. - method invokes the method or constructor represented by this object, using the specified parameters. - + method invokes the method or constructor represented by this object, using the specified parameters. + ]]> @@ -614,13 +614,13 @@ Provides COM objects with version-independent access to the method. An instance of the class associated with the constructor. - method invokes the constructor reflected by this object with the specified arguments, under the constraints of the specified object. - + method invokes the constructor reflected by this object with the specified arguments, under the constraints of the specified object. + ]]> @@ -663,11 +663,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - @@ -694,13 +694,13 @@ if the method is abstract; otherwise, . - property gets a value indicating whether the method is abstract. - + property gets a value indicating whether the method is abstract. + ]]> @@ -727,13 +727,13 @@ if this method can be called by other classes in the same assembly; otherwise, . - property gets a value indicating whether this method can be called by other classes in the same assembly - + property gets a value indicating whether this method can be called by other classes in the same assembly + ]]> @@ -760,13 +760,13 @@ if this method is a constructor; otherwise, . - property gets a value indicating whether the method is a constructor. - + property gets a value indicating whether the method is a constructor. + ]]> @@ -800,13 +800,13 @@ if one or more instance of the parameter is applied to this member; otherwise, . - member indicates whether one or more instances of the `attributeType` parameter are applied to this member. - + member indicates whether one or more instances of the `attributeType` parameter are applied to this member. + ]]> @@ -833,13 +833,13 @@ if access to the class is restricted to members of the class itself and to members of its derived classes; otherwise, . - property gets a value indicating whether access to this method is restricted to members of the class and members of its derived classes. - + property gets a value indicating whether access to this method is restricted to members of the class and members of its derived classes. + ]]> @@ -866,13 +866,13 @@ if access to this method is restricted to members of the class itself and to members of derived classes that are in the same assembly; otherwise, . - property gets a value indicating whether this method can be called by members of the class itself and by derived classes if they are in the same assembly - + property gets a value indicating whether this method can be called by members of the class itself and by derived classes if they are in the same assembly + ]]> @@ -899,13 +899,13 @@ if access to this method is restricted to members of the class itself, members of derived classes wherever they are, and members of other classes in the same assembly; otherwise, . - property gets a value indicating whether this method can be called by derived classes, wherever they are, and by all classes in the same assembly. - + property gets a value indicating whether this method can be called by derived classes, wherever they are, and by all classes in the same assembly. + ]]> @@ -932,13 +932,13 @@ if this method is ; otherwise, . - property gets a value indicating whether this method is `final`. - + property gets a value indicating whether this method is `final`. + ]]> @@ -965,13 +965,13 @@ if the member is hidden by signature; otherwise, . - property gets a value indicating whether only a member of the same name with exactly the same signature is hidden in the derived class. - + property gets a value indicating whether only a member of the same name with exactly the same signature is hidden in the derived class. + ]]> @@ -998,13 +998,13 @@ if access to this method is restricted to other members of the class itself; otherwise, . - property gets a value indicating whether this member is private. - + property gets a value indicating whether this member is private. + ]]> @@ -1031,13 +1031,13 @@ if this method is public; otherwise, . - property gets a value indicating whether this method is public. - + property gets a value indicating whether this method is public. + ]]> @@ -1064,13 +1064,13 @@ if this method has a special name; otherwise, . - property gets a value indicating whether this method has a special name. - + property gets a value indicating whether this method has a special name. + ]]> @@ -1097,13 +1097,13 @@ if this method is ; otherwise, . - property gets a value indicating whether the method is `static`. - + property gets a value indicating whether the method is `static`. + ]]> @@ -1130,13 +1130,13 @@ if this method is ; otherwise, . - property gets a value indicating whether the method is `virtual`. - + property gets a value indicating whether the method is `virtual`. + ]]> @@ -1162,13 +1162,13 @@ Provides COM objects with version-independent access to the property. One of the values indicating the type of member. - property gets a value indicating the type of the member - method, constructor, event, and so on. - + property gets a value indicating the type of the member - method, constructor, event, and so on. + ]]> @@ -1194,13 +1194,13 @@ Provides COM objects with version-independent access to the property. A object. - property gets a handle to the internal metadata representation of a method. - + property gets a handle to the internal metadata representation of a method. + ]]> @@ -1226,13 +1226,13 @@ Provides COM objects with version-independent access to the property. A object containing the name of this member. - property gets the name of the current member. - + property gets the name of the current member. + ]]> @@ -1258,13 +1258,13 @@ Provides COM objects with version-independent access to the property. The object that was used to obtain this object. - property gets the class object that was used to obtain this `MemberInfo` object. - + property gets the class object that was used to obtain this `MemberInfo` object. + ]]> @@ -1291,11 +1291,11 @@ Provides COM objects with version-independent access to the method. A string that represents the current . - diff --git a/xml/System.Runtime.InteropServices/_MethodInfo.xml b/xml/System.Runtime.InteropServices/_MethodInfo.xml index 3d9405c513c..d520ad75b59 100644 --- a/xml/System.Runtime.InteropServices/_MethodInfo.xml +++ b/xml/System.Runtime.InteropServices/_MethodInfo.xml @@ -38,13 +38,13 @@ Exposes the public members of the class to unmanaged code. - class members that can be accessed by unmanaged COM objects. - + class members that can be accessed by unmanaged COM objects. + ]]> @@ -70,13 +70,13 @@ Provides COM objects with version-independent access to the property. One of the values. - property gets the attributes associated with this method. - + property gets the attributes associated with this method. + ]]> @@ -102,13 +102,13 @@ Provides COM objects with version-independent access to the property. One of the values. - property gets a value indicating the calling conventions for this method. - + property gets a value indicating the calling conventions for this method. + ]]> @@ -134,13 +134,13 @@ Provides COM objects with version-independent access to the property. The object for the class that declares this member. - property gets the class that declares this member. - + property gets the class that declares this member. + ]]> @@ -171,13 +171,13 @@ if the specified is equal to the current ; otherwise, . - method determines whether the specified is equal to the current . - + method determines whether the specified is equal to the current . + ]]> @@ -204,13 +204,13 @@ Provides COM objects with version-independent access to the method. A object for the first implementation of this method. - method returns the object for the method on the direct or indirect base class in which the method represented by this instance was first declared. - + method returns the object for the method on the direct or indirect base class in which the method represented by this instance was first declared. + ]]> @@ -224,13 +224,13 @@ Provides COM objects with version-independent access to the methods. - members return all attributes applied to this member. - + members return all attributes applied to this member. + ]]> @@ -261,13 +261,13 @@ Provides COM objects with version-independent access to the method. An array that contains all the custom attributes, or an array with zero (0) elements if no attributes are defined. - method returns an array containing all the custom attributes. - + method returns an array containing all the custom attributes. + ]]> @@ -300,13 +300,13 @@ Provides COM objects with version-independent access to the method. An array of custom attributes applied to this member, or an array with zero (0) elements if no attributes have been applied. - method returns an array of custom attributes identified by . - + method returns an array of custom attributes identified by . + ]]> @@ -333,13 +333,13 @@ Provides COM objects with version-independent access to the method. The hash code for the current instance. - method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. - + method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> @@ -376,11 +376,11 @@ An array allocated by the caller that receives the identifiers corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - @@ -407,13 +407,13 @@ Provides COM objects with version-independent access to the method. One of the values. - member returns the flags. - + member returns the flags. + ]]> @@ -440,13 +440,13 @@ Provides COM objects with version-independent access to the method. An array of type containing information that matches the signature of the method (or constructor) reflected by this instance. - method gets the parameters of the specified method or constructor. - + method gets the parameters of the specified method or constructor. + ]]> @@ -473,13 +473,13 @@ Provides COM objects with version-independent access to the method. A object. - method gets the type of the current instance. - + method gets the type of the current instance. + ]]> @@ -512,11 +512,11 @@ A pointer to the requested type information object. Retrieves the type information for an object, which can be used to get the type information for an interface. - @@ -545,11 +545,11 @@ When this method returns, contains a pointer to a location that receives the number of type information interfaces provided by the object. This parameter is passed uninitialized. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - @@ -563,13 +563,13 @@ Provides COM objects with version-independent access to the method. - methods invoke the constructor reflected by the instance that has the specified parameters. - + methods invoke the constructor reflected by the instance that has the specified parameters. + ]]> @@ -597,17 +597,17 @@ The instance that created this method. - An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, should be . - + An argument list for the invoked method or constructor. This is an array of objects with the same number, order, and type as the parameters of the method or constructor to be invoked. If there are no parameters, should be . + If the method or constructor represented by this instance takes a parameter ( in Visual Basic), no special attribute is required for that parameter to invoke the method or constructor using this function. Any object in this array that is not explicitly initialized with a value will contain the default value for that object type. For reference type elements, this value is . For value type elements, this value is 0, 0.0, or , depending on the specific element type. Provides COM objects with version-independent access to the method. An instance of the class associated with the constructor. - method invokes the method or constructor represented by this object, using the specified parameters. - + method invokes the method or constructor represented by this object, using the specified parameters. + ]]> @@ -645,13 +645,13 @@ Provides COM objects with version-independent access to the method. An instance of the class associated with the constructor. - method invokes the constructor reflected by this object with the specified arguments, under the constraints of the specified object. - + method invokes the constructor reflected by this object with the specified arguments, under the constraints of the specified object. + ]]> @@ -694,11 +694,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - @@ -725,13 +725,13 @@ if the method is abstract; otherwise, . - property gets a value indicating whether the method is abstract. - + property gets a value indicating whether the method is abstract. + ]]> @@ -758,13 +758,13 @@ if this method can be called by other classes in the same assembly; otherwise, . - property gets a value indicating whether this method can be called by other classes in the same assembly - + property gets a value indicating whether this method can be called by other classes in the same assembly + ]]> @@ -791,13 +791,13 @@ if this method is a constructor; otherwise, . - property gets a value indicating whether the method is a constructor. - + property gets a value indicating whether the method is a constructor. + ]]> @@ -831,13 +831,13 @@ if one or more instance of the parameter is applied to this member; otherwise, . - member indicates whether one or more instances of the `attributeType` parameter are applied to this member. - + member indicates whether one or more instances of the `attributeType` parameter are applied to this member. + ]]> @@ -864,13 +864,13 @@ if access to the class is restricted to members of the class itself and to members of its derived classes; otherwise, . - property gets a value indicating whether access to this method is restricted to members of the class and members of its derived classes. - + property gets a value indicating whether access to this method is restricted to members of the class and members of its derived classes. + ]]> @@ -897,13 +897,13 @@ if access to this method is restricted to members of the class itself and to members of derived classes that are in the same assembly; otherwise, . - property gets a value indicating whether this method can be called by members of the class itself and derived classes if they are in the same assembly - + property gets a value indicating whether this method can be called by members of the class itself and derived classes if they are in the same assembly + ]]> @@ -930,13 +930,13 @@ if access to this method is restricted to members of the class itself, members of derived classes wherever they are, and members of other classes in the same assembly; otherwise, . - property gets a value indicating whether this method can be called by derived classes, wherever they are, and by all classes in the same assembly. - + property gets a value indicating whether this method can be called by derived classes, wherever they are, and by all classes in the same assembly. + ]]> @@ -963,13 +963,13 @@ if this method is ; otherwise, . - property gets a value indicating whether this method is `final`. - + property gets a value indicating whether this method is `final`. + ]]> @@ -996,13 +996,13 @@ if the member is hidden by signature; otherwise, . - property gets a value indicating whether only a member of the same name with exactly the same signature is hidden in the derived class. - + property gets a value indicating whether only a member of the same name with exactly the same signature is hidden in the derived class. + ]]> @@ -1029,13 +1029,13 @@ if access to this method is restricted to other members of the class itself; otherwise, . - property gets a value indicating whether this member is private. - + property gets a value indicating whether this member is private. + ]]> @@ -1062,13 +1062,13 @@ if this method is public; otherwise, . - property gets a value indicating whether this method is public. - + property gets a value indicating whether this method is public. + ]]> @@ -1095,13 +1095,13 @@ if this method has a special name; otherwise, . - property gets a value indicating whether this method has a special name. - + property gets a value indicating whether this method has a special name. + ]]> @@ -1128,13 +1128,13 @@ if this method is ; otherwise, . - property gets a value indicating whether the method is `static`. - + property gets a value indicating whether the method is `static`. + ]]> @@ -1161,13 +1161,13 @@ if this method is ; otherwise, . - property gets a value indicating whether the method is `virtual`. - + property gets a value indicating whether the method is `virtual`. + ]]> @@ -1193,13 +1193,13 @@ Provides COM objects with version-independent access to the property. One of the values indicating the type of member. - property gets a value indicating the type of the member - method, constructor, event, and so on. - + property gets a value indicating the type of the member - method, constructor, event, and so on. + ]]> @@ -1225,13 +1225,13 @@ Provides COM objects with version-independent access to the property. A object. - property gets a handle to the internal metadata representation of a method. - + property gets a handle to the internal metadata representation of a method. + ]]> @@ -1257,13 +1257,13 @@ Provides COM objects with version-independent access to the property. A object containing the name of this member. - property gets the name of the current member. - + property gets the name of the current member. + ]]> @@ -1289,13 +1289,13 @@ Provides COM objects with version-independent access to the property. The object that was used to obtain this object. - property gets the class object that was used to obtain this `MemberInfo` object. - + property gets the class object that was used to obtain this `MemberInfo` object. + ]]> @@ -1321,13 +1321,13 @@ Provides COM objects with version-independent access to the property. The return type of this method. - property gets the return type of this method. - + property gets the return type of this method. + ]]> @@ -1353,13 +1353,13 @@ Provides COM objects with version-independent access to the property. An object representing the custom attributes for the return type. - property gets the custom attributes for the return type. - + property gets the custom attributes for the return type. + ]]> @@ -1386,11 +1386,11 @@ Provides COM objects with version-independent access to the method. A string that represents the current . - diff --git a/xml/System.Runtime.InteropServices/_PropertyInfo.xml b/xml/System.Runtime.InteropServices/_PropertyInfo.xml index 9b5da3aacc9..a4e30f7bbc4 100644 --- a/xml/System.Runtime.InteropServices/_PropertyInfo.xml +++ b/xml/System.Runtime.InteropServices/_PropertyInfo.xml @@ -38,13 +38,13 @@ Exposes the public members of the class to unmanaged code. - class members that can be accessed by unmanaged COM objects. - + class members that can be accessed by unmanaged COM objects. + ]]> @@ -70,13 +70,13 @@ Provides COM objects with version-independent access to the property. The attributes of this property. - property gets the attributes of this property. - + property gets the attributes of this property. + ]]> @@ -103,13 +103,13 @@ if this property can be read; otherwise, . - property gets a value indicating whether the property can be read. - + property gets a value indicating whether the property can be read. + ]]> @@ -136,13 +136,13 @@ if this property can be written to; otherwise, . - property gets a value indicating whether the property can be written to. - + property gets a value indicating whether the property can be written to. + ]]> @@ -168,13 +168,13 @@ Provides COM objects with version-independent access to the property. The object for the class that declares this member. - property gets the class that declares this member. - + property gets the class that declares this member. + ]]> @@ -205,13 +205,13 @@ if the specified is equal to the current ; otherwise, . - method determines whether the specified is equal to the current . - + method determines whether the specified is equal to the current . + ]]> @@ -225,13 +225,13 @@ Provides COM objects with version-independent access to the methods. - methods return an array of the `get` and `set` accessors on this property. - + methods return an array of the `get` and `set` accessors on this property. + ]]> @@ -258,13 +258,13 @@ Provides COM objects with version-independent access to the method. An array of objects that reflect the public , , and other accessors of the property reflected by the current instance, if accessors are found; otherwise, this method returns an array with zero (0) elements. - method returns an array whose elements reflect the public `get`, `set`, and other accessors of the property reflected by the current instance. - + method returns an array whose elements reflect the public `get`, `set`, and other accessors of the property reflected by the current instance. + ]]> @@ -295,13 +295,13 @@ Provides COM objects with version-independent access to the method. An array of objects whose elements reflect the , , and other accessors of the property reflected by the current instance. If the parameter is , this array contains public and non-public , , and other accessors. If is , this array contains only public , , and other accessors. If no accessors with the specified visibility are found, this method returns an array with zero (0) elements. - method returns an array whose elements reflect the public and, if specified, non-public `get`, `set`, and other accessors of the property reflected by the current instance. - + method returns an array whose elements reflect the public and, if specified, non-public `get`, `set`, and other accessors of the property reflected by the current instance. + ]]> @@ -315,13 +315,13 @@ Provides COM objects with version-independent access to the methods. - methods return all attributes applied to this member. - + methods return all attributes applied to this member. + ]]> @@ -352,13 +352,13 @@ Provides COM objects with version-independent access to the method. An array that contains all the custom attributes, or an array with zero elements if no attributes are defined. - method returns an array containing all the custom attributes. - + method returns an array containing all the custom attributes. + ]]> @@ -391,13 +391,13 @@ Provides COM objects with version-independent access to the method. An array of custom attributes applied to this member, or an array with zero (0) elements if no attributes have been applied. - method returns an array of custom attributes identified by . - + method returns an array of custom attributes identified by . + ]]> @@ -411,13 +411,13 @@ Provides COM objects with version-independent access to the methods. - methods return a object representing the `get` accessor for this property. - + methods return a object representing the `get` accessor for this property. + ]]> @@ -444,13 +444,13 @@ Provides COM objects with version-independent access to the method. A object representing the public accessor for this property, or if the accessor is non-public or does not exist. - method returns the public `get` accessor for this property. - + method returns the public `get` accessor for this property. + ]]> @@ -481,13 +481,13 @@ Provides COM objects with version-independent access to the method. A object representing the accessor for this property, if the parameter is . Or if is and the accessor is non-public, or if is but no accessors exist. - method returns the public or non-public `get` accessor for this property. - + method returns the public or non-public `get` accessor for this property. + ]]> @@ -514,13 +514,13 @@ Provides COM objects with version-independent access to the method. The hash code for the current instance. - method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. - + method serves as a hash function for a particular type. is suitable for use in hashing algorithms and data structures such as a hash table. + ]]> @@ -557,11 +557,11 @@ An array allocated by the caller that receives the identifiers corresponding to the names. Maps a set of names to a corresponding set of dispatch identifiers. - @@ -588,13 +588,13 @@ Provides COM objects with version-independent access to the method. An array of type containing the parameters for the indexes. - method returns an array of all the index parameters for the property - + method returns an array of all the index parameters for the property + ]]> @@ -608,13 +608,13 @@ Provides COM objects with version-independent access to the methods. - methods return a object representing the `set` accessor for this property. - + methods return a object representing the `set` accessor for this property. + ]]> @@ -641,13 +641,13 @@ Provides COM objects with version-independent access to the method. The object representing the method for this property if the accessor is public, or if the accessor is not public. - method returns the public `set` accessor for this property. - + method returns the public `set` accessor for this property. + ]]> @@ -676,25 +676,25 @@ to return a non-public accessor; otherwise, . Provides COM objects with version-independent access to the method. - One of the values in the following table. - - Value - - Meaning - - A object representing the method for this property. - - The accessor is public, OR the parameter is and the accessor is non-public. - + One of the values in the following table. + + Value + + Meaning + + A object representing the method for this property. + + The accessor is public, OR the parameter is and the accessor is non-public. + The parameter is , but the property is read-only, OR the parameter is and the accessor is non-public, OR there is no accessor. - method returns the `set` accessor for this property. - + method returns the `set` accessor for this property. + ]]> @@ -721,13 +721,13 @@ Provides COM objects with version-independent access to the method. A object. - method gets the type of the current instance. - + method gets the type of the current instance. + ]]> @@ -760,11 +760,11 @@ A pointer to the requested type information object. Retrieves the type information for an object, which can be used to get the type information for an interface. - @@ -793,11 +793,11 @@ When this method returns, contains a pointer to a location that receives the number of type information interfaces provided by the object. This parameter is passed uninitialized. Retrieves the number of type information interfaces that an object provides (either 0 or 1). - @@ -811,13 +811,13 @@ Provides COM objects with version-independent access to the methods. - methods return the value of the property. - + methods return the value of the property. + ]]> @@ -849,13 +849,13 @@ Provides COM objects with version-independent access to the method. The property value for the parameter. - method returns a literal value associated with the property by a compiler. - + method returns a literal value associated with the property by a compiler. + ]]> @@ -893,13 +893,13 @@ Provides COM objects with version-independent access to the method. The property value for the parameter. - method returns the value of a property having the specified binding, index, and . - + method returns the value of a property having the specified binding, index, and . + ]]> @@ -942,11 +942,11 @@ The index of the first argument that has an error. Provides access to properties and methods exposed by an object. - @@ -980,13 +980,13 @@ if one or more instances of the parameter are applied to this member; otherwise, . - method indicates whether one or more instance of the `attributeType` parameter is applied to this member. - + method indicates whether one or more instance of the `attributeType` parameter is applied to this member. + ]]> @@ -1013,13 +1013,13 @@ if this property is the special name; otherwise, . - property sets a value indicating whether the property is the special name. - + property sets a value indicating whether the property is the special name. + ]]> @@ -1045,13 +1045,13 @@ Provides COM objects with version-independent access to the property. One of the values indicating that this member is a property. - property gets a value indicating that this member is a property. - + property gets a value indicating that this member is a property. + ]]> @@ -1077,13 +1077,13 @@ Provides COM objects with version-independent access to the property. A object containing the name of this member. - property gets the name of the current member. - + property gets the name of the current member. + ]]> @@ -1109,13 +1109,13 @@ Provides COM objects with version-independent access to the property. The type of this property. - property gets the type of this property. - + property gets the type of this property. + ]]> @@ -1141,13 +1141,13 @@ Provides COM objects with version-independent access to the property. The object through which this object was obtained. - property gets the class object that was used to obtain this object. - + property gets the class object that was used to obtain this object. + ]]> @@ -1161,13 +1161,13 @@ Provides COM objects with version-independent access to the method. - method sets the property value for the given object to the given value. - + method sets the property value for the given object to the given value. + ]]> @@ -1200,13 +1200,13 @@ Optional index values for indexed properties. This value should be for non-indexed properties. Provides COM objects with version-independent access to the method. - method sets the value of the property with optional index values for index properties. - + method sets the value of the property with optional index values for index properties. + ]]> @@ -1245,13 +1245,13 @@ The object that represents the culture for which the resource will be localized. Note that if the resource is not localized for this culture, the method will be called successively in search of a match. If this value is , the is obtained from the property. Provides COM objects with version-independent access to the method. - method sets the property value for the given object to the given value. - + method sets the property value for the given object to the given value. + ]]> @@ -1278,11 +1278,11 @@ Provides COM objects with version-independent access to the method. A string that represents the current . - diff --git a/xml/System.Runtime.InteropServices/_Type.xml b/xml/System.Runtime.InteropServices/_Type.xml index 163df05f597..4224e70255d 100644 --- a/xml/System.Runtime.InteropServices/_Type.xml +++ b/xml/System.Runtime.InteropServices/_Type.xml @@ -75,7 +75,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the in which the type is declared. For generic types, this property gets the in which the generic type is defined. + The property gets the in which the type is declared. For generic types, this property gets the in which the generic type is defined. ]]> @@ -107,7 +107,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the assembly-qualified name of the , including the name of the assembly from which the was loaded. + The property gets the assembly-qualified name of the , including the name of the assembly from which the was loaded. ]]> @@ -139,7 +139,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the attributes associated with the . + The property gets the attributes associated with the . ]]> @@ -171,7 +171,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the type from which the current directly inherits. + The property gets the type from which the current directly inherits. ]]> @@ -203,7 +203,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the class that declares this member. + The property gets the class that declares this member. ]]> @@ -425,7 +425,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the fully qualified name of the , including the namespace of the but not the assembly. + The property gets the fully qualified name of the , including the namespace of the but not the assembly. ]]> @@ -2946,7 +2946,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the GUID associated with the . + The property gets the GUID associated with the . ]]> @@ -2979,7 +2979,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property + The property ]]> @@ -3265,7 +3265,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is abstract and must be overridden. + The property gets a value indicating whether the is abstract and must be overridden. ]]> @@ -3298,7 +3298,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the string format attribute `AnsiClass` is selected for the . + The property gets a value indicating whether the string format attribute `AnsiClass` is selected for the . ]]> @@ -3331,7 +3331,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is an array. + The property gets a value indicating whether the is an array. ]]> @@ -3399,7 +3399,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the string format attribute `AutoClass` is selected for the . + The property gets a value indicating whether the string format attribute `AutoClass` is selected for the . ]]> @@ -3432,7 +3432,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the class layout attribute `AutoLayout` is selected for the . + The property gets a value indicating whether the class layout attribute `AutoLayout` is selected for the . ]]> @@ -3465,7 +3465,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is passed by reference. + The property gets a value indicating whether the is passed by reference. ]]> @@ -3498,7 +3498,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is a class; that is, not a value type or interface. + The property gets a value indicating whether the is a class; that is, not a value type or interface. ]]> @@ -3531,7 +3531,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is a COM object. + The property gets a value indicating whether the is a COM object. ]]>
@@ -3564,7 +3564,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the can be hosted in a context. + The property gets a value indicating whether the can be hosted in a context. ]]>
@@ -3636,7 +3636,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the current represents an enumeration. + The property gets a value indicating whether the current represents an enumeration. ]]>
@@ -3669,7 +3669,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the class layout attribute `ExplicitLayout` is selected for the . + The property gets a value indicating whether the class layout attribute `ExplicitLayout` is selected for the . ]]>
@@ -3702,7 +3702,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the has , indicating that it was imported from a COM type library. + The property gets a value indicating whether the has , indicating that it was imported from a COM type library. ]]>
@@ -3772,7 +3772,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is an interface; that is, not a class or a value type. + The property gets a value indicating whether the is an interface; that is, not a class or a value type. ]]>
@@ -3805,7 +3805,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the class layout attribute `SequentialLayout` is selected for the . + The property gets a value indicating whether the class layout attribute `SequentialLayout` is selected for the . ]]>
@@ -3838,7 +3838,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the Type is marshaled by reference. + The property gets a value indicating whether the Type is marshaled by reference. ]]>
@@ -3871,7 +3871,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is nested and visible only within its own assembly. + The property gets a value indicating whether the is nested and visible only within its own assembly. ]]>
@@ -3904,7 +3904,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is nested and visible only to classes that belong to both its own family and its own assembly. + The property gets a value indicating whether the is nested and visible only to classes that belong to both its own family and its own assembly. ]]>
@@ -3937,7 +3937,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is nested and visible only within its own family. + The property gets a value indicating whether the is nested and visible only within its own family. ]]>
@@ -3970,7 +3970,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is nested and visible only to classes that belong to either its own family or to its own assembly. + The property gets a value indicating whether the is nested and visible only to classes that belong to either its own family or to its own assembly. ]]>
@@ -4003,7 +4003,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is nested and declared private. + The property gets a value indicating whether the is nested and declared private. ]]>
@@ -4036,7 +4036,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether a class is nested and declared public. + The property gets a value indicating whether a class is nested and declared public. ]]>
@@ -4069,7 +4069,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the top-level is not declared public. + The property gets a value indicating whether the top-level is not declared public. ]]>
@@ -4102,7 +4102,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is a pointer. + The property gets a value indicating whether the is a pointer. ]]>
@@ -4135,7 +4135,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is one of the primitive types. + The property gets a value indicating whether the is one of the primitive types. ]]>
@@ -4168,7 +4168,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the top-level is declared public. + The property gets a value indicating whether the top-level is declared public. ]]>
@@ -4201,7 +4201,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is declared sealed. + The property gets a value indicating whether the is declared sealed. ]]>
@@ -4234,7 +4234,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is serializable. + The property gets a value indicating whether the is serializable. ]]>
@@ -4267,7 +4267,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the has a name that requires special handling. + The property gets a value indicating whether the has a name that requires special handling. ]]>
@@ -4337,7 +4337,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the string format attribute `UnicodeClass` is selected for the . + The property gets a value indicating whether the string format attribute `UnicodeClass` is selected for the . ]]>
@@ -4370,7 +4370,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating whether the is a value type. + The property gets a value indicating whether the is a value type. ]]>
@@ -4402,7 +4402,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets a value indicating that this member is a type or a nested type. + The property gets a value indicating that this member is a type or a nested type. ]]>
@@ -4434,7 +4434,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the module (the DLL) in which the current is defined. + The property gets the module (the DLL) in which the current is defined. ]]>
@@ -4466,7 +4466,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the name of the . + The property gets the name of the . ]]>
@@ -4498,7 +4498,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the namespace of the . + The property gets the namespace of the . ]]>
@@ -4530,7 +4530,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the class object that was used to obtain this member. + The property gets the class object that was used to obtain this member. ]]>
@@ -4595,7 +4595,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the handle for the current . + The property gets the handle for the current . ]]>
@@ -4627,7 +4627,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property gets the initializer for the . + The property gets the initializer for the . ]]>
@@ -4659,7 +4659,7 @@ ## Remarks This property is for access to managed classes from unmanaged code, and should not be called from managed code. - The property indicates the type provided by the common language runtime that represents this type. + The property indicates the type provided by the common language runtime that represents this type. ]]>
diff --git a/xml/System.Runtime.Remoting.Activation/IActivator.xml b/xml/System.Runtime.Remoting.Activation/IActivator.xml index a56cee6b8d4..639aaa914cd 100644 --- a/xml/System.Runtime.Remoting.Activation/IActivator.xml +++ b/xml/System.Runtime.Remoting.Activation/IActivator.xml @@ -22,13 +22,13 @@ Provides the basic functionality for a remoting activator class. - property to form a hierarchy that must be observed. - + property to form a hierarchy that must be observed. + ]]> @@ -95,11 +95,11 @@ Gets the where this activator is active. The where this activator is active. - is used to locate the right position in the chain when adding an activator. - + is used to locate the right position in the chain when adding an activator. + ]]> diff --git a/xml/System.Runtime.Remoting.Activation/IConstructionCallMessage.xml b/xml/System.Runtime.Remoting.Activation/IConstructionCallMessage.xml index f84b26f10ff..50be5bb8840 100644 --- a/xml/System.Runtime.Remoting.Activation/IConstructionCallMessage.xml +++ b/xml/System.Runtime.Remoting.Activation/IConstructionCallMessage.xml @@ -32,11 +32,11 @@ Represents the construction call request of an object. - and before the thread returns to the user code, a is sent to the remote application. When the construction message arrives at the remote application, it is processed by a remoting activator (either the default one, or one that is specified in the property) and a new object is created. The remoting application then returns a to the local application. The contains an instance of , which packages information about the remote object. The remoting infrastructure converts the instance into a proxy to the remote object, which is returned to the user code. - + and before the thread returns to the user code, a is sent to the remote application. When the construction message arrives at the remote application, it is processed by a remoting activator (either the default one, or one that is specified in the property) and a new object is created. The remoting application then returns a to the local application. The contains an instance of , which packages information about the remote object. The remoting infrastructure converts the instance into a proxy to the remote object, which is returned to the user code. + ]]> @@ -132,13 +132,13 @@ Gets or sets the activator that activates the remote object. The activator that activates the remote object. - property on the activator that is returned by the current property to traverse the chain of activators. - - If you add your own activator into the message's activator chain on the client side, the activator may be serialized and transported to the server side, if deemed necessary. For this reason, custom activators should be fairly lightweight in terms of serialization requirements. - + property on the activator that is returned by the current property to traverse the chain of activators. + + If you add your own activator into the message's activator chain on the client side, the activator may be serialized and transported to the server side, if deemed necessary. For this reason, custom activators should be fairly lightweight in terms of serialization requirements. + ]]> The immediate caller does not have infrastructure permission. @@ -171,11 +171,11 @@ Gets the call site activation attributes. The call site activation attributes. - indexer allows you to specify additional attributes to use during object activation. The user specifies the in the `activationAttributes` parameter to . - + indexer allows you to specify additional attributes to use during object activation. The user specifies the in the `activationAttributes` parameter to . + ]]> The immediate caller does not have infrastructure permission. @@ -208,11 +208,11 @@ Gets a list of context properties that define the context in which the object is to be created. A list of properties of the context in which to construct the object. - contains the list of properties that were contributed by various attributes in the construction call message. These properties are used to create the context in which the server object is activated. - + contains the list of properties that were contributed by various attributes in the construction call message. These properties are used to create the context in which the server object is activated. + ]]> The immediate caller does not have infrastructure permission. diff --git a/xml/System.Runtime.Remoting.Activation/UrlAttribute.xml b/xml/System.Runtime.Remoting.Activation/UrlAttribute.xml index a8a18a73d9b..58c7ef44ca4 100644 --- a/xml/System.Runtime.Remoting.Activation/UrlAttribute.xml +++ b/xml/System.Runtime.Remoting.Activation/UrlAttribute.xml @@ -33,33 +33,33 @@ Defines an attribute that can be used at the call site to specify the URL where the activation will happen. This class cannot be inherited. - is passed in the activation attributes array as a parameter to when creating activated objects with the method. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - - - -## Examples - The following code example illustrates the use of the in setting up client-activated remoting. The example contains three parts: a client, a server, and a remote object that is used by the client and server. - - The following code example shows a client: - + is passed in the activation attributes array as a parameter to when creating activated objects with the method. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + + + +## Examples + The following code example illustrates the use of the in setting up client-activated remoting. The example contains three parts: a client, a server, and a remote object that is used by the client and server. + + The following code example shows a client: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Activation.UrlAttribute/CPP/client.cpp" id="Snippet0"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Activation/UrlAttribute/Overview/client.cs" id="Snippet0"::: - - The following code example shows a server for this client: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Activation/UrlAttribute/Overview/client.cs" id="Snippet0"::: + + The following code example shows a server for this client: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Activation.UrlAttribute/CPP/server.cpp" id="Snippet2"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Activation/UrlAttribute/Overview/server.cs" id="Snippet2"::: - - The following code example shows the remote object that is used by the client and the server: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Activation/UrlAttribute/Overview/server.cs" id="Snippet2"::: + + The following code example shows the remote object that is used by the client and the server: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Activation.UrlAttribute/CPP/remoteobject.cpp" id="Snippet3"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Activation/UrlAttribute/Overview/remoteobject.cs" id="Snippet3"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Activation/UrlAttribute/Overview/remoteobject.cs" id="Snippet3"::: + ]]> @@ -93,14 +93,14 @@ The call site URL. Creates a new instance of the class. - constructor. - + constructor. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Activation.UrlAttribute/CPP/client.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Activation/UrlAttribute/Overview/client.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Activation/UrlAttribute/Overview/client.cs" id="Snippet1"::: + ]]> The parameter is . @@ -139,11 +139,11 @@ if the object is a with the same value; otherwise, . - method. - + method. + ]]> The immediate caller does not have infrastructure permission. @@ -214,11 +214,11 @@ The of the server object to create. Forces the creation of the context and the server object inside the context at the specified URL. - does not contribute any properties to the new context because it is used by the remoting infrastructure to force the creation of the context and the server object inside the context at the specified URL. - + does not contribute any properties to the new context because it is used by the remoting infrastructure to force the creation of the context and the server object inside the context at the specified URL. + ]]> The immediate caller does not have infrastructure permission. @@ -293,14 +293,14 @@ Gets the URL value of the . The URL value of the . - property of the . - + property of the . + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Activation.UrlAttribute/CPP/client.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Activation/UrlAttribute/Overview/client.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Activation/UrlAttribute/Overview/client.cs" id="Snippet1"::: + ]]> The immediate caller does not have infrastructure permission. diff --git a/xml/System.Runtime.Remoting.Channels.Http/HttpChannel.xml b/xml/System.Runtime.Remoting.Channels.Http/HttpChannel.xml index b60215db976..5db54a52839 100644 --- a/xml/System.Runtime.Remoting.Channels.Http/HttpChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Http/HttpChannel.xml @@ -545,7 +545,7 @@ property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Http.HttpClientChannel/CPP/client.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Http/HttpChannel/Overview/client.cs" id="Snippet12"::: @@ -583,7 +583,7 @@ ## Examples - The following code example shows how to use the property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Http.HttpClientChannel/CPP/client.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Http/HttpChannel/Overview/client.cs" id="Snippet12"::: diff --git a/xml/System.Runtime.Remoting.Channels.Http/HttpClientChannel.xml b/xml/System.Runtime.Remoting.Channels.Http/HttpClientChannel.xml index bf8d66ea413..fa46d30c473 100644 --- a/xml/System.Runtime.Remoting.Channels.Http/HttpClientChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Http/HttpClientChannel.xml @@ -184,7 +184,7 @@ property using the `name` parameter. + This constructor sets the property using the `name` parameter. @@ -304,7 +304,7 @@ ## Examples - The following code example shows how to use the property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Http.HttpClientChannel/CPP/client.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Http/HttpChannel/Overview/client.cs" id="Snippet11"::: @@ -367,7 +367,7 @@ property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Http.HttpClientChannel/CPP/client.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Http/HttpChannel/Overview/client.cs" id="Snippet12"::: @@ -405,7 +405,7 @@ ## Examples - The following code example shows how to use the property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Http.HttpClientChannel/CPP/client.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Http/HttpChannel/Overview/client.cs" id="Snippet12"::: diff --git a/xml/System.Runtime.Remoting.Channels.Http/HttpServerChannel.xml b/xml/System.Runtime.Remoting.Channels.Http/HttpServerChannel.xml index 8b4d59dcfda..d1f760d065a 100644 --- a/xml/System.Runtime.Remoting.Channels.Http/HttpServerChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Http/HttpServerChannel.xml @@ -200,7 +200,7 @@ property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. + This constructor sets the property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. To request that an available port be dynamically assigned, set the `port` parameter to 0 (zero). @@ -244,7 +244,7 @@ property using the `name` parameter. + This constructor sets the property using the `name` parameter. To request that an available port be dynamically assigned, set the `port` parameter to 0 (zero). @@ -422,7 +422,7 @@ ## Examples - The following code example shows how to use the property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Http.HttpServerChannel/CPP/server.cpp" id="Snippet21"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Http/HttpServerChannel/Overview/server.cs" id="Snippet21"::: @@ -458,7 +458,7 @@ property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Http.HttpServerChannel/CPP/server.cpp" id="Snippet23"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Http/HttpServerChannel/Overview/server.cs" id="Snippet23"::: @@ -749,7 +749,7 @@ property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Http.HttpServerChannel/CPP/server.cpp" id="Snippet24"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Http/HttpServerChannel/Overview/server.cs" id="Snippet24"::: diff --git a/xml/System.Runtime.Remoting.Channels.Ipc/IpcChannel.xml b/xml/System.Runtime.Remoting.Channels.Ipc/IpcChannel.xml index bb7f39126b9..cf90e1a408f 100644 --- a/xml/System.Runtime.Remoting.Channels.Ipc/IpcChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Ipc/IpcChannel.xml @@ -248,7 +248,7 @@ ## Examples - The following code example shows how to use the property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Ipc.IpcChannel/CPP/server.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Ipc/IpcChannel/Overview/server.cs" id="Snippet15"::: @@ -288,7 +288,7 @@ ## Examples - The following code example shows how to use the property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Ipc.IpcChannel/CPP/server.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Ipc/IpcChannel/Overview/server.cs" id="Snippet12"::: @@ -328,7 +328,7 @@ ## Examples - The following code example shows how to use the property. This code example is part of a larger example provided for the class. + The following code example shows how to use the property. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Ipc.IpcChannel/CPP/server.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Ipc/IpcChannel/Overview/server.cs" id="Snippet13"::: diff --git a/xml/System.Runtime.Remoting.Channels.Ipc/IpcClientChannel.xml b/xml/System.Runtime.Remoting.Channels.Ipc/IpcClientChannel.xml index 7d9e77b23c2..4668a64f6d5 100644 --- a/xml/System.Runtime.Remoting.Channels.Ipc/IpcClientChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Ipc/IpcClientChannel.xml @@ -176,7 +176,7 @@ property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. + This constructor sets the property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. If you do not require sink functionality, set the `sinkProvider` parameter to `null`. @@ -223,7 +223,7 @@ ## Examples - The following code example shows how to use the property. + The following code example shows how to use the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Ipc.IpcClientChannel/CPP/client.cpp" id="Snippet21"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Ipc/IpcClientChannel/.ctor/client.cs" id="Snippet21"::: @@ -263,7 +263,7 @@ ## Examples - The following code example shows how to use the property. + The following code example shows how to use the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Ipc.IpcClientChannel/CPP/client.cpp" id="Snippet23"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Ipc/IpcClientChannel/.ctor/client.cs" id="Snippet23"::: diff --git a/xml/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel.xml b/xml/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel.xml index 969c4a05d63..0b039642e9d 100644 --- a/xml/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel.xml @@ -176,7 +176,7 @@ property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. + This constructor sets the property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. @@ -256,7 +256,7 @@ property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. + This constructor sets the property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. If you do not require sink functionality, set the `sinkProvider` parameter to `null`. @@ -303,7 +303,7 @@ ## Examples - The following code example shows how to use the property. + The following code example shows how to use the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Ipc.IpcServerChannel/CPP/server.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel/.ctor/server.cs" id="Snippet15"::: @@ -343,7 +343,7 @@ ## Examples - The following code example shows how to use the property. + The following code example shows how to use the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Ipc.IpcServerChannel/CPP/server.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel/.ctor/server.cs" id="Snippet12"::: @@ -383,7 +383,7 @@ ## Examples - The following code example shows how to use the property. + The following code example shows how to use the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Channels.Ipc.IpcServerChannel/CPP/server.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels.Ipc/IpcServerChannel/.ctor/server.cs" id="Snippet13"::: diff --git a/xml/System.Runtime.Remoting.Channels.Tcp/TcpChannel.xml b/xml/System.Runtime.Remoting.Channels.Tcp/TcpChannel.xml index c63426b47cd..dd4f2bac117 100644 --- a/xml/System.Runtime.Remoting.Channels.Tcp/TcpChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Tcp/TcpChannel.xml @@ -271,7 +271,7 @@ . To set the property, assign the value to the "name" indexed property in the dictionary passed to the constructor. + Every registered channel has a unique name. The name is used to retrieve a specific channel when calling . To set the property, assign the value to the "name" indexed property in the dictionary passed to the constructor. diff --git a/xml/System.Runtime.Remoting.Channels.Tcp/TcpClientChannel.xml b/xml/System.Runtime.Remoting.Channels.Tcp/TcpClientChannel.xml index 9866f338cc4..3f67874f952 100644 --- a/xml/System.Runtime.Remoting.Channels.Tcp/TcpClientChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Tcp/TcpClientChannel.xml @@ -179,7 +179,7 @@ property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. + This constructor sets the property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. If you do not require sink functionality, set the `sinkProvider` parameter to `null`. diff --git a/xml/System.Runtime.Remoting.Channels.Tcp/TcpServerChannel.xml b/xml/System.Runtime.Remoting.Channels.Tcp/TcpServerChannel.xml index c9d4fe274b4..a2a583d6fd8 100644 --- a/xml/System.Runtime.Remoting.Channels.Tcp/TcpServerChannel.xml +++ b/xml/System.Runtime.Remoting.Channels.Tcp/TcpServerChannel.xml @@ -182,7 +182,7 @@ property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. + This constructor sets the property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. To request that an available port be dynamically assigned, set the `port` parameter to 0 (zero). @@ -261,7 +261,7 @@ property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. + This constructor sets the property by using the `name` parameter. If you want to register more than one channel, each channel must have a unique name. To request that an available port be dynamically assigned, set the `port` parameter to 0 (zero). diff --git a/xml/System.Runtime.Remoting.Contexts/ContextAttribute.xml b/xml/System.Runtime.Remoting.Contexts/ContextAttribute.xml index 59f59dbe2f1..e011ae3bb61 100644 --- a/xml/System.Runtime.Remoting.Contexts/ContextAttribute.xml +++ b/xml/System.Runtime.Remoting.Contexts/ContextAttribute.xml @@ -44,11 +44,11 @@ Provides the default implementations of the and interfaces. - class is the root for all context attributes. Simple class properties can be derived from with the context attribute and the context property being in the class. For more specialized or more sophisticated needs, the context attribute can derive from and the context property can be split into a separated class. For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - + class is the root for all context attributes. Simple class properties can be derived from with the context attribute and the context property being in the class. For more specialized or more sophisticated needs, the context attribute can derive from and the context property can be split into a separated class. For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + ]]> @@ -172,11 +172,11 @@ The context to freeze. Called when the context is frozen. - @@ -246,11 +246,11 @@ The to which to add the context property. Adds the current context property to the given message. - class is an implementation of an property. The method adds the property to the given class so that when the message is received, the new object can be created in the required context environment. - + class is an implementation of an property. The method adds the property to the given class so that when the message is received, the new object can be created in the required context environment. + ]]> The parameter is . @@ -333,14 +333,14 @@ if the context property is okay with the new context; otherwise, . - property of the new context and determine whether it is compatible with these other context properties. - + property of the new context and determine whether it is compatible with these other context properties. + > [!NOTE] -> By default, the method returns `true`. - +> By default, the method returns `true`. + ]]> @@ -376,11 +376,11 @@ Gets the name of the context attribute. The name of the context attribute. - as the property name. - + as the property name. + ]]> diff --git a/xml/System.Runtime.Remoting.Contexts/IContextAttribute.xml b/xml/System.Runtime.Remoting.Contexts/IContextAttribute.xml index c70e60bbfd6..0c0d0c13c71 100644 --- a/xml/System.Runtime.Remoting.Contexts/IContextAttribute.xml +++ b/xml/System.Runtime.Remoting.Contexts/IContextAttribute.xml @@ -22,11 +22,11 @@ Identifies a context attribute. - class is exposed from all context attributes. The attributes contribute a property that resides in a context and enforces a specific policy for the objects created in that context. For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - + class is exposed from all context attributes. The attributes contribute a property that resides in a context and enforces a specific policy for the objects created in that context. For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + ]]> @@ -62,11 +62,11 @@ The to which to add the context properties. Returns context properties to the caller in the given message. - method can add context properties directly to the property list in the interface. The default implementation in the class will add this to the context property list. Context attributes are free to override and can implement their own behavior. For example, they can add to the list a new class that implements the context property. - + method can add context properties directly to the property list in the interface. The default implementation in the class will add this to the context property list. Context attributes are free to override and can implement their own behavior. For example, they can add to the list a new class that implements the context property. + ]]> diff --git a/xml/System.Runtime.Remoting.Lifetime/ClientSponsor.xml b/xml/System.Runtime.Remoting.Lifetime/ClientSponsor.xml index 359597ea22b..d592265e320 100644 --- a/xml/System.Runtime.Remoting.Lifetime/ClientSponsor.xml +++ b/xml/System.Runtime.Remoting.Lifetime/ClientSponsor.xml @@ -33,23 +33,23 @@ Provides a default implementation for a lifetime sponsor class. - . - + . + > [!NOTE] -> This class makes a link demand and an inheritance demand at the class level. A is thrown when either the immediate caller or the derived class does not have infrastructure permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands) and [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). - - - -## Examples - The following example illustrates the ClientSponsor class to extend the life of a class-activated remote object. - +> This class makes a link demand and an inheritance demand at the class level. A is thrown when either the immediate caller or the derived class does not have infrastructure permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands) and [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). + + + +## Examples + The following example illustrates the ClientSponsor class to extend the life of a class-activated remote object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/ClientSponsor_Register/CPP/clientsponsor_client.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Lifetime/ClientSponsor/Overview/clientsponsor_client.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Lifetime/ClientSponsor/Overview/clientsponsor_client.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Lifetime/ClientSponsor/Overview/clientsponsor_client.vb" id="Snippet1"::: + ]]> @@ -81,11 +81,11 @@ Initializes a new instance of the class with default values. - property. - + property. + ]]> @@ -140,13 +140,13 @@ Empties the list objects registered with the current . - @@ -208,18 +208,18 @@ Initializes a new instance of , providing a lease for the current object. An for the current object. - . - - - -## Examples + . + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/ClientSponsor_Register/CPP/clientsponsor_client.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Lifetime/ClientSponsor/Overview/clientsponsor_client.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Lifetime/ClientSponsor/Overview/clientsponsor_client.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Lifetime/ClientSponsor/Overview/clientsponsor_client.vb" id="Snippet2"::: + ]]> @@ -257,13 +257,13 @@ if registration succeeded; otherwise, . - @@ -302,18 +302,18 @@ Requests a sponsoring client to renew the lease for the specified object. The additional lease time for the specified object. - method is called by the distributed garbage collector to renew the lease for the specified object. - - - -## Examples + method is called by the distributed garbage collector to renew the lease for the specified object. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/ClientSponsor_Register/CPP/clientsponsor_client.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Lifetime/ClientSponsor/Overview/clientsponsor_client.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Lifetime/ClientSponsor/Overview/clientsponsor_client.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Lifetime/ClientSponsor/Overview/clientsponsor_client.vb" id="Snippet2"::: + ]]> @@ -339,13 +339,13 @@ Gets or sets the by which to increase the lifetime of the sponsored objects when renewal is requested. The by which to increase the lifetime of the sponsored objects when renewal is requested. - @@ -380,13 +380,13 @@ The object to unregister. Unregisters the specified from the list of objects sponsored by the current . - diff --git a/xml/System.Runtime.Remoting.Lifetime/ILease.xml b/xml/System.Runtime.Remoting.Lifetime/ILease.xml index 08dc05a5463..712f9c7d704 100644 --- a/xml/System.Runtime.Remoting.Lifetime/ILease.xml +++ b/xml/System.Runtime.Remoting.Lifetime/ILease.xml @@ -22,19 +22,19 @@ Defines a lifetime lease object that is used by the remoting lifetime service. - contains a lease manager that administers the leases in the domain. The lease manager periodically examines the leases for time expiration. If a lease has expired, it can either be canceled by removing its reference to the lease, or renewed by invoking one or more of the lease's sponsors. - - A lease contains properties that determine its policies, and methods that renew the lease time. The lease exposes the interface. - - For an example showing how to use the interface see [Lifetimes](https://msdn.microsoft.com/library/334a30e5-33cb-4f0f-a38a-ed4abc5560fa). - + contains a lease manager that administers the leases in the domain. The lease manager periodically examines the leases for time expiration. If a lease has expired, it can either be canceled by removing its reference to the lease, or renewed by invoking one or more of the lease's sponsors. + + A lease contains properties that determine its policies, and methods that renew the lease time. The lease exposes the interface. + + For an example showing how to use the interface see [Lifetimes](https://msdn.microsoft.com/library/334a30e5-33cb-4f0f-a38a-ed4abc5560fa). + ]]> @@ -131,11 +131,11 @@ Gets or sets the initial time for the lease. The initial time for the lease. - property is set to , then the lease will never time out and the object associated with it will have an infinite lifetime. - + property is set to , then the lease will never time out and the object associated with it will have an infinite lifetime. + ]]> The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -181,11 +181,11 @@ The callback object of the sponsor. Registers a sponsor for the lease without renewing the lease. - The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -257,11 +257,11 @@ Renews a lease for the specified time. The new expiration time of the lease. - or the current time plus the renewal time. - + or the current time plus the renewal time. + ]]> The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -298,11 +298,11 @@ Gets or sets the amount of time by which a call to the remote object renews the . The amount of time by which a call to the remote object renews the . - to the only if the has dropped below the . Sequential calls therefore do not increase the without bound. Instead, immediately after any call, the is guaranteed to be the or longer. - + to the only if the has dropped below the . Sequential calls therefore do not increase the without bound. Instead, immediately after any call, the is guaranteed to be the or longer. + ]]> The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -339,13 +339,13 @@ Gets or sets the amount of time to wait for a sponsor to return with a lease renewal time. The amount of time to wait for a sponsor to return with a lease renewal time. - is , then this lease will not take sponsors. - - If a sponsor does not respond to a call to renew a lease within the time-out period, it is assumed to be dead and is removed from the list of sponsors for the current lease. - + is , then this lease will not take sponsors. + + If a sponsor does not respond to a call to renew a lease within the time-out period, it is assumed to be dead and is removed from the list of sponsors for the current lease. + ]]> The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. diff --git a/xml/System.Runtime.Remoting.Lifetime/LeaseState.xml b/xml/System.Runtime.Remoting.Lifetime/LeaseState.xml index e01382e5223..b1b493c4ef3 100644 --- a/xml/System.Runtime.Remoting.Lifetime/LeaseState.xml +++ b/xml/System.Runtime.Remoting.Lifetime/LeaseState.xml @@ -28,11 +28,11 @@ Indicates the possible lease states of a lifetime lease. - property returns the lease status for a lease. - + property returns the lease status for a lease. + ]]> diff --git a/xml/System.Runtime.Remoting.Lifetime/LifetimeServices.xml b/xml/System.Runtime.Remoting.Lifetime/LifetimeServices.xml index 80e7b085940..376af455f4a 100644 --- a/xml/System.Runtime.Remoting.Lifetime/LifetimeServices.xml +++ b/xml/System.Runtime.Remoting.Lifetime/LifetimeServices.xml @@ -29,23 +29,23 @@ Controls the.NET remoting lifetime services. - [!NOTE] -> This class makes a link demand. A SecurityException is thrown if the immediate caller does not have infrastructure permission. See [Link Demands](/dotnet/framework/misc/link-demands) for more information. - - - -## Examples +> This class makes a link demand. A SecurityException is thrown if the immediate caller does not have infrastructure permission. See [Link Demands](/dotnet/framework/misc/link-demands) for more information. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Lifetime/CPP/server.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Lifetime/LifetimeServices/Overview/server.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Lifetime/LifetimeServices/Overview/server.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Lifetime/LifetimeServices/Overview/server.vb" id="Snippet2"::: + ]]> @@ -102,13 +102,13 @@ Gets or sets the time interval between each activation of the lease manager to clean up expired leases. The default amount of time the lease manager sleeps after checking for expired leases. - is set to 100 seconds, the lease list is inspected for cleanups and renewals every 100 seconds. - - The default value of the property is 10 seconds. - + is set to 100 seconds, the lease list is inspected for cleanups and renewals every 100 seconds. + + The default value of the property is 10 seconds. + ]]> At least one of the callers higher in the callstack does not have permission to configure remoting types and channels. This exception is thrown only when setting the property value. @@ -141,11 +141,11 @@ Gets or sets the initial lease time span for an . The initial lease for objects that can have leases in the . - At least one of the callers higher in the callstack does not have permission to configure remoting types and channels. This exception is thrown only when setting the property value. @@ -178,18 +178,18 @@ Gets or sets the amount of time by which the lease is extended every time a call comes in on the server object. The by which a lifetime lease in the current is extended after each call. - At least one of the callers higher in the callstack does not have permission to configure remoting types and channels. This exception is thrown only when setting the property value. @@ -222,18 +222,18 @@ Gets or sets the amount of time the lease manager waits for a sponsor to return with a lease renewal time. The initial sponsorship time-out. - At least one of the callers higher in the callstack does not have permission to configure remoting types and channels. This exception is thrown only when setting the property value. diff --git a/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml b/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml index 8be4c622616..3bbd675a9f8 100644 --- a/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml +++ b/xml/System.Runtime.Remoting.Messaging/AsyncResult.xml @@ -35,14 +35,14 @@ class is used in conjunction with asynchronous method calls made using delegates. The returned from the delegate's `BeginInvoke` method can be cast to an . The has the property that holds the delegate object on which the asynchronous call was invoked. + The class is used in conjunction with asynchronous method calls made using delegates. The returned from the delegate's `BeginInvoke` method can be cast to an . The has the property that holds the delegate object on which the asynchronous call was invoked. For more information about `BeginInvoke` and asynchronous calls using delegates, see [Asynchronous Programming Using Delegates](/dotnet/standard/asynchronous-programming-patterns/asynchronous-programming-using-delegates). ## Examples - The following example demonstrates how to use the property to get a , and how to wait for an asynchronous call on a delegate. The is signaled when the asynchronous call completes, and you can wait for it by calling the method. + The following example demonstrates how to use the property to get a , and how to wait for an asynchronous call on a delegate. The is signaled when the asynchronous call completes, and you can wait for it by calling the method. The example consists of two classes, the class that contains the method that's called asynchronously, and the class that contains the `Main` method that makes the call. @@ -84,14 +84,14 @@ property can be cast to the actual class of the user-defined delegate. + The property can be cast to the actual class of the user-defined delegate. For example, if the delegate that was used to make the asynchronous call is of type `MyDelegate`, the delegate that is returned by this property must be cast to `MyDelegate`. The callback method can then call the delegate's `EndInvoke` method with the correct signature, in order to obtain the results of the asynchronous method call. ## Examples - The following code example demonstrates how to use the property to get the delegate that was used to make the asynchronous call, in order to call `EndInvoke`. The example casts the , which is the only parameter of the callback method, to an object. + The following code example demonstrates how to use the property to get the delegate that was used to make the asynchronous call, in order to call `EndInvoke`. The example casts the , which is the only parameter of the callback method, to an object. The example consists of two classes, the class that contains the method that's called asynchronously, and the class that contains the `Main` method that makes the call. @@ -185,7 +185,7 @@ ## Examples - The following code example demonstrates how the property is used to pass information to a callback method. The last parameter of the `BeginInvoke` method call is a format string, which the callback method uses to format an output message. + The following code example demonstrates how the property is used to pass information to a callback method. The last parameter of the `BeginInvoke` method call is a format string, which the callback method uses to format an output message. The example consists of two classes, the class that contains the method that's called asynchronously, and the class that contains the `Main` method that makes the call. @@ -234,12 +234,12 @@ The wait handle is not closed automatically when you call `EndInvoke` on the delegate that was used to make the asynchronous method call. If you release all references to the wait handle, system resources are freed when garbage collection reclaims the wait handle. To free the system resources as soon as you are finished using the wait handle, call the method. Garbage collection works more efficiently when disposable objects are explicitly closed or disposed. > [!CAUTION] -> The contained in the property can be used to block the current thread until the asynchronous call is complete. However the will ignore the , if one was specified during the `BeginInvoke` call. Therefore, a situation can occur where the application shuts down before the has finished executing, even if a is used to block until the asynchronous call completion. For an example of such a situation, see the example for the class, and remove the statement. +> The contained in the property can be used to block the current thread until the asynchronous call is complete. However the will ignore the , if one was specified during the `BeginInvoke` call. Therefore, a situation can occur where the application shuts down before the has finished executing, even if a is used to block until the asynchronous call completion. For an example of such a situation, see the example for the class, and remove the statement. ## Examples - The following example demonstrates how to use the property to get a , and how to wait for an asynchronous call on a delegate. The is signaled when the asynchronous call completes, and you can wait for it by calling the method. + The following example demonstrates how to use the property to get a , and how to wait for an asynchronous call on a delegate. The is signaled when the asynchronous call completes, and you can wait for it by calling the method. The example consists of two classes, the class that contains the method that's called asynchronously, and the class that contains the `Main` method that makes the call. @@ -378,12 +378,12 @@ property to `true`. Thus, it is safe for the client to destroy the resources after the property returns `true`. + The server must not use any client supplied resources outside of the agreed upon sharing semantics after it sets the property to `true`. Thus, it is safe for the client to destroy the resources after the property returns `true`. ## Examples - The following example shows how to use the property of the returned by `BeginInvoke` to discover when an asynchronous call completes. You might do this when making the asynchronous call from a thread that services the user interface. Polling for completion allows the calling thread to continue executing while the asynchronous call executes on a thread. + The following example shows how to use the property of the returned by `BeginInvoke` to discover when an asynchronous call completes. You might do this when making the asynchronous call from a thread that services the user interface. Polling for completion allows the calling thread to continue executing while the asynchronous call executes on a thread. The example consists of two classes, the class that contains the method that's called asynchronously, and the class that contains the `Main` method that makes the call. @@ -513,7 +513,7 @@ invokes the consumer code's delegate. It also sets the instance returned by the method. If the `msg` parameter is of type , the same object is returned by . Otherwise, a reply message that contains a remoting exception is returned. - also modifies the value returned by the property. + also modifies the value returned by the property. ]]> diff --git a/xml/System.Runtime.Remoting.Messaging/ConstructionCall.xml b/xml/System.Runtime.Remoting.Messaging/ConstructionCall.xml index 5d63ace072a..b88d424b488 100644 --- a/xml/System.Runtime.Remoting.Messaging/ConstructionCall.xml +++ b/xml/System.Runtime.Remoting.Messaging/ConstructionCall.xml @@ -50,13 +50,13 @@ Implements the interface to create a request message that constitutes a constructor call on a remote object. - class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. - - A remoting client sends a message to a server when attempting to create an instance of a client-activated remote class. - + class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. + + A remoting client sends a message to a server when attempting to create an instance of a client-activated remote class. + ]]> @@ -87,11 +87,11 @@ An array of remoting headers that contain key-value pairs. This array is used to initialize fields for those headers that belong to the namespace "http://schemas.microsoft.com/clr/soap/messageProperties". Initializes a new instance of the class from an array of remoting headers. - class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. - + class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. + ]]> @@ -118,11 +118,11 @@ A remoting message. Initializes a new instance of the class by copying an existing message. - class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. - + class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. + ]]> @@ -327,11 +327,11 @@ Gets an interface that represents a collection of the remoting message's properties. An interface that represents a collection of the remoting message's properties. - property returns the value of the inherited field. - + property returns the value of the inherited field. + ]]> diff --git a/xml/System.Runtime.Remoting.Messaging/ConstructionResponse.xml b/xml/System.Runtime.Remoting.Messaging/ConstructionResponse.xml index ce5e6b80962..54f8c36ce7b 100644 --- a/xml/System.Runtime.Remoting.Messaging/ConstructionResponse.xml +++ b/xml/System.Runtime.Remoting.Messaging/ConstructionResponse.xml @@ -50,13 +50,13 @@ Implements the interface to create a message that responds to a call to instantiate a remote object. - object returns the result of a construction request sent with the interface. - - The class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. - + object returns the result of a construction request sent with the interface. + + The class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. + ]]> @@ -89,11 +89,11 @@ A request message that constitutes a constructor call on a remote object. Initializes a new instance of the class from an array of remoting headers and a request message. - class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. - + class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. + ]]> @@ -129,11 +129,11 @@ Gets an interface that represents a collection of the remoting message's properties. An interface that represents a collection of the remoting message's properties. - property returns the value of the inherited field. - + property returns the value of the inherited field. + ]]> diff --git a/xml/System.Runtime.Remoting.Messaging/IMethodCallMessage.xml b/xml/System.Runtime.Remoting.Messaging/IMethodCallMessage.xml index f4b3ae32fe0..f56b2d874eb 100644 --- a/xml/System.Runtime.Remoting.Messaging/IMethodCallMessage.xml +++ b/xml/System.Runtime.Remoting.Messaging/IMethodCallMessage.xml @@ -29,18 +29,18 @@ Defines the method call message interface. - is generated as a result of a method called on a remote object, and is used to transport details about the remote method call to the server side. - - - -## Examples + is generated as a result of a method called on a remote object, and is used to transport details about the remote method call to the server side. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/IMethodCallMessage_GetInArg/CPP/imethodcallmessage.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Messaging/IMethodCallMessage/Overview/imethodcallmessage.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Messaging/IMethodCallMessage/Overview/imethodcallmessage.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Messaging/IMethodCallMessage/Overview/imethodcallmessage.vb" id="Snippet1"::: + ]]> @@ -140,15 +140,15 @@ Gets the number of arguments in the call that are not marked as parameters. The number of arguments in the call that are not marked as parameters. - The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -181,18 +181,18 @@ Gets an array of arguments that are not marked as parameters. An array of arguments that are not marked as parameters. - property is redundant since the same functionality can be achieved with the and methods, there might be performance optimization available if the implementer understands when all the arguments will be retrieved. - - - -## Examples + property is redundant since the same functionality can be achieved with the and methods, there might be performance optimization available if the implementer understands when all the arguments will be retrieved. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/IMethodCallMessage_GetInArg/CPP/imethodcallmessage.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Messaging/IMethodCallMessage/Overview/imethodcallmessage.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Messaging/IMethodCallMessage/Overview/imethodcallmessage.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Messaging/IMethodCallMessage/Overview/imethodcallmessage.vb" id="Snippet2"::: + ]]> The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. diff --git a/xml/System.Runtime.Remoting.Messaging/IMethodMessage.xml b/xml/System.Runtime.Remoting.Messaging/IMethodMessage.xml index 9af721e4fc8..537d5f16b9b 100644 --- a/xml/System.Runtime.Remoting.Messaging/IMethodMessage.xml +++ b/xml/System.Runtime.Remoting.Messaging/IMethodMessage.xml @@ -26,20 +26,20 @@ Defines the method message interface. - interface. - - - -## Examples - The following example code shows a custom proxy that overrides `RealProxy.Invoke` in order to write the message information to the console and return immediately without making a remote call. - + interface. + + + +## Examples + The following example code shows a custom proxy that overrides `RealProxy.Invoke` in order to write the message information to the console and return immediately without making a remote call. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/IMethodMessage_MethodName/CPP/imethodmessage_methodname.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Messaging/IMethodMessage/Overview/imethodmessage_methodname.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Messaging/IMethodMessage/Overview/imethodmessage_methodname.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Messaging/IMethodMessage/Overview/imethodmessage_methodname.vb" id="Snippet1"::: + ]]> @@ -71,15 +71,15 @@ Gets the number of arguments passed to the method. The number of arguments passed to the method. - The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -112,11 +112,11 @@ Gets an array of arguments passed to the method. An array containing the arguments passed to the method. - property is redundant since the same functionality can be achieved through the and , there might be performance optimization available if the implementer understands when all the arguments will be retrieved. - + property is redundant since the same functionality can be achieved through the and , there might be performance optimization available if the implementer understands when all the arguments will be retrieved. + ]]> The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -218,15 +218,15 @@ if the method can accept a variable number of arguments; otherwise, . - The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -259,15 +259,15 @@ Gets the for the current method call. Gets the for the current method call. - The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -300,11 +300,11 @@ Gets the of the called method. The of the called method. - The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -337,15 +337,15 @@ Gets the name of the invoked method. The name of the invoked method. - The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -378,11 +378,11 @@ Gets an object containing the method signature. An object containing the method signature. - return an array of objects containing the parameter types of the method. - + return an array of objects containing the parameter types of the method. + ]]> The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. diff --git a/xml/System.Runtime.Remoting.Messaging/IMethodReturnMessage.xml b/xml/System.Runtime.Remoting.Messaging/IMethodReturnMessage.xml index eb3e54c7c0c..131e6049997 100644 --- a/xml/System.Runtime.Remoting.Messaging/IMethodReturnMessage.xml +++ b/xml/System.Runtime.Remoting.Messaging/IMethodReturnMessage.xml @@ -29,20 +29,20 @@ Defines the method call return message interface. - is generated as a result of a method called on a remote object, and is used to return the results of the method call back to the caller. - - - -## Examples - The following example code shows a custom proxy that overrides `RealProxy.Invoke` in order to write the return message information to the console. - + is generated as a result of a method called on a remote object, and is used to return the results of the method call back to the caller. + + + +## Examples + The following example code shows a custom proxy that overrides `RealProxy.Invoke` in order to write the return message information to the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/IMethodReturnMessage_ReturnValue/CPP/imethodreturnmessage_returnvalue.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Messaging/IMethodReturnMessage/Overview/imethodreturnmessage_returnvalue.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Messaging/IMethodReturnMessage/Overview/imethodreturnmessage_returnvalue.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Messaging/IMethodReturnMessage/Overview/imethodreturnmessage_returnvalue.vb" id="Snippet1"::: + ]]> @@ -74,15 +74,15 @@ Gets the exception thrown during the method call. The exception object for the method call, or if the method did not throw an exception. - The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -183,15 +183,15 @@ Gets the number of arguments in the method call marked as or parameters. The number of arguments in the method call marked as or parameters. - The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. @@ -224,21 +224,21 @@ Returns the specified argument marked as a or an parameter. The specified argument marked as a or an parameter. - property is redundant since the same functionality can be achieved through the field and method, there might be performance optimization available if the implementer understands when all the arguments will be retrieved. - + property is redundant since the same functionality can be achieved through the field and method, there might be performance optimization available if the implementer understands when all the arguments will be retrieved. + > [!WARNING] -> If is not `null`, a exception is thrown when is accessed. - - - -## Examples +> If is not `null`, a exception is thrown when is accessed. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/IMethodReturnMessage_ReturnValue/CPP/imethodreturnmessage_returnvalue.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Messaging/IMethodReturnMessage/Overview/imethodreturnmessage_returnvalue.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Messaging/IMethodReturnMessage/Overview/imethodreturnmessage_returnvalue.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Messaging/IMethodReturnMessage/Overview/imethodreturnmessage_returnvalue.vb" id="Snippet2"::: + ]]> The immediate caller makes the call through a reference to the interface and does not have infrastructure permission. diff --git a/xml/System.Runtime.Remoting.Messaging/MessageSurrogateFilter.xml b/xml/System.Runtime.Remoting.Messaging/MessageSurrogateFilter.xml index 55b14e2118d..88f63f7ec9d 100644 --- a/xml/System.Runtime.Remoting.Messaging/MessageSurrogateFilter.xml +++ b/xml/System.Runtime.Remoting.Messaging/MessageSurrogateFilter.xml @@ -35,15 +35,15 @@ if the class should ignore a particular property while creating an for a class. - delegate is intended for use only by the remoting infrastructure of the .NET Framework; you should not instantiate the delegate directly. - - The property of the class gets and sets a instance. - - Each key/value parameter pair is a remoting message property that belongs to the property of the class. - + delegate is intended for use only by the remoting infrastructure of the .NET Framework; you should not instantiate the delegate directly. + + The property of the class gets and sets a instance. + + Each key/value parameter pair is a remoting message property that belongs to the property of the class. + ]]> diff --git a/xml/System.Runtime.Remoting.Messaging/MethodCall.xml b/xml/System.Runtime.Remoting.Messaging/MethodCall.xml index 8de44dda28c..3273f107e3e 100644 --- a/xml/System.Runtime.Remoting.Messaging/MethodCall.xml +++ b/xml/System.Runtime.Remoting.Messaging/MethodCall.xml @@ -50,13 +50,13 @@ Implements the interface to create a request message that acts as a method call on a remote object. - class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. - - contains remoting data that is passed between message sinks. A remoting client sends a message to a server. - + class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. + + contains remoting data that is passed between message sinks. A remoting client sends a message to a server. + ]]> @@ -102,11 +102,11 @@ An array of remoting headers that contains key/value pairs. This array is used to initialize fields for headers that belong to the namespace "http://schemas.microsoft.com/clr/soap/messageProperties". Initializes a new instance of the class from an array of remoting headers. - class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. - + class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. + ]]> @@ -139,11 +139,11 @@ A remoting message. Initializes a new instance of the class by copying an existing message. - class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. - + class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. + ]]> @@ -179,11 +179,11 @@ Gets the number of arguments passed to a method. A that represents the number of arguments passed to a method. - @@ -219,11 +219,11 @@ Gets an array of arguments passed to a method. An array of type that represents the arguments passed to a method. - @@ -249,11 +249,11 @@ An interface that represents a collection of the remoting message's properties. - field is also accessible through the property. - + field is also accessible through the property. + ]]> @@ -293,11 +293,11 @@ Gets a method argument, as an object, at a specified index. The method argument as an object. - @@ -337,11 +337,11 @@ Gets the name of a method argument at a specified index. The name of the method argument. - @@ -381,11 +381,11 @@ Gets a method argument at a specified index that is not marked as an parameter. The method argument that is not marked as an parameter. - @@ -425,11 +425,11 @@ Gets the name of a method argument at a specified index that is not marked as an parameter. The name of the method argument that is not marked as an parameter. - @@ -470,11 +470,11 @@ The context of a certain serialized stream. The method is not implemented. - method throws a . - + method throws a . + ]]> @@ -511,11 +511,11 @@ if the method can accept a variable number of arguments; otherwise, . - @@ -552,11 +552,11 @@ Initializes an internal serialization handler from an array of remoting headers that are applied to a method. An internal serialization handler. - @@ -592,11 +592,11 @@ Gets the number of arguments in the method call that are not marked as parameters. A that represents the number of arguments in the method call that are not marked as parameters. - @@ -632,11 +632,11 @@ Gets an array of arguments in the method call that are not marked as parameters. An array of type that represents arguments in the method call that are not marked as parameters. - @@ -719,11 +719,11 @@ Gets the for the current method call. The for the current method call. - @@ -759,11 +759,11 @@ Gets the of the called method. The of the called method. - @@ -799,11 +799,11 @@ Gets the name of the invoked method. A that contains the name of the invoked method. - @@ -839,11 +839,11 @@ Gets an object that contains the method signature. A that contains the method signature. - @@ -879,11 +879,11 @@ Gets an interface that represents a collection of the remoting message's properties. An interface that represents a collection of the remoting message's properties. - property returns the value of the field. - + property returns the value of the field. + ]]> @@ -916,11 +916,11 @@ Sets method information from previously initialized remoting message properties. - property is set through the method. - + property is set through the method. + ]]> @@ -958,11 +958,11 @@ The context of a given serialized stream. Sets method information from serialization settings. - diff --git a/xml/System.Runtime.Remoting.Messaging/MethodResponse.xml b/xml/System.Runtime.Remoting.Messaging/MethodResponse.xml index 22955d432ae..8791d5145da 100644 --- a/xml/System.Runtime.Remoting.Messaging/MethodResponse.xml +++ b/xml/System.Runtime.Remoting.Messaging/MethodResponse.xml @@ -50,15 +50,15 @@ Implements the interface to create a message that acts as a method response on a remote object. - is generated as a result of a method called on a remote object, and is used to return the results of the method call back to the caller. The message includes a return value and `out` arguments. - - The class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. - - contains remoting data at the end of the message sink. A remoting server returns a message to a client. - + is generated as a result of a method called on a remote object, and is used to return the results of the method call back to the caller. The message includes a return value and `out` arguments. + + The class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. + + contains remoting data at the end of the message sink. A remoting server returns a message to a client. + ]]> @@ -96,11 +96,11 @@ A request message that acts as a method call on a remote object. Initializes a new instance of the class from an array of remoting headers and a request message. - class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. - + class is used by the remoting infrastructure of the .NET Framework. You do not need to create an instance of the class directly; instead, use the interface. + ]]> @@ -136,11 +136,11 @@ Gets the number of arguments passed to the method. A that represents the number of arguments passed to a method. - @@ -176,11 +176,11 @@ Gets an array of arguments passed to the method. An array of type that represents the arguments passed to a method. - @@ -216,11 +216,11 @@ Gets the exception thrown during the method call, or if the method did not throw an exception. The thrown during the method call, or if the method did not throw an exception. - @@ -246,11 +246,11 @@ Specifies an interface that represents a collection of the remoting message's properties. - field is also accessible through the property. - + field is also accessible through the property. + ]]> @@ -290,11 +290,11 @@ Gets a method argument, as an object, at a specified index. The method argument as an object. - @@ -334,11 +334,11 @@ Gets the name of a method argument at a specified index. The name of the method argument. - @@ -379,11 +379,11 @@ Context of a certain serialized stream. The method is not implemented. - method throws a . - + method throws a . + ]]> @@ -423,11 +423,11 @@ Returns the specified argument marked as a parameter or an parameter. The specified argument marked as a parameter or an parameter. - @@ -467,11 +467,11 @@ Returns the name of the specified argument marked as a parameter or an parameter. The argument name, or if the current method is not implemented. - @@ -508,11 +508,11 @@ if the method can accept a variable number of arguments; otherwise, . - @@ -549,11 +549,11 @@ Initializes an internal serialization handler from an array of remoting headers that are applied to a method. An internal serialization handler. - @@ -612,11 +612,11 @@ Gets the for the current method call. The for the current method call. - @@ -652,11 +652,11 @@ Gets the of the called method. The of the called method. - @@ -692,11 +692,11 @@ Gets the name of the invoked method. A that contains the name of the invoked method. - @@ -732,11 +732,11 @@ Gets an object that contains the method signature. A that contains the method signature. - @@ -772,11 +772,11 @@ Gets the number of arguments in the method call marked as or parameters. A that represents the number of arguments in the method call marked as or parameters. - @@ -812,11 +812,11 @@ Gets an array of arguments in the method call that are marked as or parameters. An array of type that represents the arguments in the method call that are marked as or parameters. - @@ -852,11 +852,11 @@ Gets an interface that represents a collection of the remoting message's properties. An interface that represents a collection of the remoting message's properties. - property returns the value of the field. - + property returns the value of the field. + ]]> @@ -892,11 +892,11 @@ Gets the return value of the method call. A that represents the return value of the method call. - @@ -934,11 +934,11 @@ The context of a certain serialized stream. Sets method information from serialization settings. - diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri.xml index 5f6480b303a..d1cde43b3ef 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri.xml @@ -33,20 +33,20 @@ Wraps an XSD type. - class to convert between a object and an XSD `anyURI` string. -For more information about XSD data types, see the [XML Data Types Reference](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/ms256131(v=vs.100)). - - - -## Examples - The following code example shows how to use the members in the class to convert between a object and an XSD `anyURI` string. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapAnyUri/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -78,14 +78,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Initializes a new instance of the class. - @@ -111,14 +111,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht A that contains a URI. Initializes a new instance of the class with the specified URI. - @@ -148,14 +148,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Returns the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapAnyUri/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -185,14 +185,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Converts the specified into a object. A object that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapAnyUri/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -219,14 +219,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Returns as a . A that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapAnyUri/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -252,14 +252,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Gets or sets a URI. A that contains a URI. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapAnyUri/CPP/demo.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet14"::: + ]]> @@ -285,14 +285,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapAnyUri/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapAnyUri/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapBase64Binary.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapBase64Binary.xml index cc7e40c6349..329598c6b7e 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapBase64Binary.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapBase64Binary.xml @@ -262,7 +262,7 @@ For more information about XSD data types, see the [XML Data Types Reference](ht property. This code example is part of a larger example that is provided for the class. + The following code example shows how to use the property. This code example is part of a larger example that is provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapBase64Binary/CPP/demo.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapBase64Binary/Overview/demo.cs" id="Snippet14"::: @@ -295,7 +295,7 @@ For more information about XSD data types, see the [XML Data Types Reference](ht property. This code example is part of a larger example that is provided for the class. + The following code example shows how to use the property. This code example is part of a larger example that is provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapBase64Binary/CPP/demo.cpp" id="Snippet16"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapBase64Binary/Overview/demo.cs" id="Snippet16"::: diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay.xml index e429ef55269..4773962a1dd 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay.xml @@ -33,19 +33,19 @@ Wraps an XSD type. - class to convert between a object and an XSD `gDay` string. - + + + +## Examples + The following code example shows how to use the members in the class to convert between a object and an XSD `gDay` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapDay/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -77,14 +77,14 @@ Initializes a new instance of the class. - @@ -110,14 +110,14 @@ A object to initialize the current instance. Initializes a new instance of the class with a specified object. - @@ -147,14 +147,14 @@ Returns the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapDay/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -184,24 +184,24 @@ Converts the specified into a object. A object that is obtained from . - method is capable of parsing strings in various formats. The recognizable string formats are "---ddzzz" and "---dd", which are composed out of the following format patterns. - -|Format Pattern|Description|Examples| -|--------------------|-----------------|--------------| -|dd|The day of the month. Single-digit days have a leading zero.|23, 09| -|zzz|The full time zone offset (hour and minutes) from the Universal Time Coordinate (Greenwich Mean Time). Single-digit hours have a leading zero. "Z" means the current time zone.|-07:00, +08:00, Z| - - - -## Examples - The following code example shows how to use the method. This code example is part of a larger example that is provided for the class. - + method is capable of parsing strings in various formats. The recognizable string formats are "---ddzzz" and "---dd", which are composed out of the following format patterns. + +|Format Pattern|Description|Examples| +|--------------------|-----------------|--------------| +|dd|The day of the month. Single-digit days have a leading zero.|23, 09| +|zzz|The full time zone offset (hour and minutes) from the Universal Time Coordinate (Greenwich Mean Time). Single-digit hours have a leading zero. "Z" means the current time zone.|-07:00, +08:00, Z| + + + +## Examples + The following code example shows how to use the method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapDay/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -230,14 +230,14 @@ Returns as a . A obtained from in the format "---dd". - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapDay/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -263,14 +263,14 @@ Gets or sets the date and time of the current instance. The object that contains the date and time of the current instance. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapDay/CPP/demo.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet14"::: + ]]> @@ -296,14 +296,14 @@ Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapDay/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDay/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration.xml index 7d3f40fa072..4d7e368c4ac 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration.xml @@ -25,19 +25,19 @@ Provides static methods for the serialization and deserialization of to a string that is formatted as XSD . - class to convert between a object and an XSD `duration` string. - + + + +## Examples + The following code example shows how to use the methods in the class to convert between a object and an XSD `duration` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapDuration/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -86,14 +86,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Converts the specified into a object. A object that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapDuration/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -131,14 +131,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Returns the specified object as a . A representation of in the format "PxxYxxDTxxHxxMxx.xxxS" or "PxxYxxDTxxHxxMxxS". The "PxxYxxDTxxHxxMxx.xxxS" is used if does not equal zero. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapDuration/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -164,14 +164,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapDuration/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapDuration/Overview/demo.cs" id="Snippet13"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary.xml index d882c577223..dfdd807ac98 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary.xml @@ -33,20 +33,20 @@ Wraps an XSD type. - class to convert between a object and an XSD `hexBinary` string. - + + + +## Examples + The following code example shows how to use the members in the class to convert between a object and an XSD `hexBinary` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapHexBinary/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -78,14 +78,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Initializes a new instance of the class. - @@ -111,14 +111,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht A array that contains a hexadecimal number. Initializes a new instance of the class. - @@ -148,14 +148,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Returns the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapHexBinary/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -185,14 +185,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Converts the specified into a object. A object that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapHexBinary/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -219,14 +219,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Returns as a . A that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapHexBinary/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -252,14 +252,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Gets or sets the hexadecimal representation of a number. A array containing the hexadecimal representation of a number. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapHexBinary/CPP/demo.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet14"::: + ]]> @@ -285,14 +285,14 @@ For more information about XSD data types, see the [XML Data Types Reference](ht Gets the XML Schema definition language (XSD) of the current SOAP type. A indicating the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapHexBinary/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapHexBinary/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger.xml index ccc8962f072..da969c5d60a 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger.xml @@ -33,19 +33,19 @@ Wraps an XSD type. - class to convert between a object and an XSD `integer` string. - + + + +## Examples + The following code example shows how to use the members in the class to convert between a object and an XSD `integer` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapInteger/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -77,14 +77,14 @@ Initializes a new instance of the class. - @@ -110,14 +110,14 @@ A value to initialize the current instance. Initializes a new instance of the class with a value. - @@ -147,14 +147,14 @@ Returns the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapInteger/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -184,14 +184,14 @@ Converts the specified into a object. A object that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapInteger/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -218,14 +218,14 @@ Returns as a . A that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapInteger/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -251,14 +251,14 @@ Gets or sets the numeric value of the current instance. A that indicates the numeric value of the current instance. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapInteger/CPP/demo.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet14"::: + ]]> @@ -284,14 +284,14 @@ Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapInteger/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapInteger/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth.xml index e34ac8cfddd..36e3dc6df81 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth.xml @@ -33,19 +33,19 @@ Wraps an XSD type. - class to convert between a object and an XSD `gMonth` string. - + + + +## Examples + The following code example shows how to use the members in the class to convert between a object and an XSD `gMonth` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonth/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -77,14 +77,14 @@ Initializes a new instance of the class. - @@ -110,14 +110,14 @@ A object to initialize the current instance. Initializes a new instance of the class with a specified object. - @@ -147,14 +147,14 @@ Returns the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonth/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -184,24 +184,24 @@ Converts the specified into a object. A object that is obtained from . - method is capable of parsing strings in various formats. The recognizable string formats are composed out of the following format patterns. - -|Format Pattern|Description|Examples| -|--------------------|-----------------|--------------| -|MM|The numeric month. Single-digit months have a leading zero.|11, 05| -|zzz|The full time zone offset (hour and minutes) from the Universal Time Coordinate (Greenwich Mean Time). Single-digit hours have a leading zero.|-07:00, 08:00| - - - -## Examples - The following code example shows how to use the method. This code example is part of a larger example that is provided for the class. - + method is capable of parsing strings in various formats. The recognizable string formats are composed out of the following format patterns. + +|Format Pattern|Description|Examples| +|--------------------|-----------------|--------------| +|MM|The numeric month. Single-digit months have a leading zero.|11, 05| +|zzz|The full time zone offset (hour and minutes) from the Universal Time Coordinate (Greenwich Mean Time). Single-digit hours have a leading zero.|-07:00, 08:00| + + + +## Examples + The following code example shows how to use the method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonth/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -230,14 +230,14 @@ Returns as a . A that is obtained from in the format "--MM--". - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonth/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -263,14 +263,14 @@ Gets or sets the date and time of the current instance. The object that contains the date and time of the current instance. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonth/CPP/demo.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet14"::: + ]]> @@ -296,14 +296,14 @@ Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonth/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonth/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay.xml index 63efc9d4df9..4353265f553 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay.xml @@ -33,19 +33,19 @@ Wraps an XSD type. - class to convert between a object and an XSD `gMonthDay` string. - + + + +## Examples + The following code example shows how to use the members in the class to convert between a object and an XSD `gMonthDay` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonthDay/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -77,14 +77,14 @@ Initializes a new instance of the class. - @@ -110,14 +110,14 @@ A object to initialize the current instance. Initializes a new instance of the class with a specified object. - @@ -147,14 +147,14 @@ Returns the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonthDay/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -184,25 +184,25 @@ Converts the specified into a object. A object that is obtained from . - method is capable of parsing strings in various formats. The recognizable string formats are composed out of the format patterns shown in the following table. - -|Format Pattern|Description|Examples| -|--------------------|-----------------|--------------| -|MM|The numeric month. Single-digit months have a leading zero.|11, 05| -|dd|The day of the month. Single-digit days have a leading zero.|23, 09| -|zzz|The full time zone offset (hour and minutes) from the Universal Time Coordinate (Greenwich Mean Time). Single-digit hours have a leading zero.|-07:00, 08:00| - - - -## Examples - The following code example shows how to use the method. This code example is part of a larger example that is provided for the class. - + method is capable of parsing strings in various formats. The recognizable string formats are composed out of the format patterns shown in the following table. + +|Format Pattern|Description|Examples| +|--------------------|-----------------|--------------| +|MM|The numeric month. Single-digit months have a leading zero.|11, 05| +|dd|The day of the month. Single-digit days have a leading zero.|23, 09| +|zzz|The full time zone offset (hour and minutes) from the Universal Time Coordinate (Greenwich Mean Time). Single-digit hours have a leading zero.|-07:00, 08:00| + + + +## Examples + The following code example shows how to use the method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonthDay/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -231,14 +231,14 @@ Returns as a . A that is obtained from in the format "'--'MM'-'dd". - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonthDay/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -264,14 +264,14 @@ Gets or sets the date and time of the current instance. The object that contains the date and time of the current instance. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonthDay/CPP/demo.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet14"::: + ]]> @@ -297,14 +297,14 @@ Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapMonthDay/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapMonthDay/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger.xml index 4c69ff5d94a..3fc17227acd 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger.xml @@ -33,19 +33,19 @@ Wraps an XSD type. - class to convert between a object and an XSD `negativeInteger` string. - + + + +## Examples + The following code example shows how to use the members in the class to convert between a object and an XSD `negativeInteger` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNegativeInteger/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -77,14 +77,14 @@ Initializes a new instance of the class. - @@ -110,14 +110,14 @@ A value to initialize the current instance. Initializes a new instance of the class with a value. - @@ -149,14 +149,14 @@ Returns the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNegativeInteger/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -186,14 +186,14 @@ Converts the specified into a object. A object that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNegativeInteger/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -220,14 +220,14 @@ Returns as a . A that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNegativeInteger/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -253,14 +253,14 @@ Gets or sets the numeric value of the current instance. A that indicates the numeric value of the current instance. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNegativeInteger/CPP/demo.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet14"::: + ]]> @@ -288,14 +288,14 @@ Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNegativeInteger/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNegativeInteger/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger.xml index b2bbbddb684..67ccaaf38b2 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger.xml @@ -33,19 +33,19 @@ Wraps an XSD type. - class to convert between a object and an XSD `nonNegativeInteger` string. - + + + +## Examples + The following code example shows how to use the members in the class to convert between a object and an XSD `nonNegativeInteger` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonNegativeInteger/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -77,14 +77,14 @@ Initializes a new instance of the class. - @@ -110,14 +110,14 @@ A value to initialize the current instance. Initializes a new instance of the class with a value. - @@ -149,14 +149,14 @@ Returns the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonNegativeInteger/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -186,14 +186,14 @@ Converts the specified into a object. A object that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonNegativeInteger/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -220,14 +220,14 @@ Returns as a . A that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonNegativeInteger/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -253,14 +253,14 @@ Gets or sets the numeric value of the current instance. A that indicates the numeric value of the current instance. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonNegativeInteger/CPP/demo.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet14"::: + ]]> @@ -288,14 +288,14 @@ Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonNegativeInteger/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonNegativeInteger/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger.xml index 5e821fee3ca..59935156678 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger.xml @@ -33,19 +33,19 @@ Wraps an XSD type. - class to convert between a object and an XSD `nonPositiveInteger` string. - + + + +## Examples + The following code example shows how to use the members in the class to convert between a object and an XSD `nonPositiveInteger` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonPositiveInteger/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -77,14 +77,14 @@ Initializes a new instance of the class. - @@ -110,14 +110,14 @@ A value to initialize the current instance. Initializes a new instance of the class with a value. - @@ -149,14 +149,14 @@ Returns the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonPositiveInteger/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -186,14 +186,14 @@ Converts the specified into a object. A object that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonPositiveInteger/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -220,14 +220,14 @@ Returns as a . A that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonPositiveInteger/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -253,14 +253,14 @@ Gets or sets the numeric value of the current instance. A that indicates the numeric value of the current instance. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonPositiveInteger/CPP/demo.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet14"::: + ]]> @@ -288,14 +288,14 @@ Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapNonPositiveInteger/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapNonPositiveInteger/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger.xml index 1bb928e3fe5..a9c706bb264 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger.xml @@ -33,19 +33,19 @@ Wraps an XSD type. - class to convert between a object and an XSD `positiveInteger` string. - + + + +## Examples + The following code example shows how to use the members in the class to convert between a object and an XSD `positiveInteger` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapPositiveInteger/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -77,14 +77,14 @@ Initializes a new instance of the class. - @@ -110,14 +110,14 @@ A value to initialize the current instance. Initializes a new instance of the class with a value. - @@ -149,14 +149,14 @@ Returns the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapPositiveInteger/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -186,14 +186,14 @@ Converts the specified into a object. A object that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapPositiveInteger/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -220,14 +220,14 @@ Returns as a . A that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapPositiveInteger/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -253,14 +253,14 @@ Gets or sets the numeric value of the current instance. A indicating the numeric value of the current instance. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapPositiveInteger/CPP/demo.cpp" id="Snippet14"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet14"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet14"::: + ]]> @@ -288,14 +288,14 @@ Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapPositiveInteger/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapPositiveInteger/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName.xml b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName.xml index 29e1fab1f33..5e5f0aa1a06 100644 --- a/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName.xml +++ b/xml/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName.xml @@ -33,19 +33,19 @@ Wraps an XSD type. - class to convert between a object and an XSD `QName` string. - + + + +## Examples + The following code example shows how to use the members in the class to convert between a object and an XSD `QName` string. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapQName/CPP/demo.cpp" id="Snippet10"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet10"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet10"::: + ]]> @@ -77,14 +77,14 @@ Initializes a new instance of the class. - @@ -110,14 +110,14 @@ A that contains the local part of a qualified name. Initializes a new instance of the class with the local part of a qualified name. - @@ -145,14 +145,14 @@ A that contains the local part of a qualified name. Initializes a new instance of the class with the namespace alias and the local part of a qualified name. - @@ -182,14 +182,14 @@ A that contains the namespace that is referenced by . Initializes a new instance of the class with the namespace alias, the local part of a qualified name, and the namespace that is referenced by the alias. - @@ -219,14 +219,14 @@ Returns the XML Schema definition language (XSD) of the current SOAP type. A indicating the XSD of the current SOAP type. - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapQName/CPP/demo.cpp" id="Snippet13"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet13"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet13"::: + ]]> @@ -252,14 +252,14 @@ Gets or sets the namespace alias of a qualified name. A that contains the namespace alias of a qualified name. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapQName/CPP/demo.cpp" id="Snippet17"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet17"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet17"::: + ]]> @@ -285,14 +285,14 @@ Gets or sets the name portion of a qualified name. A that contains the name portion of a qualified name. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapQName/CPP/demo.cpp" id="Snippet18"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet18"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet18"::: + ]]> @@ -318,14 +318,14 @@ Gets or sets the namespace that is referenced by . A that contains the namespace that is referenced by . - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapQName/CPP/demo.cpp" id="Snippet19"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet19"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet19"::: + ]]> @@ -355,14 +355,14 @@ Converts the specified into a object. A object that is obtained from . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapQName/CPP/demo.cpp" id="Snippet11"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet11"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet11"::: + ]]> @@ -389,14 +389,14 @@ Returns the qualified name as a . A in the format " : ". If is not specified, this method returns . - method. This code example is part of a larger example that is provided for the class. - + method. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapQName/CPP/demo.cpp" id="Snippet12"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet12"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet12"::: + ]]> @@ -422,14 +422,14 @@ Gets the XML Schema definition language (XSD) of the current SOAP type. A that indicates the XSD of the current SOAP type. - property. This code example is part of a larger example that is provided for the class. - + property. This code example is part of a larger example that is provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.W3cXsd2001.SoapQName/CPP/demo.cpp" id="Snippet16"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet16"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata.W3cXsd2001/SoapQName/Overview/demo.cs" id="Snippet16"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata/SoapAttribute.xml b/xml/System.Runtime.Remoting.Metadata/SoapAttribute.xml index 94299d7adc6..54cd08561cf 100644 --- a/xml/System.Runtime.Remoting.Metadata/SoapAttribute.xml +++ b/xml/System.Runtime.Remoting.Metadata/SoapAttribute.xml @@ -25,11 +25,11 @@ Provides default functionality for all SOAP attributes. - is nonfunctional, and can be used only as the base class for SOAP attributes. - + is nonfunctional, and can be used only as the base class for SOAP attributes. + ]]> @@ -97,11 +97,11 @@ The XML namespace to which the target of the current SOAP attribute is serialized. - field through the public property. - + field through the public property. + ]]> @@ -126,11 +126,11 @@ A reflection object used by attribute classes derived from the class to set XML serialization information. - field directly. - + field directly. + ]]> @@ -157,11 +157,11 @@ if the target object of the current attribute must be serialized as an XML attribute; if the target object must be serialized as a subelement. - 5`. If the property is set to `false`, `FieldA` will be serialized as ``. - + 5`. If the property is set to `false`, `FieldA` will be serialized as ``. + ]]> @@ -187,11 +187,11 @@ Gets or sets the XML namespace name. The XML namespace name under which the target of the current attribute is serialized. - diff --git a/xml/System.Runtime.Remoting.Metadata/SoapMethodAttribute.xml b/xml/System.Runtime.Remoting.Metadata/SoapMethodAttribute.xml index 14f6d81e3ef..6daec7e617a 100644 --- a/xml/System.Runtime.Remoting.Metadata/SoapMethodAttribute.xml +++ b/xml/System.Runtime.Remoting.Metadata/SoapMethodAttribute.xml @@ -29,19 +29,19 @@ Customizes SOAP generation and processing for a method. This class cannot be inherited. - attribute are methods that can be remotely invoked. Apply the to customize SOAP generation and processing. Properties of this attribute allow the programmer to customize the SOAPAction HTTP header field to indicate the intent of the SOAP HTTP request. - - - -## Examples - The following code example shows how to use the members in the class to customize SOAP generation and processing for a method. - + attribute are methods that can be remotely invoked. Apply the to customize SOAP generation and processing. Properties of this attribute allow the programmer to customize the SOAPAction HTTP header field to indicate the intent of the SOAP HTTP request. + + + +## Examples + The following code example shows how to use the members in the class to customize SOAP generation and processing for a method. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.SoapMethodAttribute/CPP/demo.cpp" id="Snippet100"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet100"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet100"::: + ]]> @@ -86,19 +86,19 @@ Gets or sets the XML element name to use for the method response to the target method. The XML element name to use for the method response to the target method. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.SoapMethodAttribute/CPP/demo.cpp" id="Snippet110"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet110"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet110"::: + ]]> @@ -124,14 +124,14 @@ Gets or sets the XML element namespace used for method response to the target method. The XML element namespace used for method response to the target method. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.SoapMethodAttribute/CPP/demo.cpp" id="Snippet110"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet110"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet110"::: + ]]> @@ -157,19 +157,19 @@ Gets or sets the XML element name used for the return value from the target method. The XML element name used for the return value from the target method. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.SoapMethodAttribute/CPP/demo.cpp" id="Snippet110"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet110"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet110"::: + ]]> @@ -201,21 +201,21 @@ Gets or sets the SOAPAction header field used with HTTP requests sent with this method. This property is currently not implemented. The SOAPAction header field used with HTTP requests sent with this method. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.SoapMethodAttribute/CPP/demo.cpp" id="Snippet110"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet110"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet110"::: + ]]> @@ -241,11 +241,11 @@ Gets or sets a value indicating whether the target of the current attribute will be serialized as an XML attribute instead of an XML field. The current implementation always returns . - property cannot be set on the attribute. - + property cannot be set on the attribute. + ]]> An attempt was made to set the current property. @@ -278,14 +278,14 @@ Gets or sets the XML namespace that is used during serialization of remote method calls of the target method. The XML namespace that is used during serialization of remote method calls of the target method. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.Metadata.SoapMethodAttribute/CPP/demo.cpp" id="Snippet110"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet110"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapMethodAttribute/Overview/demo.cs" id="Snippet110"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Metadata/SoapTypeAttribute.xml b/xml/System.Runtime.Remoting.Metadata/SoapTypeAttribute.xml index 965ba2f4006..b0aa39ce631 100644 --- a/xml/System.Runtime.Remoting.Metadata/SoapTypeAttribute.xml +++ b/xml/System.Runtime.Remoting.Metadata/SoapTypeAttribute.xml @@ -29,20 +29,20 @@ Customizes SOAP generation and processing for target types. This class cannot be inherited. - attribute is a custom attribute that can be applied to objects, value types, and interface objects. This attribute is used to specify information on an object type that controls how SOAP will generate the SOAP XML wire format. - - - -## Examples - The following code example demonstrates customization of SOAP generated for a class with the . The SOAP can be produced by the code shown in the class example. - + attribute is a custom attribute that can be applied to objects, value types, and interface objects. This attribute is used to specify information on an object type that controls how SOAP will generate the SOAP XML wire format. + + + +## Examples + The following code example demonstrates customization of SOAP generated for a class with the . The SOAP can be produced by the code shown in the class example. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/SoapAttributes1/CPP/s.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Metadata/SoapFieldAttribute/Overview/s.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Metadata/SoapFieldAttribute/Overview/s.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Metadata/SoapFieldAttribute/Overview/s.vb" id="Snippet1"::: + ]]> @@ -87,14 +87,14 @@ Gets or sets a configuration value. A configuration value. - value indicates the SOAP configuration options that will be used with a attribute. - + value indicates the SOAP configuration options that will be used with a attribute. + > [!NOTE] -> The enumeration has no effect on serialization of objects with the . - +> The enumeration has no effect on serialization of objects with the . + ]]> @@ -120,11 +120,11 @@ Gets or sets a value indicating whether the target of the current attribute will be serialized as an XML attribute instead of an XML field. The current implementation always returns . - property cannot be set on the attribute. - + property cannot be set on the attribute. + ]]> An attempt was made to set the current property. diff --git a/xml/System.Runtime.Remoting.Metadata/XmlFieldOrderOption.xml b/xml/System.Runtime.Remoting.Metadata/XmlFieldOrderOption.xml index de5ecc90bba..9c90de62832 100644 --- a/xml/System.Runtime.Remoting.Metadata/XmlFieldOrderOption.xml +++ b/xml/System.Runtime.Remoting.Metadata/XmlFieldOrderOption.xml @@ -28,11 +28,11 @@ You should not use this enumeration; it is not used by the .NET Framework remoting infrastructure. - property of the class gets or sets a value of type . However, the .NET Framework remoting infrastructure does not use the property's value. - + property of the class gets or sets a value of type . However, the .NET Framework remoting infrastructure does not use the property's value. + ]]> diff --git a/xml/System.Runtime.Remoting.Proxies/RealProxy.xml b/xml/System.Runtime.Remoting.Proxies/RealProxy.xml index 7afbd7114fd..f0118cbbeae 100644 --- a/xml/System.Runtime.Remoting.Proxies/RealProxy.xml +++ b/xml/System.Runtime.Remoting.Proxies/RealProxy.xml @@ -30,27 +30,27 @@ Provides base functionality for proxies. - class is the `abstract` base class from which proxies must derive. - - A client that uses an object across any kind of a remoting boundary is actually using a transparent proxy for the object. The transparent proxy provides the illusion that the actual object resides in the client's space. It achieves this by forwarding calls made on it to the real object using the remoting infrastructure. - - The transparent proxy is itself housed by an instance of a managed runtime class of type . The implements a part of the functionality that is needed to forward the operations from the transparent proxy. Note that a proxy object inherits the associated semantics of managed objects such as garbage collection, support for fields and methods, and can be extended to form new classes. The proxy has a dual nature: it acts as an object of the same class as the remote object (transparent proxy), and it is a managed object itself. - - A proxy object can be used without regard to any remoting subdivisions within a . - + class is the `abstract` base class from which proxies must derive. + + A client that uses an object across any kind of a remoting boundary is actually using a transparent proxy for the object. The transparent proxy provides the illusion that the actual object resides in the client's space. It achieves this by forwarding calls made on it to the real object using the remoting infrastructure. + + The transparent proxy is itself housed by an instance of a managed runtime class of type . The implements a part of the functionality that is needed to forward the operations from the transparent proxy. Note that a proxy object inherits the associated semantics of managed objects such as garbage collection, support for fields and methods, and can be extended to form new classes. The proxy has a dual nature: it acts as an object of the same class as the remote object (transparent proxy), and it is a managed object itself. + + A proxy object can be used without regard to any remoting subdivisions within a . + > [!NOTE] -> This class makes a link demand and an inheritance demand at the class level. A is thrown when either the immediate caller or the derived class does not have infrastructure permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands) and [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). - - - -## Examples +> This class makes a link demand and an inheritance demand at the class level. A is thrown when either the immediate caller or the derived class does not have infrastructure permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands) and [Inheritance Demands](https://learn.microsoft.com/previous-versions/dotnet/netframework-4.0/x4yx82e6(v=vs.100)). + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/ChannelServices_SyncDispatchMessage/CPP/channelservices_syncdispatchmessage_client.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Channels/ChannelServices/SyncDispatchMessage/channelservices_syncdispatchmessage_client.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Channels/ChannelServices/SyncDispatchMessage/channelservices_syncdispatchmessage_client.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Channels/ChannelServices/SyncDispatchMessage/channelservices_syncdispatchmessage_client.vb" id="Snippet1"::: + ]]> @@ -85,13 +85,13 @@ Initializes a new instance of the class with default values. - @@ -123,22 +123,22 @@ The of the remote object for which to create a proxy. Initializes a new instance of the class that represents a remote object of the specified . - method. - - A client that uses an object across any kind of a remoting boundary is actually using a transparent proxy for the object. The transparent proxy gives the impression that the actual object resides in the client's space. It achieves this by forwarding calls made on it to the real object using the remoting infrastructure. - - The transparent proxy is housed by an instance of a managed runtime class . The implements a part of the functionality that is needed to forward the operations from the transparent proxy. Note that a proxy object inherits the associated semantics of managed objects such as garbage collection and support for fields and methods, and can be extended to form new classes. The proxy has a dual nature: it acts as an object of the same class as the remote object (transparent proxy), and is a managed object itself. - - - -## Examples + method. + + A client that uses an object across any kind of a remoting boundary is actually using a transparent proxy for the object. The transparent proxy gives the impression that the actual object resides in the client's space. It achieves this by forwarding calls made on it to the real object using the remoting infrastructure. + + The transparent proxy is housed by an instance of a managed runtime class . The implements a part of the functionality that is needed to forward the operations from the transparent proxy. Note that a proxy object inherits the associated semantics of managed objects such as garbage collection and support for fields and methods, and can be extended to form new classes. The proxy has a dual nature: it acts as an object of the same class as the remote object (transparent proxy), and is a managed object itself. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/CustomProxy_Attribute_RealProxy/CPP/customproxy_sample.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Proxies/ProxyAttribute/Overview/customproxy_sample.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/ProxyAttribute/Overview/customproxy_sample.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/ProxyAttribute/Overview/customproxy_sample.vb" id="Snippet10"::: + ]]> @@ -176,11 +176,11 @@ The stub data to set for the specified stub and the new proxy instance. Initializes a new instance of the class. - @@ -251,13 +251,13 @@ Creates an for the specified object type, and registers it with the remoting infrastructure as a client-activated object. A new instance of that is created for the specified type. - @@ -326,20 +326,20 @@ Requests an unmanaged reference to the object represented by the current proxy instance. A pointer to a COM Callable Wrapper if the object reference is requested for communication with unmanaged objects in the current process through COM, or a pointer to a cached or newly generated COM interface if the object reference is requested for marshaling to a remote location. - method, then that instance is returned; otherwise, a new instance is returned. - - If the proxy is requested not for marshaling but for communication with unmanaged objects in the current process, then a [COM Callable Wrapper](/dotnet/framework/interop/com-callable-wrapper) (CCW), which can be used in the current process for communication through COM, is returned. - - - -## Examples + method, then that instance is returned; otherwise, a new instance is returned. + + If the proxy is requested not for marshaling but for communication with unmanaged objects in the current process, then a [COM Callable Wrapper](/dotnet/framework/interop/com-callable-wrapper) (CCW), which can be used in the current process for communication through COM, is returned. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/RealProxy_Sample/CPP/realproxy_sample.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Proxies/RealProxy/GetCOMIUnknown/realproxy_sample.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/RealProxy/GetCOMIUnknown/realproxy_sample.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/RealProxy/GetCOMIUnknown/realproxy_sample.vb" id="Snippet2"::: + ]]> @@ -376,13 +376,13 @@ The source and destination of the serialization. Adds the transparent proxy of the object represented by the current instance of to the specified . - The or parameter is . @@ -417,13 +417,13 @@ Returns the of the object that the current instance of represents. The of the object that the current instance of represents. - @@ -459,18 +459,18 @@ Retrieves stub data that is stored for the specified proxy. Stub data for the specified proxy. - The immediate caller does not have UnmanagedCode permission. @@ -498,13 +498,13 @@ Returns the transparent proxy for the current instance of . The transparent proxy for the current proxy instance. - @@ -537,11 +537,11 @@ Returns the server object that is represented by the current proxy instance. The server object that is represented by the current proxy instance. - method is used in scenarios involving an external in the same . - + method is used in scenarios involving an external in the same . + ]]> The immediate caller does not have UnmanagedCode permission. @@ -582,18 +582,18 @@ Initializes a new instance of the object of the remote object that the current instance of represents with the specified . The result of the construction request. - method calls the parameterless constructor for the new instance of the remote object that is represented by the current . - - - -## Examples + method calls the parameterless constructor for the new instance of the remote object that is represented by the current . + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/CustomProxy_Attribute_RealProxy/CPP/customproxy_sample.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Proxies/ProxyAttribute/Overview/customproxy_sample.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/ProxyAttribute/Overview/customproxy_sample.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/ProxyAttribute/Overview/customproxy_sample.vb" id="Snippet5"::: + ]]> The immediate caller does not have UnmanagedCode permission. @@ -624,20 +624,20 @@ When overridden in a derived class, invokes the method that is specified in the provided on the remote object that is represented by the current instance. The message returned by the invoked method, containing the return value and any or parameters. - is called, it delegates the calls to the method. The method transforms the message in the `msg` parameter into a , and sends it to the remote object that is represented by the current instance of . - - The parameter provides a dictionary through the property. The dictionary contains name/value pairs of information about the method call, such as the name of the method called and its parameters. - - - -## Examples + is called, it delegates the calls to the method. The method transforms the message in the `msg` parameter into a , and sends it to the remote object that is represented by the current instance of . + + The parameter provides a dictionary through the property. The dictionary contains name/value pairs of information about the method call, such as the name of the method called and its parameters. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/CustomProxy_Attribute_RealProxy/CPP/customproxy_sample.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Proxies/ProxyAttribute/Overview/customproxy_sample.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/ProxyAttribute/Overview/customproxy_sample.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/ProxyAttribute/Overview/customproxy_sample.vb" id="Snippet4"::: + ]]> @@ -666,20 +666,20 @@ A pointer to the interface for the object that is represented by the current proxy instance. Stores an unmanaged proxy of the object that is represented by the current instance. - , then it is serialized and copied to the current location. If it is derived from , then it returns a transparent proxy, and the remoting infrastructure caches the unmanaged proxy (the `IUnknown` interface) in the transparent proxy for future use. - - - -## Examples + , then it is serialized and copied to the current location. If it is derived from , then it returns a transparent proxy, and the remoting infrastructure caches the unmanaged proxy (the `IUnknown` interface) in the transparent proxy for future use. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/RealProxy_Sample/CPP/realproxy_sample.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Proxies/RealProxy/GetCOMIUnknown/realproxy_sample.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/RealProxy/GetCOMIUnknown/realproxy_sample.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/RealProxy/GetCOMIUnknown/realproxy_sample.vb" id="Snippet3"::: + ]]> @@ -716,18 +716,18 @@ The new stub data. Sets the stub data for the specified proxy. - The immediate caller does not have UnmanagedCode permission. @@ -758,20 +758,20 @@ Requests a COM interface with the specified ID. A pointer to the requested interface. - method allows the current proxy instance to implement additional COM interfaces on behalf of the server object that the current instance represents. The current method generates the requested interface and returns a pointer to it. The types of COM interfaces that can be generated by this method depend on the proxy type, which in turn might depend on the type of the server object that the current proxy instance represents. - - For more information, see . - - - -## Examples + method allows the current proxy instance to implement additional COM interfaces on behalf of the server object that the current instance represents. The current method generates the requested interface and returns a pointer to it. The types of COM interfaces that can be generated by this method depend on the proxy type, which in turn might depend on the type of the server object that the current proxy instance represents. + + For more information, see . + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/RealProxy_Sample/CPP/realproxy_sample.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting.Proxies/RealProxy/GetCOMIUnknown/realproxy_sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/RealProxy/GetCOMIUnknown/realproxy_sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Remoting.Proxies/RealProxy/GetCOMIUnknown/realproxy_sample.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.Remoting.Services/RemotingClientProxy.xml b/xml/System.Runtime.Remoting.Services/RemotingClientProxy.xml index 37a9b5f7553..643afeefa90 100644 --- a/xml/System.Runtime.Remoting.Services/RemotingClientProxy.xml +++ b/xml/System.Runtime.Remoting.Services/RemotingClientProxy.xml @@ -24,11 +24,11 @@ The abstract base class for proxies to well-known objects that were generated by the Soapsuds Tool (Soapsuds.exe). - provides access to the frequently used properties for Soapsuds-generated proxies that point to well-known objects (XML Web services). - + provides access to the frequently used properties for Soapsuds-generated proxies that point to well-known objects (XML Web services). + ]]> @@ -94,11 +94,11 @@ Indicates the type of the object that the current proxy represents. - class type of the object that the current proxy represents. - + class type of the object that the current proxy represents. + ]]> @@ -123,11 +123,11 @@ Indicates the URL of the object that the current proxy represents. - @@ -250,11 +250,11 @@ Gets or sets the domain name to be used for basic authentication and digest authentication. The name of the domain to use for basic authentication and digest authentication. - Security in network programming @@ -304,11 +304,11 @@ Gets or sets the password to use for basic authentication and digest authentication. The password to use for basic authentication and digest authentication. - Security in network programming @@ -427,11 +427,11 @@ Gets or sets the time-out in milliseconds to use for synchronous calls. The time-out in milliseconds to use for synchronous calls. - property is -1, and indicates that a time-out never occurs (infinite time-out). - + property is -1, and indicates that a time-out never occurs (infinite time-out). + ]]> @@ -503,11 +503,11 @@ Gets or sets the user name to send for basic authentication and digest authentication. The user name to send for basic authentication and digest authentication. - Security in network programming diff --git a/xml/System.Runtime.Remoting/ActivatedClientTypeEntry.xml b/xml/System.Runtime.Remoting/ActivatedClientTypeEntry.xml index 2082e959a2e..3d47d02d1a8 100644 --- a/xml/System.Runtime.Remoting/ActivatedClientTypeEntry.xml +++ b/xml/System.Runtime.Remoting/ActivatedClientTypeEntry.xml @@ -171,7 +171,7 @@ property. + The following code example shows how to use the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.ActivatedClientTypeEntry/CPP/activatedclienttypeentry_client.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/ActivatedClientTypeEntry/Overview/activatedclienttypeentry_client.cs" id="Snippet4"::: @@ -241,7 +241,7 @@ property. + The following code example shows how to use the property. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.ActivatedClientTypeEntry/CPP/activatedclienttypeentry_client.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/ActivatedClientTypeEntry/Overview/activatedclienttypeentry_client.cs" id="Snippet3"::: diff --git a/xml/System.Runtime.Remoting/IChannelInfo.xml b/xml/System.Runtime.Remoting/IChannelInfo.xml index 88996ce7b18..32045493bc5 100644 --- a/xml/System.Runtime.Remoting/IChannelInfo.xml +++ b/xml/System.Runtime.Remoting/IChannelInfo.xml @@ -22,13 +22,13 @@ Provides custom channel information that is carried along with the . - property. It provides access to transport specific information contributed by the channels that are able to receive calls in the process or application domain where the object lives. This interface might also be used when building custom classes. - - When an existing object instance is marshaled to produce a , the is copied from the channel (see ) for each registered channel and stored in the . When the is unmarshaled at its destination, the provided through the interface can be examined and used by corresponding channels in that process or application domain to create a transport message sink that manages the communication between the proxy and the server object. - + property. It provides access to transport specific information contributed by the channels that are able to receive calls in the process or application domain where the object lives. This interface might also be used when building custom classes. + + When an existing object instance is marshaled to produce a , the is copied from the channel (see ) for each registered channel and stored in the . When the is unmarshaled at its destination, the provided through the interface can be examined and used by corresponding channels in that process or application domain to create a transport message sink that manages the communication between the proxy and the server object. + ]]> diff --git a/xml/System.Runtime.Remoting/RemotingConfiguration.xml b/xml/System.Runtime.Remoting/RemotingConfiguration.xml index 284cb8ea616..1037d46d222 100644 --- a/xml/System.Runtime.Remoting/RemotingConfiguration.xml +++ b/xml/System.Runtime.Remoting/RemotingConfiguration.xml @@ -102,7 +102,7 @@ ## Examples - The following code example demonstrates the use of the property to indicate the name of the remoting application. For the full example code, see examples for the and methods. + The following code example demonstrates the use of the property to indicate the name of the remoting application. For the full example code, see examples for the and methods. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/RemotingConfiguration.ServerActivation1/CPP/server.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/RemotingConfiguration/ApplicationName/server.cs" id="Snippet2"::: diff --git a/xml/System.Runtime.Remoting/RemotingException.xml b/xml/System.Runtime.Remoting/RemotingException.xml index bc75766750d..93a7d0362f3 100644 --- a/xml/System.Runtime.Remoting/RemotingException.xml +++ b/xml/System.Runtime.Remoting/RemotingException.xml @@ -29,15 +29,15 @@ The exception that is thrown when something has gone wrong during remoting. - uses the HRESULT COR_E_REMOTING, which has the value 0x8013150B. - - uses the default implementation, which supports reference equality. - - For a list of initial property values for an instance of , see the constructors. - + uses the HRESULT COR_E_REMOTING, which has the value 0x8013150B. + + uses the default implementation, which supports reference equality. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -71,16 +71,16 @@ Initializes a new instance of the class with default properties. - inherits from the class. The following table shows initial property values for an instance of the class: - -|Property|Value| -|--------------|-----------| -||`null`| -||The empty string ("")| - + inherits from the class. The following table shows initial property values for an instance of the class: + +|Property|Value| +|--------------|-----------| +||`null`| +||The empty string ("")| + ]]> @@ -107,16 +107,16 @@ The error message that explains why the exception occurred. Initializes a new instance of the class with a specified message. - inherits from the class. The following table shows initial property values for an instance of the class: - -|Property Type|Condition| -|-------------------|---------------| -||`null`| -||The `message` string| - + inherits from the class. The following table shows initial property values for an instance of the class: + +|Property Type|Condition| +|-------------------|---------------| +||`null`| +||The `message` string| + ]]> @@ -151,11 +151,11 @@ The contextual information about the source or destination of the exception. Initializes a new instance of the class from serialized data. - The parameter is . @@ -184,18 +184,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 initial property values for an instance of the class: - -|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 initial property values for an instance of the class: + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| + ]]> diff --git a/xml/System.Runtime.Remoting/RemotingServices.xml b/xml/System.Runtime.Remoting/RemotingServices.xml index 5bbc117451b..81f351e665f 100644 --- a/xml/System.Runtime.Remoting/RemotingServices.xml +++ b/xml/System.Runtime.Remoting/RemotingServices.xml @@ -396,7 +396,7 @@ , , and properties of and is used by classes implementing the interface. Consumers of classes should reference the property. + This determines the method base from the , , and properties of and is used by classes implementing the interface. Consumers of classes should reference the property. ]]> diff --git a/xml/System.Runtime.Remoting/RemotingTimeoutException.xml b/xml/System.Runtime.Remoting/RemotingTimeoutException.xml index 366bc87223c..604c1991e6a 100644 --- a/xml/System.Runtime.Remoting/RemotingTimeoutException.xml +++ b/xml/System.Runtime.Remoting/RemotingTimeoutException.xml @@ -29,17 +29,17 @@ The exception that is thrown when the server or the client cannot be reached for a previously specified period of time. - is thrown when a remoting call does not complete in the specified timeout time. - - uses the HRESULT COR_E_REMOTING, which has the value 0x8013150B. - - uses the default implementation, which supports reference equality. - - For a list of initial property values for an instance of , see the constructors. - + is thrown when a remoting call does not complete in the specified timeout time. + + uses the HRESULT COR_E_REMOTING, which has the value 0x8013150B. + + uses the default implementation, which supports reference equality. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -73,16 +73,16 @@ Initializes a new instance of the class with default properties. - inherits from the class. The following table shows initial property values for an instance of the class: - -|Property|Value| -|--------------|-----------| -||`null`| -||Localized error message for | - + inherits from the class. The following table shows initial property values for an instance of the class: + +|Property|Value| +|--------------|-----------| +||`null`| +||Localized error message for | + ]]> @@ -108,16 +108,16 @@ The message that indicates the reason why the exception occurred. Initializes a new instance of class with a specified message. - inherits from the class. The following table shows initial property values for an instance of the class: - -|Property Type|Condition| -|-------------------|---------------| -||`null`| -||The `message` string| - + inherits from the class. The following table shows initial property values for an instance of the class: + +|Property Type|Condition| +|-------------------|---------------| +||`null`| +||The `message` string| + ]]> @@ -145,18 +145,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 initial property values for an instance of the class: - -|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 initial property values for an instance of the class: + +|Property|Value| +|--------------|-----------| +||The inner exception reference| +||The error message string| + ]]> diff --git a/xml/System.Runtime.Remoting/ServerException.xml b/xml/System.Runtime.Remoting/ServerException.xml index b0db4396ded..e3f8d91726a 100644 --- a/xml/System.Runtime.Remoting/ServerException.xml +++ b/xml/System.Runtime.Remoting/ServerException.xml @@ -29,15 +29,15 @@ The exception that is thrown to communicate errors to the client when the client connects to non-.NET Framework applications that cannot throw exceptions. - uses the HRESULT COR_E_SERVER, which has the value 0x8013150E. - - uses the default implementation, which supports reference equality. - - For a list of initial property values for an instance of , see the constructors. - + uses the HRESULT COR_E_SERVER, which has the value 0x8013150E. + + uses the default implementation, which supports reference equality. + + For a list of initial property values for an instance of , see the constructors. + ]]> @@ -71,16 +71,16 @@ Initializes a new instance of the class with default properties. - inherits from the class. The following table shows initial property values for an instance of the class: - -|Property|Value| -|--------------|-----------| -||`null`| -||The empty string ("")| - + inherits from the class. The following table shows initial property values for an instance of the class: + +|Property|Value| +|--------------|-----------| +||`null`| +||The empty string ("")| + ]]> @@ -107,16 +107,16 @@ The message that describes the exception. Initializes a new instance of the class with a specified message. - inherits from the class. The following table shows initial property values for an instance of the class: - -|Property Type|Condition| -|-------------------|---------------| -||`null`| -||The `message` string| - + inherits from the class. The following table shows initial property values for an instance of the class: + +|Property Type|Condition| +|-------------------|---------------| +||`null`| +||The `message` string| + ]]> @@ -145,18 +145,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 initial property values for an instance of the class: - -|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 initial property values for an instance of the class: + +|Property|Value| +|--------------|-----------| +||The inner exception reference| +||The error message string| + ]]> diff --git a/xml/System.Runtime.Remoting/SoapServices.xml b/xml/System.Runtime.Remoting/SoapServices.xml index 64ebde75791..df30dfeb19c 100644 --- a/xml/System.Runtime.Remoting/SoapServices.xml +++ b/xml/System.Runtime.Remoting/SoapServices.xml @@ -29,19 +29,19 @@ Provides several methods for using and publishing remoted objects in SOAP format. - class to convert between a object and an XML type. - + class to convert between a object and an XML type. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet100"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet100"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet100"::: + ]]> @@ -79,21 +79,21 @@ Returns the common language runtime type namespace name from the provided namespace and assembly names. The common language runtime type namespace name from the provided namespace and assembly names. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet101"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet101"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet101"::: + ]]> The and parameters are both either or empty. @@ -136,19 +136,19 @@ if the namespace and assembly names were successfully decoded; otherwise, . - namespace. There are two ways to specify this information in a configuration file: either by explicitly specifying the mappings, or by specifying which object types to preload. The current method supports the retrieval of such mappings. - - - -## Examples - The following code example shows how to use this method. This code example is part of a larger example provided for the class. - + namespace. There are two ways to specify this information in a configuration file: either by explicitly specifying the mappings, or by specifying which object types to preload. The current method supports the retrieval of such mappings. + + + +## Examples + The following code example shows how to use this method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet102"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet102"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet102"::: + ]]> The parameter is or empty. @@ -187,19 +187,19 @@ When this method returns, contains a that holds the name of the field. This parameter is passed uninitialized. Retrieves field type from XML attribute name, namespace, and the of the containing object. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet150"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet150"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet150"::: + ]]> The immediate caller does not have infrastructure permission. @@ -237,19 +237,19 @@ When this method returns, contains a that holds the name of the field. This parameter is passed uninitialized. Retrieves the and name of a field from the provided XML element name, namespace, and the containing type. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet150"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet150"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet150"::: + ]]> The immediate caller does not have infrastructure permission. @@ -288,19 +288,19 @@ Retrieves the that should be used during deserialization of an unrecognized object type with the given XML element name and namespace. The of object associated with the specified XML element name and namespace. - and . - - - -## Examples - The following code example shows how to use this method. This code example is part of a larger example provided for the class. - + and . + + + +## Examples + The following code example shows how to use this method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet160"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet160"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet160"::: + ]]> The immediate caller does not have infrastructure permission. @@ -339,19 +339,19 @@ Retrieves the object that should be used during deserialization of an unrecognized object type with the given XML type name and namespace. The of object associated with the specified XML type name and namespace. - and . - - - -## Examples - The following code example shows how to use this method. This code example is part of a larger example provided for the class. - + and . + + + +## Examples + The following code example shows how to use this method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet160"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet160"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet160"::: + ]]> The immediate caller does not have infrastructure permission. @@ -388,19 +388,19 @@ Returns the SOAPAction value associated with the method specified in the given . The SOAPAction value associated with the method specified in the given . - has not been registered with any SOAPAction value, the method returns the SOAPAction automatically cached with the . - - - -## Examples - The following code example shows how to use this method. This code example is part of a larger example provided for the class. - + has not been registered with any SOAPAction value, the method returns the SOAPAction automatically cached with the . + + + +## Examples + The following code example shows how to use this method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet140"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet140"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet140"::: + ]]> The immediate caller does not have infrastructure permission. @@ -436,19 +436,19 @@ if the type and method name were successfully recovered; otherwise, . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet140"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet140"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet140"::: + ]]> The SOAPAction value does not start and end with quotes. @@ -491,14 +491,14 @@ if the requested values have been set flagged with ; otherwise, . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet103"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet103"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet103"::: + ]]> The immediate caller does not have infrastructure permission. @@ -536,14 +536,14 @@ Retrieves the XML namespace used during remote calls of the method specified in the given . The XML namespace used during remote calls of the specified method. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet105"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet105"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet105"::: + ]]> The immediate caller does not have infrastructure permission. @@ -580,14 +580,14 @@ Retrieves the XML namespace used during the generation of responses to the remote call to the method specified in the given . The XML namespace used during the generation of responses to a remote method call. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet105"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet105"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet105"::: + ]]> The immediate caller does not have infrastructure permission. @@ -629,14 +629,14 @@ if the requested values have been set flagged with ; otherwise, . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet104"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet104"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet104"::: + ]]> The immediate caller does not have infrastructure permission. @@ -669,21 +669,21 @@ if the given namespace is native to the common language runtime; otherwise, . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet106"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet106"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet106"::: + ]]> The immediate caller does not have infrastructure permission. @@ -723,14 +723,14 @@ if the specified SOAPAction is acceptable for a given ; otherwise, . - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet140"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet140"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet140"::: + ]]> The immediate caller does not have infrastructure permission. @@ -776,19 +776,19 @@ The for each type of which to call . Preloads every found in the specified from the information found in the associated with each type. - namespace. There are two ways to specify this information in a configuration file: either by explicitly specifying the mappings, or by specifying which object types to preload. The custom attributes are read during the preloading process and the information in them is made available to the SOAP parser. - - - -## Examples - The following code example shows how to use this method. This code example is part of a larger example provided for the class. - + namespace. There are two ways to specify this information in a configuration file: either by explicitly specifying the mappings, or by specifying which object types to preload. The custom attributes are read during the preloading process and the information in them is made available to the SOAP parser. + + + +## Examples + The following code example shows how to use this method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet120"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet120"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet120"::: + ]]> The immediate caller does not have infrastructure permission. @@ -824,19 +824,19 @@ The to preload. Preloads the given based on values set in a on the type. - namespace. There are two ways to specify this information in a configuration file: either by explicitly specifying the mappings, or by specifying which object types to preload. The custom attributes are read during the preloading process and the information in them is made available to the SOAP parser. - - - -## Examples - The following code example shows how to use this method. This code example is part of a larger example provided for the class. - + namespace. There are two ways to specify this information in a configuration file: either by explicitly specifying the mappings, or by specifying which object types to preload. The custom attributes are read during the preloading process and the information in them is made available to the SOAP parser. + + + +## Examples + The following code example shows how to use this method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet121"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet121"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet121"::: + ]]> The immediate caller does not have infrastructure permission. @@ -876,14 +876,14 @@ The run-time to use in deserialization. Associates the given XML element name and namespace with a run-time type that should be used for deserialization. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet180"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet180"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet180"::: + ]]> The immediate caller does not have infrastructure permission. @@ -924,14 +924,14 @@ The run-time to use in deserialization. Associates the given XML type name and namespace with the run-time type that should be used for deserialization. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet190"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet190"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet190"::: + ]]> The immediate caller does not have infrastructure permission. @@ -977,21 +977,21 @@ The of the method to associate with the SOAPAction cached with it. Associates the specified with the SOAPAction cached with it. - property, or is read off the wire. The current method associates the SOAPAction with the for use in channel sinks. - - The SOAPAction HTTP request header field indicates the intent of the SOAP HTTP request. The value is a URI identifying the intent. SOAP places no restrictions on the format or specificity of the URI or that it is resolvable. An HTTP client must use this header field when issuing a SOAP HTTP request. - - - -## Examples - The following code example shows how to use this method. This code example is part of a larger example provided for the class. - + property, or is read off the wire. The current method associates the SOAPAction with the for use in channel sinks. + + The SOAPAction HTTP request header field indicates the intent of the SOAP HTTP request. The value is a URI identifying the intent. SOAP places no restrictions on the format or specificity of the URI or that it is resolvable. An HTTP client must use this header field when issuing a SOAP HTTP request. + + + +## Examples + The following code example shows how to use this method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet170"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet170"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet170"::: + ]]> The immediate caller does not have infrastructure permission. @@ -1023,19 +1023,19 @@ The SOAPAction value to associate with the given . Associates the provided SOAPAction value with the given for use in channel sinks. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet170"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet170"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet170"::: + ]]> The immediate caller does not have infrastructure permission. @@ -1062,19 +1062,19 @@ Gets the XML namespace prefix for common language runtime types. The XML namespace prefix for common language runtime types. - that the current property returns. - - - -## Examples - The following code example shows how to use this property. This code example is part of a larger example provided for the class. - + that the current property returns. + + + +## Examples + The following code example shows how to use this property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet130"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet130"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet130"::: + ]]> The immediate caller does not have infrastructure permission. @@ -1101,19 +1101,19 @@ Gets the default XML namespace prefix that should be used for XML encoding of a common language runtime class that has an assembly, but no native namespace. The default XML namespace prefix that should be used for XML encoding of a common language runtime class that has an assembly, but no native namespace. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet131"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet131"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet131"::: + ]]> The immediate caller does not have infrastructure permission. @@ -1140,19 +1140,19 @@ Gets the XML namespace prefix that should be used for XML encoding of a common language runtime class that is part of the mscorlib.dll file. The XML namespace prefix that should be used for XML encoding of a common language runtime class that is part of the mscorlib.dll file. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet132"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet132"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet132"::: + ]]> The immediate caller does not have infrastructure permission. @@ -1179,19 +1179,19 @@ Gets the default XML namespace prefix that should be used for XML encoding of a common language runtime class that has both a common language runtime namespace and an assembly. The default XML namespace prefix that should be used for XML encoding of a common language runtime class that has both a common language runtime namespace and an assembly. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Runtime.Remoting.SoapServices/CPP/demo.cpp" id="Snippet133"::: - :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet133"::: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Remoting/SoapServices/Overview/demo.cs" id="Snippet133"::: + ]]> The immediate caller does not have infrastructure permission. diff --git a/xml/System.Runtime.Serialization.Formatters/ISoapMessage.xml b/xml/System.Runtime.Serialization.Formatters/ISoapMessage.xml index f53b53f0c4c..e4c24008ad2 100644 --- a/xml/System.Runtime.Serialization.Formatters/ISoapMessage.xml +++ b/xml/System.Runtime.Serialization.Formatters/ISoapMessage.xml @@ -22,13 +22,13 @@ Provides an interface for an object that contains the names and types of parameters required during serialization of a SOAP RPC (Remote Procedure Call). - interface contains the method call parameter types used during deserialization of a method call. - - To support SOAP RPC calls that are based on the interface and do not use the functionality, set the property to an object that supports this interface. - + interface contains the method call parameter types used during deserialization of a method call. + + To support SOAP RPC calls that are based on the interface and do not use the functionality, set the property to an object that supports this interface. + ]]> diff --git a/xml/System.Runtime.Serialization.Formatters/SoapFault.xml b/xml/System.Runtime.Serialization.Formatters/SoapFault.xml index b9d4885b1a9..eb9c9171656 100644 --- a/xml/System.Runtime.Serialization.Formatters/SoapFault.xml +++ b/xml/System.Runtime.Serialization.Formatters/SoapFault.xml @@ -118,11 +118,11 @@ Gets or sets additional information required for the . Additional information required for the . - @@ -148,11 +148,11 @@ Gets or sets the fault actor for the . The fault actor for the . - property provides information about the cause of the fault within the message path. - + property provides information about the cause of the fault within the message path. + ]]> @@ -178,11 +178,11 @@ Gets or sets the fault code for the . The fault code for this . - @@ -208,11 +208,11 @@ Gets or sets the fault message for the . The fault message for the . - diff --git a/xml/System.Runtime.Serialization.Formatters/SoapMessage.xml b/xml/System.Runtime.Serialization.Formatters/SoapMessage.xml index 35328e9609b..98f0dc357f1 100644 --- a/xml/System.Runtime.Serialization.Formatters/SoapMessage.xml +++ b/xml/System.Runtime.Serialization.Formatters/SoapMessage.xml @@ -33,11 +33,11 @@ Holds the names and types of parameters required during serialization of a SOAP RPC (Remote Procedure Call). - is the root of a serialization graph, SOAP is produced in RPC (Remote Procedure Call) format and a object is used to specify the method call parameter types. The property can be set to this object during deserialization. - + is the root of a serialization graph, SOAP is produced in RPC (Remote Procedure Call) format and a object is used to specify the method call parameter types. The property can be set to this object during deserialization. + ]]> diff --git a/xml/System.Runtime.Serialization.Json/DataContractJsonSerializer.xml b/xml/System.Runtime.Serialization.Json/DataContractJsonSerializer.xml index eb94f75afe0..75061ece293 100644 --- a/xml/System.Runtime.Serialization.Json/DataContractJsonSerializer.xml +++ b/xml/System.Runtime.Serialization.Json/DataContractJsonSerializer.xml @@ -896,7 +896,7 @@ property affects types to which a attribute has been applied and that also implement the interface. In this case when is `true`, data added in future versions 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). + The property affects types to which a attribute has been applied and that also implement the interface. In this case when is `true`, data added in future versions 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). ]]> @@ -1136,7 +1136,7 @@ ## Remarks This property can be set using a constructor. For a list, see . - The property specifies the maximum number of objects that the serializer serializes or deserializes in a single or 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. 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, 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 property specifies the maximum number of objects that the serializer serializes or deserializes in a single or 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. 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, 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. ]]> diff --git a/xml/System.Runtime.Serialization/CollectionDataContractAttribute.xml b/xml/System.Runtime.Serialization/CollectionDataContractAttribute.xml index 475c30d5097..d5af14ad151 100644 --- a/xml/System.Runtime.Serialization/CollectionDataContractAttribute.xml +++ b/xml/System.Runtime.Serialization/CollectionDataContractAttribute.xml @@ -58,28 +58,28 @@ When applied to a collection type, enables custom specification of the collection item elements. This attribute can be applied only to types that are recognized by the as valid, serializable collections. - is intended to ease interoperability when working with data from non-WCF providers and to control the exact shape of serialized instances. To this end, the property enables you to control the names of the repeating items inside a collection. This is especially useful when the provider does not use the XML element type name as the array item name, for example, if a provider uses "String" as an element type name instead of the XSD type name "string". - - The is also intended to be used with dictionary types to handle keyed collections. Dictionary types are classes that implement either the or the interface, for example, the . Use the and properties to set custom names when using the class. - - For more information about using the , see [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). - - - -## Examples - The following example applies the to a class that inherits from the class. The code sets the and properties to custom values. - + is intended to ease interoperability when working with data from non-WCF providers and to control the exact shape of serialized instances. To this end, the property enables you to control the names of the repeating items inside a collection. This is especially useful when the provider does not use the XML element type name as the array item name, for example, if a provider uses "String" as an element type name instead of the XSD type name "string". + + The is also intended to be used with dictionary types to handle keyed collections. Dictionary types are classes that implement either the or the interface, for example, the . Use the and properties to set custom names when using the class. + + For more information about using the , see [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). + + + +## Examples + The following example applies the to a class that inherits from the class. The code sets the and properties to custom values. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/collectiondatacontractattribute/cs/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/collectiondatacontractattribute/vb/source.vb" id="Snippet1"::: - - When the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe) is used to generate code for the client, the code resembles the following example. Notice that the name of the class is changed, as well as the . When using generics, the type parameter name is used to create the resulting type name. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/collectiondatacontractattribute/vb/source.vb" id="Snippet1"::: + + When the [ServiceModel Metadata Utility Tool (Svcutil.exe)](/dotnet/framework/wcf/servicemodel-metadata-utility-tool-svcutil-exe) is used to generate code for the client, the code resembles the following example. Notice that the name of the class is changed, as well as the . When using generics, the type parameter name is used to create the resulting type name. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/collectiondatacontractattribute/cs/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/collectiondatacontractattribute/vb/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/collectiondatacontractattribute/vb/source.vb" id="Snippet2"::: + ]]> @@ -338,11 +338,11 @@ to keep object reference data; otherwise, . The default is . - diff --git a/xml/System.Runtime.Serialization/ContractNamespaceAttribute.xml b/xml/System.Runtime.Serialization/ContractNamespaceAttribute.xml index f6bd4ad4b18..6745c1e0c47 100644 --- a/xml/System.Runtime.Serialization/ContractNamespaceAttribute.xml +++ b/xml/System.Runtime.Serialization/ContractNamespaceAttribute.xml @@ -58,24 +58,24 @@ Specifies the CLR namespace and XML namespace of the data contract. - attribute to an assembly that contains types to which the has been applied. The enables you to set a namespace that is different than the one generated when the type is serialized. For more information about how names are generated, see [Data Contract Names](/dotnet/framework/wcf/feature-details/data-contract-names). - - If you are using a type to conform to an existing data contract, you must match the namespace of the existing contract by using the (or the property of the class). - + attribute to an assembly that contains types to which the has been applied. The enables you to set a namespace that is different than the one generated when the type is serialized. For more information about how names are generated, see [Data Contract Names](/dotnet/framework/wcf/feature-details/data-contract-names). + + If you are using a type to conform to an existing data contract, you must match the namespace of the existing contract by using the (or the property of the class). + > [!NOTE] -> In any code, you can use the word `ContractNamespace` instead of the longer . - - - -## Examples - The following example shows the applied to an assembly. - +> In any code, you can use the word `ContractNamespace` instead of the longer . + + + +## Examples + The following example shows the applied to an assembly. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/contractnamespaceattribute/cs/overview.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/contractnamespaceattribute/vb/overview.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/contractnamespaceattribute/vb/overview.vb" id="Snippet1"::: + ]]> Using Data Contracts @@ -216,11 +216,11 @@ Gets the namespace of the data contract members. The namespace of the data contract members. - diff --git a/xml/System.Runtime.Serialization/DataContractAttribute.xml b/xml/System.Runtime.Serialization/DataContractAttribute.xml index 4142ea7bedd..22045702da8 100644 --- a/xml/System.Runtime.Serialization/DataContractAttribute.xml +++ b/xml/System.Runtime.Serialization/DataContractAttribute.xml @@ -340,11 +340,11 @@ The following example serializes and deserializes a class named `Person` to whic 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). + The 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. + 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. ]]> @@ -398,7 +398,7 @@ The following example serializes and deserializes a class named `Person` to whic Use this property to specify a particular namespace if your type must return data that complies with a specific data 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 cf8ab150023..e681953e3c9 100644 --- a/xml/System.Runtime.Serialization/DataContractSerializer.xml +++ b/xml/System.Runtime.Serialization/DataContractSerializer.xml @@ -952,7 +952,7 @@ 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). + The 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). ]]> @@ -1037,7 +1037,7 @@ ## Examples - The following example uses the property to determine whether the start of the data has been found. + 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"::: @@ -1148,7 +1148,7 @@ 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. + The 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. ]]> @@ -1216,7 +1216,7 @@ OperationDescription operation = host.Description.Endpoints[0].Contract.Operatio 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 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. ]]> diff --git a/xml/System.Runtime.Serialization/DataMemberAttribute.xml b/xml/System.Runtime.Serialization/DataMemberAttribute.xml index 60b35716b93..2fbd3090584 100644 --- a/xml/System.Runtime.Serialization/DataMemberAttribute.xml +++ b/xml/System.Runtime.Serialization/DataMemberAttribute.xml @@ -58,29 +58,29 @@ When applied to the member of a type, specifies that the member is part of a data contract and is serializable by the . - attribute in conjunction with the to identify members of a type that are part of a data contract. One of the serializers that can serialize data contracts is the . - - The data contract model is an "opt-in" model. Applying the to a field or property explicitly specifies that the member value will be serialized. In contrast, the serializes all public fields and properties of a type. - + attribute in conjunction with the to identify members of a type that are part of a data contract. One of the serializers that can serialize data contracts is the . + + The data contract model is an "opt-in" model. Applying the to a field or property explicitly specifies that the member value will be serialized. In contrast, the serializes all public fields and properties of a type. + > [!CAUTION] -> You can apply the to private fields or properties. Be aware that the data returned by the member (even if it's private) will be serialized and deserialized, and thus can be viewed or intercepted by a malicious user or process. - - By default, the CLR member name is used as the name of the data member. By setting the property, you can customize the name of the data member. This can be used to provide a name that may not be allowed as a CLR member name. When mapping to XML using the , this name is used as the name of the schema element in a type. - +> You can apply the to private fields or properties. Be aware that the data returned by the member (even if it's private) will be serialized and deserialized, and thus can be viewed or intercepted by a malicious user or process. + + By default, the CLR member name is used as the name of the data member. By setting the property, you can customize the name of the data member. This can be used to provide a name that may not be allowed as a CLR member name. When mapping to XML using the , this name is used as the name of the schema element in a type. + > [!NOTE] -> Properties to which the attribute has been applied must have both `get` and `set` fields. They cannot be `get`-only or `set`-only. To serialize a property that should remain `get`-only by design (for example, a property that returns a collection), consider applying the to the backing field instead. - - For more information about data contracts and data members, see [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). For more information about member names, see [Data Member Default Values](/dotnet/framework/wcf/feature-details/data-member-default-values). - -## Examples - The following example shows a type to which the and attributes have been applied. The property on the is set to "ID". - +> Properties to which the attribute has been applied must have both `get` and `set` fields. They cannot be `get`-only or `set`-only. To serialize a property that should remain `get`-only by design (for example, a property that returns a collection), consider applying the to the backing field instead. + + For more information about data contracts and data members, see [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). For more information about member names, see [Data Member Default Values](/dotnet/framework/wcf/feature-details/data-member-default-values). + +## Examples + The following example shows a type to which the and attributes have been applied. The property on the is set to "ID". + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datamemberattribute/cs/overview.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datamemberattribute/vb/overview.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datamemberattribute/vb/overview.vb" id="Snippet0"::: + ]]> @@ -173,22 +173,22 @@ if the default value for a member should be generated in the serialization stream; otherwise, . The default is . - property to `false` (it is `true` by default). - + property to `false` (it is `true` by default). + > [!NOTE] -> Setting the property to `false` is not a recommended practice. It should only be done if there is a specific need to do so (such as for interoperability or to reduce data size). - - - -## Examples - The following example shows the property set to `false` on various fields. - +> Setting the property to `false` is not a recommended practice. It should only be done if there is a specific need to do so (such as for interoperability or to reduce data size). + + + +## Examples + The following example shows the property set to `false` on various fields. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/datamemberattribute/cs/overview.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datamemberattribute/vb/overview.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/datamemberattribute/vb/overview.vb" id="Snippet3"::: + ]]> @@ -278,11 +278,11 @@ , if the member is required; otherwise, . - the member is not present. @@ -332,13 +332,13 @@ Gets or sets a data member name. The name of the data member. The default is the name of the target that the attribute is applied to. - . - - The property enables you to use names that are not permitted as common language runtime (CLR) identifiers. In addition, this property enables the type author to define a data member name separate from the CLR member name. This separate definition helps in versioning scenarios (changing the CLR member name without breaking the data contract) and allows a different naming convention for data contact members and CLR members. - + . + + The property enables you to use names that are not permitted as common language runtime (CLR) identifiers. In addition, this property enables the type author to define a data member name separate from the CLR member name. This separate definition helps in versioning scenarios (changing the CLR member name without breaking the data contract) and allows a different naming convention for data contact members and CLR members. + ]]> Using Data Contracts @@ -387,11 +387,11 @@ Gets or sets the order of serialization and deserialization of a member. The numeric order of serialization or deserialization. - Data Member Order diff --git a/xml/System.Runtime.Serialization/ExportOptions.xml b/xml/System.Runtime.Serialization/ExportOptions.xml index 52f0e5553ee..3041cb558b4 100644 --- a/xml/System.Runtime.Serialization/ExportOptions.xml +++ b/xml/System.Runtime.Serialization/ExportOptions.xml @@ -51,27 +51,27 @@ Represents the options that can be set for an . - is used to generate XSD schemas from a type or assembly. You can also use the to generate .NET Framework code from a schema document. - - For more information about importing and exporting schemas, see [Schema Import and Export](/dotnet/framework/wcf/feature-details/schema-import-and-export) and [Exporting Schemas from Classes](/dotnet/framework/wcf/feature-details/exporting-schemas-from-classes). - - The property is used by the to include types that can be read in an object graph. For more information about the data contract and known types, see [Data Contract Known Types](/dotnet/framework/wcf/feature-details/data-contract-known-types). - - For more information about data contracts, see [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). - - - -## Examples - The following example creates an instance of the class and adds a type (`Possessions`) to the collection returned by the property. - - The then exports the schemas of the types, including the `Possessions` type added to the collection. - + is used to generate XSD schemas from a type or assembly. You can also use the to generate .NET Framework code from a schema document. + + For more information about importing and exporting schemas, see [Schema Import and Export](/dotnet/framework/wcf/feature-details/schema-import-and-export) and [Exporting Schemas from Classes](/dotnet/framework/wcf/feature-details/exporting-schemas-from-classes). + + The property is used by the to include types that can be read in an object graph. For more information about the data contract and known types, see [Data Contract Known Types](/dotnet/framework/wcf/feature-details/data-contract-known-types). + + For more information about data contracts, see [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). + + + +## Examples + The following example creates an instance of the class and adds a type (`Possessions`) to the collection returned by the property. + + The then exports the schemas of the types, including the `Possessions` type added to the collection. + :::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"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/xsddatacontractexporter/vb/overview.vb" id="Snippet0"::: + ]]> @@ -206,21 +206,21 @@ Gets the collection of types that may be encountered during serialization or deserialization. A collection that contains types that may be encountered during serialization or deserialization. XML schema representations are exported for all the types specified in this collection by the . - property is used by the to include types that can be read in an object graph (set using the property). - - For more information about the data contract and known types, see [Data Contract Known Types](/dotnet/framework/wcf/feature-details/data-contract-known-types). - - - -## Examples - The following example creates an instance of the class and adds a type to the collection returned by the property. - + property is used by the to include types that can be read in an object graph (set using the property). + + For more information about the data contract and known types, see [Data Contract Known Types](/dotnet/framework/wcf/feature-details/data-contract-known-types). + + + +## Examples + The following example creates an instance of the class and adds a type to the collection returned by the property. + :::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"::: + ]]> diff --git a/xml/System.Runtime.Serialization/ExtensionDataObject.xml b/xml/System.Runtime.Serialization/ExtensionDataObject.xml index 59bfef168bf..d11abb6f659 100644 --- a/xml/System.Runtime.Serialization/ExtensionDataObject.xml +++ b/xml/System.Runtime.Serialization/ExtensionDataObject.xml @@ -45,19 +45,19 @@ Stores data from a versioned data contract that has been extended by adding new members. - is the structure that stores extra data encountered by the during deserialization operations. The structure is used by serialization to write the extra data into the serialized instance. The structure is returned by the property of the interface. - - - -## Examples - The following code serializes an instance of a type (`PersonVersion2`) that is the second version of the serializable type (`Person`). The second version contains extra data (`ID` field) that is not present in the first version. The code then deserializes the XML document into a `Person` object, then immediately reserializes the object including the extra data. Finally, the code deserializes the new XML into a `PersonVersion2` object and writes the complete data to the console, proving that the data has made a round trip to and from an older version of the type. Note that the attribute must be applied with the and properties set to the same name and namespace as the original class. - + is the structure that stores extra data encountered by the during deserialization operations. The structure is used by serialization to write the extra data into the serialized instance. The structure is returned by the property of the interface. + + + +## Examples + The following code serializes an instance of a type (`PersonVersion2`) that is the second version of the serializable type (`Person`). The second version contains extra data (`ID` field) that is not present in the first version. The code then deserializes the XML document into a `Person` object, then immediately reserializes the object including the extra data. Finally, the code deserializes the new XML into a `PersonVersion2` object and writes the complete data to the console, proving that the data has made a round trip to and from an older version of the type. Note that the attribute must be applied with the and properties set to the same name and namespace as the original class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/iunknownserializationdata/cs/iunknownserialization.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/iunknownserializationdata/vb/iunknownserialization.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/iunknownserializationdata/vb/iunknownserialization.vb" id="Snippet0"::: + ]]> diff --git a/xml/System.Runtime.Serialization/IDataContractSurrogate.xml b/xml/System.Runtime.Serialization/IDataContractSurrogate.xml index 4a5cb2c70c6..b576c1034d2 100644 --- a/xml/System.Runtime.Serialization/IDataContractSurrogate.xml +++ b/xml/System.Runtime.Serialization/IDataContractSurrogate.xml @@ -15,23 +15,23 @@ Provides the methods needed to substitute one type for another by the during serialization, deserialization, and export and import of XML schema documents (XSD). - when using the if you need to do one of the following: substitute one type or object for another, or to dynamically generate schema variations. For a sample application, see [DataContract Surrogate](/dotnet/framework/wcf/samples/datacontract-surrogate). For more information about data contracts, see [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). - - At run time, you can find the specific for any operation in a service by using the to find the instance. For more information about implementing the interface to create a surrogate, see [Data Contract Surrogates](/dotnet/framework/wcf/extending/data-contract-surrogates). - - You can also use the to affect the import and export of XML schemas when you are using the and classes. You can do so by assigning the to the property of the class, or to the property of the class. For more information, see [Schema Import and Export](/dotnet/framework/wcf/feature-details/schema-import-and-export). - - - -## Examples - The following example shows an implementation of the interface. The code substitutes the serialization of the `Person` type for a `PersonSurrogated` class. - + when using the if you need to do one of the following: substitute one type or object for another, or to dynamically generate schema variations. For a sample application, see [DataContract Surrogate](/dotnet/framework/wcf/samples/datacontract-surrogate). For more information about data contracts, see [Using Data Contracts](/dotnet/framework/wcf/feature-details/using-data-contracts). + + At run time, you can find the specific for any operation in a service by using the to find the instance. For more information about implementing the interface to create a surrogate, see [Data Contract Surrogates](/dotnet/framework/wcf/extending/data-contract-surrogates). + + You can also use the to affect the import and export of XML schemas when you are using the and classes. You can do so by assigning the to the property of the class, or to the property of the class. For more information, see [Schema Import and Export](/dotnet/framework/wcf/feature-details/schema-import-and-export). + + + +## Examples + The following example shows an implementation of the interface. The code substitutes the serialization of the `Person` type for a `PersonSurrogated` class. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/idatacontractsurrogate/cs/source.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/idatacontractsurrogate/vb/source.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/idatacontractsurrogate/vb/source.vb" id="Snippet0"::: + ]]> @@ -132,14 +132,14 @@ During serialization, deserialization, and schema import and export, returns a data contract type that substitutes the specified type. The to substitute for the value. This type must be serializable by the . For example, it must be marked with the attribute or other mechanisms that the serializer recognizes. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/idatacontractsurrogate/cs/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/idatacontractsurrogate/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/idatacontractsurrogate/vb/source.vb" id="Snippet1"::: + ]]> @@ -170,19 +170,19 @@ During deserialization, returns an object that is a substitute for the specified object. The substituted deserialized object. This object must be of a type that is serializable by the . For example, it must be marked with the attribute or other mechanisms that the serializer recognizes. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/idatacontractsurrogate/cs/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/idatacontractsurrogate/vb/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/idatacontractsurrogate/vb/source.vb" id="Snippet3"::: + ]]> @@ -210,11 +210,11 @@ A of to add known types to. Sets the collection of known types to use for serialization and deserialization of the custom data objects. - method. - + method. + ]]> @@ -245,19 +245,19 @@ During serialization, returns an object that substitutes the specified object. The substituted object that will be serialized. The object must be serializable by the . For example, it must be marked with the attribute or other mechanisms that the serializer recognizes. - and an is thrown. - - - -## Examples - The following example shows an implementation of the method. - + and an is thrown. + + + +## Examples + The following example shows an implementation of the method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/idatacontractsurrogate/cs/source.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/idatacontractsurrogate/vb/source.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/idatacontractsurrogate/vb/source.vb" id="Snippet2"::: + ]]> @@ -290,19 +290,19 @@ During schema import, returns the type referenced by the schema. The to use for the referenced type. - method. - + method. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/idatacontractsurrogate/cs/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/idatacontractsurrogate/vb/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/idatacontractsurrogate/vb/source.vb" id="Snippet4"::: + ]]> @@ -333,11 +333,11 @@ Processes the type that has been generated from the imported schema. A that contains the processed type. - or other information in the can be modified by the user in this method. If `null` is returned, it will cause the type to not be generated. If a new is returned, it will replace the original type generated. - + or other information in the can be modified by the user in this method. If `null` is returned, it will cause the type to not be generated. If a new is returned, it will replace the original type generated. + ]]> diff --git a/xml/System.Runtime.Serialization/KnownTypeAttribute.xml b/xml/System.Runtime.Serialization/KnownTypeAttribute.xml index 8a4ead3142b..661f3ff1c60 100644 --- a/xml/System.Runtime.Serialization/KnownTypeAttribute.xml +++ b/xml/System.Runtime.Serialization/KnownTypeAttribute.xml @@ -58,24 +58,24 @@ Specifies types that should be recognized by the when serializing or deserializing a given type. - attribute to a type to indicate to the types that should be recognized when serializing or deserializing an instance of the type to which the attribute is applied. This attribute could also be recognized by other serializers that understand data contracts. - + attribute to a type to indicate to the types that should be recognized when serializing or deserializing an instance of the type to which the attribute is applied. This attribute could also be recognized by other serializers that understand data contracts. + > [!NOTE] -> In your code, you can use the word `KnownType` instead of the longer `KnownTypeAttribute`. - - You can either apply exactly one instance with the property set, or one or more instances with the property set. - - - -## Examples - The following example shows a type named `Person` and a type named `IDInformation` that should be recognized when serializing or deserializing the `Person` type. - +> In your code, you can use the word `KnownType` instead of the longer `KnownTypeAttribute`. + + You can either apply exactly one instance with the property set, or one or more instances with the property set. + + + +## Examples + The following example shows a type named `Person` and a type named `IDInformation` that should be recognized when serializing or deserializing the `Person` type. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/knowntypeattribute/cs/overview.cs" id="Snippet0"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/knowntypeattribute/vb/overview.vb" id="Snippet0"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/knowntypeattribute/vb/overview.vb" id="Snippet0"::: + ]]> @@ -135,19 +135,19 @@ The name of the method that returns an of types used when serializing or deserializing data. Initializes a new instance of the class with the name of a method that returns an of known types. - of objects. During serialization or deserialization, the types found in the collection can be used within the root type to which the attribute is applied. - - - -## Examples - The following example uses the `methodName` parameter to identify a method in the type that contains an array of objects. - + of objects. During serialization or deserialization, the types found in the collection can be used within the root type to which the attribute is applied. + + + +## Examples + The following example uses the `methodName` parameter to identify a method in the type that contains an array of objects. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/knowntypeattribute_ctor_string/cs/knowntype_ctor1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/knowntypeattribute_ctor_string/vb/knowntypeattribute_ctor1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/knowntypeattribute_ctor_string/vb/knowntypeattribute_ctor1.vb" id="Snippet1"::: + ]]> @@ -193,14 +193,14 @@ The that is included as a known type when serializing or deserializing data. Initializes a new instance of the class with the specified type. - @@ -247,21 +247,21 @@ Gets the name of a method that will return a list of types that should be recognized during serialization or deserialization. A that contains the name of the method on the type defined by the class. - is applied to, must be static, must accept no parameters, and must return an instance of any type that implements the generic interface, such as the class, or an array of objects. - - The method is called once per application domain when the data contract is loaded for the type. - - - -## Examples - The following example uses the `methodName` parameter to identify a method in the type that contains an array of objects. - + is applied to, must be static, must accept no parameters, and must return an instance of any type that implements the generic interface, such as the class, or an array of objects. + + The method is called once per application domain when the data contract is loaded for the type. + + + +## Examples + The following example uses the `methodName` parameter to identify a method in the type that contains an array of objects. + :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/knowntypeattribute_ctor_string/cs/knowntype_ctor1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/knowntypeattribute_ctor_string/vb/knowntypeattribute_ctor1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/knowntypeattribute_ctor_string/vb/knowntypeattribute_ctor1.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Runtime.Serialization/SerializationException.xml b/xml/System.Runtime.Serialization/SerializationException.xml index 52ad0a961c2..e2b45f302ba 100644 --- a/xml/System.Runtime.Serialization/SerializationException.xml +++ b/xml/System.Runtime.Serialization/SerializationException.xml @@ -342,7 +342,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Runtime.Serialization/SerializationInfo.xml b/xml/System.Runtime.Serialization/SerializationInfo.xml index afae2052508..d7b9dca77dd 100644 --- a/xml/System.Runtime.Serialization/SerializationInfo.xml +++ b/xml/System.Runtime.Serialization/SerializationInfo.xml @@ -1335,7 +1335,7 @@ End Sub is the same as the value returned by property of the assembly of the containing type. This is the assembly name that the formatter uses when serializing type information for this object. + The is the same as the value returned by property of the assembly of the containing type. This is the assembly name that the formatter uses when serializing type information for this object. The assembly name contains the name of the assembly, version, culture, and some security information about the object. @@ -2500,7 +2500,7 @@ End Sub ## Examples The following code example demonstrates the use of the method: - + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Serialization/SerializationInfo/GetValue/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Serialization/SerializationInfo/GetValue/source.vb" id="Snippet1"::: diff --git a/xml/System.Runtime.Serialization/SerializationInfoEnumerator.xml b/xml/System.Runtime.Serialization/SerializationInfoEnumerator.xml index 2599a4c8411..2e6e6ae6c51 100644 --- a/xml/System.Runtime.Serialization/SerializationInfoEnumerator.xml +++ b/xml/System.Runtime.Serialization/SerializationInfoEnumerator.xml @@ -76,13 +76,13 @@ Provides a formatter-friendly mechanism for parsing the data in . This class cannot be inherited. - . Instead of recording the values, the keeps pointers to the member variables of the that created it. - + . Instead of recording the values, the keeps pointers to the member variables of the that created it. + This class follows the mechanism. - + ]]> @@ -187,11 +187,11 @@ if a new element is found; otherwise, . - and go through each item until you reach the last element. - + ]]> @@ -340,11 +340,11 @@ Resets the enumerator to the first item. - property will contain the first item in the current set of elements. - + property will contain the first item in the current set of elements. + ]]> diff --git a/xml/System.Runtime.Serialization/StreamingContext.xml b/xml/System.Runtime.Serialization/StreamingContext.xml index d36387a871a..7f4b1b1fb0e 100644 --- a/xml/System.Runtime.Serialization/StreamingContext.xml +++ b/xml/System.Runtime.Serialization/StreamingContext.xml @@ -85,7 +85,7 @@ can serialize or ignore fields and values based on the information stored in the streaming context. For example, a window handle is still valid if the property is set to `System.Runtime.Serialization.StreamingContextStates.CrossProcess`. + Indicates the source or destination of the bits that the formatter uses. Classes with surrogates or that implement can serialize or ignore fields and values based on the information stored in the streaming context. For example, a window handle is still valid if the property is set to `System.Runtime.Serialization.StreamingContextStates.CrossProcess`. ]]> diff --git a/xml/System.Runtime.Serialization/XmlSerializableServices.xml b/xml/System.Runtime.Serialization/XmlSerializableServices.xml index fe353cbfe28..5d8db1ed488 100644 --- a/xml/System.Runtime.Serialization/XmlSerializableServices.xml +++ b/xml/System.Runtime.Serialization/XmlSerializableServices.xml @@ -51,13 +51,13 @@ Contains methods for reading and writing XML. - property of the class. Setting the property to `true` specifies that these types are imported as XML types that implement the interface. In the process, the generated types can store anything, but they are read and written as XML by the serializer. - - The is an abstract helper class that contains code that is used by the generated types to read and write XML. It also contains code for generating schema for the generated types. Note that details about the schemas are not stored. Only the name is stored in the generated type. This class generates a default schema that represents the XML schema type `anyType` with the appropriate schema type name as the contract name. - + property of the class. Setting the property to `true` specifies that these types are imported as XML types that implement the interface. In the process, the generated types can store anything, but they are read and written as XML by the serializer. + + The is an abstract helper class that contains code that is used by the generated types to read and write XML. It also contains code for generating schema for the generated types. Note that details about the schemas are not stored. Only the name is stored in the generated type. This class generates a default schema that represents the XML schema type `anyType` with the appropriate schema type name as the contract name. + ]]> @@ -106,11 +106,11 @@ An that specifies the type name to assign the schema to. Generates a default schema type given the specified type name and adds it to the specified schema set. - The or argument is . @@ -159,11 +159,11 @@ Reads a set of XML nodes from the specified reader and returns the result. An array of type . - objects. It is a helper method used by the types that implement and that use the method. - + objects. It is a helper method used by the types that implement and that use the method. + ]]> The argument is . diff --git a/xml/System.Runtime.Serialization/XsdDataContractExporter.xml b/xml/System.Runtime.Serialization/XsdDataContractExporter.xml index ff562e55f61..d217f4dc007 100644 --- a/xml/System.Runtime.Serialization/XsdDataContractExporter.xml +++ b/xml/System.Runtime.Serialization/XsdDataContractExporter.xml @@ -371,7 +371,7 @@ The following example creates an instance of the overloads to determine whether the specified type or set of types can be exported. - After calling the method, retrieve the schemas from the property. + After calling the method, retrieve the schemas from the property. ]]> @@ -544,7 +544,7 @@ The following example creates an instance of the to determine whether the type can be exported. After calling the method, the schema can be retrieved through the property. + Call the to determine whether the type can be exported. After calling the method, the schema can be retrieved through the property. ]]> diff --git a/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml b/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml index 7fe8eec4c04..f93d5080eb4 100644 --- a/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml +++ b/xml/System.Runtime.Versioning/ComponentGuaranteesAttribute.xml @@ -107,7 +107,7 @@ class is instantiated, the value of the `guarantees` parameter is assigned to the property. + When the class is instantiated, the value of the `guarantees` parameter is assigned to the property. ]]> @@ -157,7 +157,7 @@ property corresponds to the `guarantees` parameter of the constructor. + The value of the property corresponds to the `guarantees` parameter of the constructor. ]]> diff --git a/xml/System.Runtime.Versioning/FrameworkName.xml b/xml/System.Runtime.Versioning/FrameworkName.xml index 71485c5113c..5550c0ab821 100644 --- a/xml/System.Runtime.Versioning/FrameworkName.xml +++ b/xml/System.Runtime.Versioning/FrameworkName.xml @@ -146,11 +146,11 @@ The values of the *identifier*, *versionNumber*, and *profileName* components define the values of this object's properties as follows: -- Any leading or trailing white space in the *identifier* component is removed and the resulting string is assigned to the property. +- Any leading or trailing white space in the *identifier* component is removed and the resulting string is assigned to the property. -- Any leading or trailing white space and the initial "v" or "V", if present, are removed from the `versionNumber`. The returned string is then passed to the constructor, and the resulting object is assigned to the property. +- Any leading or trailing white space and the initial "v" or "V", if present, are removed from the `versionNumber`. The returned string is then passed to the constructor, and the resulting object is assigned to the property. -- Any leading or trailing white space in the `profileName` component is removed and the resulting string is assigned to the property. +- Any leading or trailing white space in the `profileName` component is removed and the resulting string is assigned to the property. The following are examples of valid strings that can be passed to the constructor: @@ -464,9 +464,9 @@ ## Remarks The method tests for equality by returning the result of the following comparisons: -- An ordinal comparison of the property values of the current instance and `other`. +- An ordinal comparison of the property values of the current instance and `other`. -- An ordinal comparison of the property values of the current instance and `other`. +- An ordinal comparison of the property values of the current instance and `other`. - A comparison of the version properties by calling the method. @@ -520,13 +520,13 @@ property has the following format: + The string returned by the property has the following format: *identifier*, Version=*version*[, Profile=*profile*] - where *identifier* corresponds to the property, `version` is equivalent to calling on the value of the property, and `profile` corresponds to the property. If a profile has not been assigned to the object, the profile component is not included in the string. + where *identifier* corresponds to the property, `version` is equivalent to calling on the value of the property, and `profile` corresponds to the property. If a profile has not been assigned to the object, the profile component is not included in the string. - The value of the property is identical to the string returned by the method. + The value of the property is identical to the string returned by the method. ]]> @@ -630,7 +630,7 @@ property is set in the class constructor. + The value of the read-only property is set in the class constructor. ]]> @@ -828,7 +828,7 @@ property is set in the class constructor. + The value of the read-only property is set in the class constructor. ]]> @@ -891,9 +891,9 @@ *identifier*, Version=*version*[, Profile=*profile*] - where *identifier* corresponds to the property, `version` is equivalent to calling on the value of the property, and `profile` corresponds to the property. If a profile has not been assigned to the object, the profile component is not included in the returned string. + where *identifier* corresponds to the property, `version` is equivalent to calling on the value of the property, and `profile` corresponds to the property. If a profile has not been assigned to the object, the profile component is not included in the returned string. - The value returned by the method is identical to the value of the property. + The value returned by the method is identical to the value of the property. ]]> @@ -951,7 +951,7 @@ property is set in the class constructor. + The value of the read-only property is set in the class constructor. ]]> diff --git a/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml b/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml index 5b232f67757..d79ed990d27 100644 --- a/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml +++ b/xml/System.Runtime.Versioning/TargetFrameworkAttribute.xml @@ -59,19 +59,19 @@ Identifies the version of .NET that a particular assembly was compiled against. - class provides an attribute that you can apply to an assembly to indicate the version of the .NET runtime against which the assembly was built. For example, the following example applies the `TargetFrameworkAttribute` to an assembly to indicate that it was built using .NET Framework 4. - + class provides an attribute that you can apply to an assembly to indicate the version of the .NET runtime against which the assembly was built. For example, the following example applies the `TargetFrameworkAttribute` to an assembly to indicate that it was built using .NET Framework 4. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Versioning/TargetFrameworkAttribute/Overview/declare1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Versioning/TargetFrameworkAttribute/Overview/declare1.vb" id="Snippet1"::: - - The class constructor has a single parameter, `frameworkName`, that specifies the .NET version against which the assembly was built. This parameter maps to the property. In addition, the attribute can specify a property to provide a more descriptive .NET version string that is suitable for displaying to clients of the assembly. The following example applies the `TargetFrameworkAttribute` to an assembly and assigns both property values to indicate that the assembly was built using .NET Framework 4. - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Versioning/TargetFrameworkAttribute/Overview/declare1.vb" id="Snippet1"::: + + The class constructor has a single parameter, `frameworkName`, that specifies the .NET version against which the assembly was built. This parameter maps to the property. In addition, the attribute can specify a property to provide a more descriptive .NET version string that is suitable for displaying to clients of the assembly. The following example applies the `TargetFrameworkAttribute` to an assembly and assigns both property values to indicate that the assembly was built using .NET Framework 4. + :::code language="csharp" source="~/snippets/csharp/System.Runtime.Versioning/TargetFrameworkAttribute/Overview/declare2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Versioning/TargetFrameworkAttribute/Overview/declare2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Runtime.Versioning/TargetFrameworkAttribute/Overview/declare2.vb" id="Snippet2"::: + ]]> @@ -119,11 +119,11 @@ The version of .NET against which the assembly was built. Initializes an instance of the class by specifying the .NET version against which an assembly was built. - method. - + method. + ]]> @@ -179,11 +179,11 @@ Gets the display name of the .NET version against which an assembly was built. The display name of the .NET version. - property usually returns a relatively long descriptive string that is suitable for display to a user. - + property usually returns a relatively long descriptive string that is suitable for display to a user. + ]]> @@ -231,11 +231,11 @@ Gets the name of the .NET version against which a particular assembly was compiled. The name of the .NET version with which the assembly was compiled. - property maps to the `frameworkName` parameter of the constructor. It represents the .NET version in a compact form and typically corresponds to the string that is returned by the method. - + property maps to the `frameworkName` parameter of the constructor. It represents the .NET version in a compact form and typically corresponds to the string that is returned by the method. + ]]> diff --git a/xml/System.Runtime/GCLargeObjectHeapCompactionMode.xml b/xml/System.Runtime/GCLargeObjectHeapCompactionMode.xml index 7e9f436ed64..87e064e14b8 100644 --- a/xml/System.Runtime/GCLargeObjectHeapCompactionMode.xml +++ b/xml/System.Runtime/GCLargeObjectHeapCompactionMode.xml @@ -53,11 +53,11 @@ Indicates whether the next blocking garbage collection compacts the large object heap (LOH). - property is a member of the enumeration that indicates whether the next full blocking garbage collection also compacts the large object heap (LOH). By default, the LOH is not compacted. A value of CompactOnce indicates that the blocking garbage collection will compact the LOH. After the garbage collection, the value of the property reverts to Default. - + property is a member of the enumeration that indicates whether the next full blocking garbage collection also compacts the large object heap (LOH). By default, the LOH is not compacted. A value of CompactOnce indicates that the blocking garbage collection will compact the LOH. After the garbage collection, the value of the property reverts to Default. + ]]> diff --git a/xml/System.Runtime/GCLatencyMode.xml b/xml/System.Runtime/GCLatencyMode.xml index ec613cf1d29..9623e92b2e4 100644 --- a/xml/System.Runtime/GCLatencyMode.xml +++ b/xml/System.Runtime/GCLatencyMode.xml @@ -56,14 +56,14 @@ Adjusts the time that the garbage collector intrudes in your application. - property to any enumeration value except `GCLatencyMode.NoGCRegion`. You can also determine the garbage collector's current latency mode by retrieving the property value. - - See [Latency Modes](/dotnet/standard/garbage-collection/latency) for a discussion of how the runtime configuration settings for garbage collection affect the default value for this enumeration. + mode overrides the [\](/dotnet/framework/configure-apps/file-schema/runtime/gcconcurrent-element) runtime configuration setting. If concurrent garbage collection is enabled by the [\](/dotnet/framework/configure-apps/file-schema/runtime/gcconcurrent-element) element, switching to Batch mode prevents any further concurrent collections. +## Remarks + You can adjust the intrusiveness of garbage collection in your application by setting the property to any enumeration value except `GCLatencyMode.NoGCRegion`. You can also determine the garbage collector's current latency mode by retrieving the property value. + + See [Latency Modes](/dotnet/standard/garbage-collection/latency) for a discussion of how the runtime configuration settings for garbage collection affect the default value for this enumeration. + +The mode overrides the [\](/dotnet/framework/configure-apps/file-schema/runtime/gcconcurrent-element) runtime configuration setting. If concurrent garbage collection is enabled by the [\](/dotnet/framework/configure-apps/file-schema/runtime/gcconcurrent-element) element, switching to Batch mode prevents any further concurrent collections. ]]> @@ -238,8 +238,8 @@ The mode 4 - Indicates that garbage collection is suspended while the app is executing a critical path. - + Indicates that garbage collection is suspended while the app is executing a critical path. + is a read-only value; that is, you cannot assign the value to the property. You specify the no GC region latency mode by calling the method and terminate it by calling the method. diff --git a/xml/System.Runtime/GCSettings.xml b/xml/System.Runtime/GCSettings.xml index c9a687457e1..6dcebbfab75 100644 --- a/xml/System.Runtime/GCSettings.xml +++ b/xml/System.Runtime/GCSettings.xml @@ -50,11 +50,11 @@ Specifies the garbage collection settings for the current process. - property to determine whether server garbage collection is enabled for the current process. - + property to determine whether server garbage collection is enabled for the current process. + ]]> @@ -109,22 +109,22 @@ if server garbage collection is enabled; otherwise, . - @@ -188,21 +188,21 @@ For information about server garbage collection, see [Workstation and Server Gar Gets or sets a value that indicates whether a full blocking garbage collection compacts the large object heap (LOH). One of the enumeration values that indicates whether a full blocking garbage collection compacts the LOH. - property to compact rather than simply sweep the LOH during a garbage collection. - - The default value of the property is , which indicates that the LOH is not compacted during garbage collections. If you assign the property a value of , the LOH is compacted during the next full blocking garbage collection, and the property value is reset to . - + property to compact rather than simply sweep the LOH during a garbage collection. + + The default value of the property is , which indicates that the LOH is not compacted during garbage collections. If you assign the property a value of , the LOH is compacted during the next full blocking garbage collection, and the property value is reset to . + > [!NOTE] -> Background garbage collections are not blocking. This means that, if you set the property to , any background generation 2 collections that occur subsequently do not compact the LOH. Only the first blocking generation 2 collection compacts the LOH. - - After the property is set to , the next full blocking garbage collection (and compaction of the LOH) occurs at an indeterminate future time. You can compact the LOH immediately by using code like the following: - +> Background garbage collections are not blocking. This means that, if you set the property to , any background generation 2 collections that occur subsequently do not compact the LOH. Only the first blocking generation 2 collection compacts the LOH. + + After the property is set to , the next full blocking garbage collection (and compaction of the LOH) occurs at an indeterminate future time. You can compact the LOH immediately by using code like the following: + :::code language="csharp" source="~/snippets/csharp/System/GC/Collect/lohcompactionmode1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/GC/Collect/lohcompactionmode1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System/GC/Collect/lohcompactionmode1.vb" id="Snippet1"::: + ]]> @@ -269,21 +269,21 @@ For information about server garbage collection, see [Workstation and Server Gar Gets or sets the current latency mode for garbage collection. One of the enumeration values that specifies the latency mode. - to during critical operations. After such operations are completed, return to a higher latency mode so that more objects can be reclaimed to increase memory. - - Ordinarily, you set the value of the property to define the garbage collector's latency mode. However, you cannot set the no GC region latency mode by assigning the enumeration value to the property. Instead, you call the method to begin the no GC region latency mode, and you call the to end it. - - See [Latency Modes](/dotnet/standard/garbage-collection/latency) for a discussion of how the runtime configuration settings for garbage collection affect the default value of the enumeration. - + to during critical operations. After such operations are completed, return to a higher latency mode so that more objects can be reclaimed to increase memory. + + Ordinarily, you set the value of the property to define the garbage collector's latency mode. However, you cannot set the no GC region latency mode by assigning the enumeration value to the property. Instead, you call the method to begin the no GC region latency mode, and you call the to end it. + + See [Latency Modes](/dotnet/standard/garbage-collection/latency) for a discussion of how the runtime configuration settings for garbage collection affect the default value of the enumeration. + ]]> - The property is being set to an invalid value. - - -or- - + The property is being set to an invalid value. + + -or- + The property cannot be set to . Latency Modes diff --git a/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml b/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml index 66c1f5e5feb..bce9568bf4a 100644 --- a/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml +++ b/xml/System.Security.AccessControl/EventWaitHandleAccessRule.xml @@ -45,43 +45,43 @@ Represents a set of access rights allowed or denied for a user or group. This class cannot be inherited. - [!NOTE] > This type is only supported on Windows. - The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system events. For an overview of these classes, and their relationship to the underlying Windows access control structures, see . - + The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system events. For an overview of these classes, and their relationship to the underlying Windows access control structures, see . + > [!NOTE] -> Windows access control security is meaningful only for named system events. If an object represents a local event, access control is irrelevant. - - To get a list of the rules currently applied to a named event, use the method to get an object, and then use its method to obtain a collection of objects. - - objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for an event, the set contains the minimum number of rules currently required to express all the access control entries. - +> Windows access control security is meaningful only for named system events. If an object represents a local event, access control is irrelevant. + + To get a list of the rules currently applied to a named event, use the method to get an object, and then use its method to obtain a collection of objects. + + objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for an event, the set contains the minimum number of rules currently required to express all the access control entries. + > [!NOTE] -> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you get the current list of rules, it might not look exactly like the list of all the rules you have added. - - Use objects to specify the access rights to allow or deny to a user or group. An object always represents either allowed access or denied access, never both. - - To apply a rule to a named system event, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. - +> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you get the current list of rules, it might not look exactly like the list of all the rules you have added. + + Use objects to specify the access rights to allow or deny to a user or group. An object always represents either allowed access or denied access, never both. + + To apply a rule to a named system event, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + > [!IMPORTANT] -> Changes you make to an object do not affect the access levels of the named event until you call the method to assign the altered security object to the named event. - +> Changes you make to an object do not affect the access levels of the named event until you call the method to assign the altered security object to the named event. + objects are immutable. Security for an event is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. - -## Examples - The following code example demonstrates the creation and use of objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + +## Examples + The following code example demonstrates the creation and use of objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . - +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> @@ -134,24 +134,24 @@ One of the values specifying whether the rights are allowed or denied. Initializes a new instance of the class, specifying the user or group the rule applies to, the access rights, and whether the specified access rights are allowed or denied. - (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. - + (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. + ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type nor of a type such as that can be converted to type . @@ -195,43 +195,43 @@ One of the values specifying whether the rights are allowed or denied. Initializes a new instance of the class, specifying the name of the user or group the rule applies to, the access rights, and whether the specified access rights are allowed or denied. - (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. - - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. - - - -## Examples - The following code example demonstrates the use of this constructor to create objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + (by calling the , or method), a user must have access. To signal an event by calling the method, or to reset it to the unsignaled state by calling the method, a user must have access. To signal an object and then wait on it by calling the method, a user must have and access. + + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + + + +## Examples + The following code example demonstrates the use of this constructor to create objects. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . - +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. is zero. - is . - - -or- - - is a zero-length string. - - -or- - + is . + + -or- + + is a zero-length string. + + -or- + is longer than 512 characters. @@ -269,22 +269,22 @@ Gets the rights allowed or denied by the access rule. A bitwise combination of values indicating the rights allowed or denied by the access rule. - objects are immutable. You can create a new access rule representing a different user, different rights, or a different , but you cannot modify an existing access rule. - - - -## Examples - The following code example demonstrates the use of the property to display the rights in the set of rules contained in an object. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + objects are immutable. You can create a new access rule representing a different user, different rights, or a different , but you cannot modify an existing access rule. + + + +## Examples + The following code example demonstrates the use of the property to display the rights in the set of rules contained in an object. The example creates an object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . - +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/EventWaitHandleAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml b/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml index 9acef1e5e0c..fcc1e12b265 100644 --- a/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml +++ b/xml/System.Security.AccessControl/EventWaitHandleSecurity.xml @@ -184,7 +184,7 @@ class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. ]]> @@ -297,7 +297,7 @@ class override the property and return the type they use to represent access rules. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct access rule type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent access rules. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct access rule type to use with each security object. ]]> @@ -517,7 +517,7 @@ class override the property and return the type they use to represent audit rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct audit rule type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent audit rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct audit rule type to use with each security object. ]]> diff --git a/xml/System.Security.AccessControl/FileSystemSecurity.xml b/xml/System.Security.AccessControl/FileSystemSecurity.xml index 89dddfe06c0..c883c47dddf 100644 --- a/xml/System.Security.AccessControl/FileSystemSecurity.xml +++ b/xml/System.Security.AccessControl/FileSystemSecurity.xml @@ -107,7 +107,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. ]]> @@ -172,10 +172,10 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i ]]> The , , , or parameters specify an invalid value. - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is zero. The parameter is neither of type , nor of a type such as that can be converted to type . @@ -217,7 +217,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i class override the property and return the type they use to represent access rules. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct access rule type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent access rules. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct access rule type to use with each security object. ]]> @@ -403,10 +403,10 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i ]]> The , , , or properties specify an invalid value. - The property is . - - -or- - + The property is . + + -or- + The property is zero. The property is neither of type , nor of a type such as that can be converted to type . @@ -448,7 +448,7 @@ Use the following .NET implementation-dependent methods to add or retrieve ACL i class override the property and return the type they use to represent audit rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct audit rule type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent audit rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct audit rule type to use with each security object. ]]> diff --git a/xml/System.Security.AccessControl/MutexAccessRule.xml b/xml/System.Security.AccessControl/MutexAccessRule.xml index 7de1b810fdb..8671bc2f13b 100644 --- a/xml/System.Security.AccessControl/MutexAccessRule.xml +++ b/xml/System.Security.AccessControl/MutexAccessRule.xml @@ -45,43 +45,43 @@ Represents a set of access rights allowed or denied for a user or group. This class cannot be inherited. - [!NOTE] > This type is only supported on Windows. - The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system mutexes. For an overview of these classes, and their relationship to the underlying Windows access control structures, see . - + The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system mutexes. For an overview of these classes, and their relationship to the underlying Windows access control structures, see . + > [!NOTE] -> Windows access control security is meaningful only for named system mutexes. If a object represents a local mutex, access control is irrelevant. - - To get a list of the rules currently applied to a named mutex, use the method to get a object, and then use its method to obtain a collection of objects. - - objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for a mutex, the set contains the minimum number of rules currently required to express all the access control entries. - +> Windows access control security is meaningful only for named system mutexes. If a object represents a local mutex, access control is irrelevant. + + To get a list of the rules currently applied to a named mutex, use the method to get a object, and then use its method to obtain a collection of objects. + + objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for a mutex, the set contains the minimum number of rules currently required to express all the access control entries. + > [!NOTE] -> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. - - Use objects to specify access rights to allow or deny to a user or group. A object always represents either allowed access or denied access, never both. - - To apply a rule to a named system mutex, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. - +> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. + + Use objects to specify access rights to allow or deny to a user or group. A object always represents either allowed access or denied access, never both. + + To apply a rule to a named system mutex, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. - +> Changes you make to a object do not affect the access levels of the named mutex until you call the method to assign the altered security object to the named mutex. + objects are immutable. Security for a mutex is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. - -## Examples - The following code example demonstrates the creation and use of objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + +## Examples + The following code example demonstrates the creation and use of objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . - +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> @@ -134,24 +134,24 @@ One of the values specifying whether the rights are allowed or denied. Initializes a new instance of the class, specifying the user or group the rule applies to, the access rights, and whether the specified access rights are allowed or denied. - (by calling the , or method), a user must have access. To release the mutex, by calling the method, the user must have access. - + (by calling the , or method), a user must have access. To release the mutex, by calling the method, the user must have access. + ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type nor of a type such as that can be converted to type . @@ -195,43 +195,43 @@ One of the values specifying whether the rights are allowed or denied. Initializes a new instance of the class, specifying the name of the user or group the rule applies to, the access rights, and whether the specified access rights are allowed or denied. - (by calling the , or method), a user must have access. To release the mutex, by calling the methods, the user must have access. - - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. - - - -## Examples - The following code example demonstrates the use of this constructor to create objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + (by calling the , or method), a user must have access. To release the mutex, by calling the methods, the user must have access. + + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + + + +## Examples + The following code example demonstrates the use of this constructor to create objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . - +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. is zero. - is . - - -or- - - is a zero-length string. - - -or- - + is . + + -or- + + is a zero-length string. + + -or- + is longer than 512 characters. @@ -269,22 +269,22 @@ Gets the rights allowed or denied by the access rule. A bitwise combination of values indicating the rights allowed or denied by the access rule. - objects are immutable. You can create a new access rule representing a different user, different rights, or a different , but you cannot modify an existing access rule. - - - -## Examples - The following code example demonstrates the use of the property to display the rights in the set of rules contained in a object. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + objects are immutable. You can create a new access rule representing a different user, different rights, or a different , but you cannot modify an existing access rule. + + + +## Examples + The following code example demonstrates the use of the property to display the rights in the set of rules contained in a object. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . - +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/MutexAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/MutexAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.AccessControl/MutexSecurity.xml b/xml/System.Security.AccessControl/MutexSecurity.xml index 0930ca8628e..29971581f37 100644 --- a/xml/System.Security.AccessControl/MutexSecurity.xml +++ b/xml/System.Security.AccessControl/MutexSecurity.xml @@ -245,7 +245,7 @@ class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. ]]> @@ -358,7 +358,7 @@ class override the property and return the type they use to represent access rules. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct access rule type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent access rules. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct access rule type to use with each security object. ]]> @@ -578,7 +578,7 @@ class override the property and return the type they use to represent audit rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct audit rule type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent audit rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct audit rule type to use with each security object. ]]> diff --git a/xml/System.Security.AccessControl/RegistrySecurity.xml b/xml/System.Security.AccessControl/RegistrySecurity.xml index 6b5f5db673b..dbabeccdcf5 100644 --- a/xml/System.Security.AccessControl/RegistrySecurity.xml +++ b/xml/System.Security.AccessControl/RegistrySecurity.xml @@ -212,7 +212,7 @@ class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. ]]> @@ -282,10 +282,10 @@ , , , or specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type , nor of a type such as that can be converted to type . @@ -331,7 +331,7 @@ class override the property and return the type they use to represent access rules. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct access rule type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent access rules. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct access rule type to use with each security object. ]]> @@ -522,10 +522,10 @@ , , , or specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type , nor of a type such as that can be converted to type . @@ -571,7 +571,7 @@ class override the property and return the type they use to represent audit rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct audit rule type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent audit rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct audit rule type to use with each security object. ]]> diff --git a/xml/System.Security.AccessControl/SemaphoreAccessRule.xml b/xml/System.Security.AccessControl/SemaphoreAccessRule.xml index a8fda4779e9..0c7eb786104 100644 --- a/xml/System.Security.AccessControl/SemaphoreAccessRule.xml +++ b/xml/System.Security.AccessControl/SemaphoreAccessRule.xml @@ -49,43 +49,43 @@ Represents a set of access rights allowed or denied for a user or group. This class cannot be inherited. - [!NOTE] > This type is only supported on Windows. - The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system semaphores. For an overview of these classes, and their relationship to the underlying Windows access control structures, see . - + The class is one of a set of classes that the .NET Framework provides for managing Windows access control security on named system semaphores. For an overview of these classes, and their relationship to the underlying Windows access control structures, see . + > [!NOTE] -> Windows access control security is meaningful only for named system semaphores. If a object represents a local semaphore, access control is irrelevant. - - To get a list of the rules currently applied to a named semaphore, use the method to get a object, then use its method to obtain a collection of objects. - - objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for a semaphore, the set contains the minimum number of rules currently required to express all the access control entries. - +> Windows access control security is meaningful only for named system semaphores. If a object represents a local semaphore, access control is irrelevant. + + To get a list of the rules currently applied to a named semaphore, use the method to get a object, then use its method to obtain a collection of objects. + + objects do not map one-to-one with access control entries in the underlying discretionary access control list (DACL). When you get the set of all access rules for a semaphore, the set contains the minimum number of rules currently required to express all the access control entries. + > [!NOTE] -> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. - - Use objects to specify access rights to allow or deny to a user or group. A object always represents either allowed access or denied access, never both. - - To apply a rule to a named system semaphore, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. - +> The underlying access control entries change as you apply and remove rules. The information in rules is merged if possible, to maintain the smallest number of access control entries. Thus, when you read the current list of rules, it might not look exactly like the list of all the rules you have added. + + Use objects to specify access rights to allow or deny to a user or group. A object always represents either allowed access or denied access, never both. + + To apply a rule to a named system semaphore, use the method to get the object. Modify the object by using its methods to add the rule, and then use the method to reattach the security object. + > [!IMPORTANT] -> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. - +> Changes you make to a object do not affect the access levels of the named semaphore until you call the method to assign the altered security object to the named semaphore. + objects are immutable. Security for a semaphore is modified using the methods of the class to add or remove rules; as you do this, the underlying access control entries are modified. - -## Examples - The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + +## Examples + The following code example demonstrates the separation between rules and rules, and shows the combination of rights in compatible rules. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . - +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> @@ -144,24 +144,24 @@ One of the values specifying whether the rights are allowed or denied. Initializes a new instance of the class, specifying the user or group the rule applies to, the access rights, and whether the specified access rights are allowed or denied. - , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. - + , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. + ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. - is . - - -or- - + is . + + -or- + is zero. is neither of type nor of a type such as that can be converted to type . @@ -205,43 +205,43 @@ One of the values specifying whether the rights are allowed or denied. Initializes a new instance of the class, specifying the name of the user or group the rule applies to, the access rights, and whether the specified access rights are allowed or denied. - , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. - - This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. - - - -## Examples - The following code example demonstrates the use of this constructor to create objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + , for example by calling the method, a user must have access. To exit the semaphore, by calling the method, the user must have access. + + This constructor is equivalent to creating an object, by passing `identity` to the constructor, and passing the newly created object to the constructor. + + + +## Examples + The following code example demonstrates the use of this constructor to create objects. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . - +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> - specifies an invalid value. - - -or- - + specifies an invalid value. + + -or- + specifies an invalid value. is zero. - is . - - -or- - - is a zero-length string. - - -or- - + is . + + -or- + + is a zero-length string. + + -or- + is longer than 512 characters. @@ -279,22 +279,22 @@ Gets the rights allowed or denied by the access rule. A bitwise combination of values indicating the rights allowed or denied by the access rule. - objects are immutable. You can create a new access rule representing a different user, different rights, or a different , but you cannot modify an existing access rule. - - - -## Examples - The following code example demonstrates the use of the property to display the rights in the set of rules contained in a object. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. - + objects are immutable. You can create a new access rule representing a different user, different rights, or a different , but you cannot modify an existing access rule. + + + +## Examples + The following code example demonstrates the use of the property to display the rights in the set of rules contained in a object. The example creates a object, adds rules that allow and deny various rights for the current user, and displays the resulting pair of rules. The example then allows new rights for the current user and displays the result, showing that the new rights are merged with the existing rule. + > [!NOTE] -> This example does not attach the security object to a object. Examples that attach security objects can be found in and . - +> This example does not attach the security object to a object. Examples that attach security objects can be found in and . + :::code language="csharp" source="~/snippets/csharp/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.AccessControl/SemaphoreAccessRule/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.AccessControl/SemaphoreSecurity.xml b/xml/System.Security.AccessControl/SemaphoreSecurity.xml index f818f1eb921..784c7ada876 100644 --- a/xml/System.Security.AccessControl/SemaphoreSecurity.xml +++ b/xml/System.Security.AccessControl/SemaphoreSecurity.xml @@ -242,7 +242,7 @@ class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent access rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct enumeration type to use with each security object. ]]> @@ -355,7 +355,7 @@ class override the property and return the type they use to represent access rules. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct access rule type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent access rules. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct access rule type to use with each security object. ]]> @@ -573,7 +573,7 @@ class override the property and return the type they use to represent audit rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct audit rule type to use with each security object. + Classes that derive from the class override the property and return the type they use to represent audit rights. When you work with arrays or collections that contain multiple types of security objects, use this property to determine the correct audit rule type to use with each security object. ]]> diff --git a/xml/System.Security.Authentication.ExtendedProtection.Configuration/ExtendedProtectionPolicyElement.xml b/xml/System.Security.Authentication.ExtendedProtection.Configuration/ExtendedProtectionPolicyElement.xml index 430459a7d80..d1fd044909f 100644 --- a/xml/System.Security.Authentication.ExtendedProtection.Configuration/ExtendedProtectionPolicyElement.xml +++ b/xml/System.Security.Authentication.ExtendedProtection.Configuration/ExtendedProtectionPolicyElement.xml @@ -17,11 +17,11 @@ The class represents a configuration element for an . - can be configured for server applications using standard configuration files. - + can be configured for server applications using standard configuration files. + ]]> @@ -42,13 +42,13 @@ Initializes a new instance of the class. - class, the property is set to , the property is set to , and the property is set to `null`. - - The properties on the class instance should be set to appropriate values for the application before calling the method. - + class, the property is set to , the property is set to , and the property is set to `null`. + + The properties on the class instance should be set to appropriate values for the application before calling the method. + ]]> @@ -74,11 +74,11 @@ The method builds a new instance based on the properties set on the class. A new instance that represents the extended protection policy created. - class instance must be set before calling the method. - + class instance must be set before calling the method. + ]]> @@ -137,11 +137,11 @@ Gets or sets the policy enforcement value for this configuration policy element. One of the enumeration values that indicates when the extended protection policy should be enforced. - value. - + value. + ]]> diff --git a/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElement.xml b/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElement.xml index f44fc604a28..960b2bb16a6 100644 --- a/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElement.xml +++ b/xml/System.Security.Authentication.ExtendedProtection.Configuration/ServiceNameElement.xml @@ -35,13 +35,13 @@ Initializes a new instance of the class. - class, the property is set to `null`. - - The property should be set to an appropriate value for the application before calling the method to add the instance to the class. - + class, the property is set to `null`. + + The property should be set to an appropriate value for the application before calling the method to add the instance to the class. + ]]> diff --git a/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml b/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml index b1f411cb080..e0bc09e4e6b 100644 --- a/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml +++ b/xml/System.Security.Authentication.ExtendedProtection/ExtendedProtectionPolicy.xml @@ -70,11 +70,11 @@ The class represents the extended protection policy used by the server to validate incoming client connections. - class should not allow the setting of null policies, should supply a default policy, or should require an explicit policy to be created and set by the application developer or administrator. - + class should not allow the setting of null policies, should supply a default policy, or should require an explicit policy to be created and set by the application developer or administrator. + ]]> Integrated Windows Authentication with Extended Protection @@ -130,11 +130,11 @@ A value that indicates when the extended protection policy should be enforced. Initializes a new instance of the class that specifies when the extended protection policy should be enforced. - class, the property is set to the `policyEnforcement` parameter and the property is set to . - + class, the property is set to the `policyEnforcement` parameter and the property is set to . + ]]> Integrated Windows Authentication with Extended Protection @@ -190,13 +190,13 @@ A that contains the source of the serialized stream that is associated with the new instance. Initializes a new instance of the class from a object that contains the required data to populate the . - interface for the class. - - The method can be used to serialize an object. This serialized object can then be used with to construct a new object. - + interface for the class. + + The method can be used to serialize an object. This serialized object can then be used with to construct a new object. + ]]> @@ -245,11 +245,11 @@ A that contains a custom channel binding to use for validation. Initializes a new instance of the class that specifies when the extended protection policy should be enforced and the channel binding token (CBT) to be used. - class, the property is set to the `policyEnforcement` parameter, the property is set to the `customChannelBinding` parameter, and the property is set to . - + class, the property is set to the `policyEnforcement` parameter, the property is set to the `customChannelBinding` parameter, and the property is set to . + ]]> @@ -303,11 +303,11 @@ A that contains the custom SPN list that is used to match against a client's SPN. Initializes a new instance of the class that specifies when the extended protection policy should be enforced, the kind of protection enforced by the policy, and a custom Service Provider Name (SPN) list that is used to match against a client's SPN. - class, the property is set to the `policyEnforcement` parameter, the property is set to the `protectionScenario` parameter, and the property is set to the `customServiceNames` parameter. - + class, the property is set to the `policyEnforcement` parameter, the property is set to the `protectionScenario` parameter, and the property is set to the `customServiceNames` parameter. + ]]> @@ -362,11 +362,11 @@ A that contains the custom SPN list that is used to match against a client's SPN. Initializes a new instance of the class that specifies when the extended protection policy should be enforced, the kind of protection enforced by the policy, and a custom Service Provider Name (SPN) list that is used to match against a client's SPN. - class, the property is set to the `policyEnforcement` parameter, the property is set to the `protectionScenario` parameter, and the property is set to the `customServiceNames` parameter. - + class, the property is set to the `policyEnforcement` parameter, the property is set to the `protectionScenario` parameter, and the property is set to the `customServiceNames` parameter. + ]]> @@ -423,11 +423,11 @@ Gets a custom channel binding token (CBT) to use for validation. A that contains a custom channel binding to use for validation. - and . - + and . + ]]> Integrated Windows Authentication with Extended Protection @@ -480,11 +480,11 @@ Gets the custom Service Provider Name (SPN) list used to match against a client's SPN. A that contains the custom SPN list that is used to match against a client's SPN. - Integrated Windows Authentication with Extended Protection @@ -530,11 +530,11 @@ if the operating system supports integrated windows authentication with extended protection, otherwise . - Integrated Windows Authentication with Extended Protection @@ -586,11 +586,11 @@ Gets when the extended protection policy should be enforced. A value that indicates when the extended protection policy should be enforced. - Integrated Windows Authentication with Extended Protection @@ -642,11 +642,11 @@ Gets the kind of protection enforced by the extended protection policy. A value that indicates the kind of protection enforced by the policy. - Integrated Windows Authentication with Extended Protection @@ -699,11 +699,11 @@ A that contains the destination of the serialized stream that is associated with the new . Populates a object with the required data to serialize an object. - method can be used to serialize an object. This serialized object can then be used with to construct a new object. - + method can be used to serialize an object. This serialized object can then be used with to construct a new object. + ]]> Integrated Windows Authentication with Extended Protection diff --git a/xml/System.Security.Authentication/AuthenticationException.xml b/xml/System.Security.Authentication/AuthenticationException.xml index 42d98201e1b..ec382c2772f 100644 --- a/xml/System.Security.Authentication/AuthenticationException.xml +++ b/xml/System.Security.Authentication/AuthenticationException.xml @@ -63,16 +63,16 @@ The exception that is thrown when authentication fails for an authentication stream. - and classes throw this exception when the client or server cannot be authenticated. When this exception is thrown, you can retry the authentication with different credentials. If you cannot retry the authentication, a is thrown instead of the . - - - -## Examples - | - + and classes throw this exception when the client or server cannot be authenticated. When this exception is thrown, you can retry the authentication with different credentials. If you cannot retry the authentication, a is thrown instead of the . + + + +## Examples + | + ]]> @@ -129,11 +129,11 @@ Initializes a new instance of the class with no message. - @@ -185,11 +185,11 @@ A that describes the authentication failure. Initializes a new instance of the class with the specified message. - property with the text in the `message` parameter. The property is set to `null`. - + property with the text in the `message` parameter. The property is set to `null`. + ]]> @@ -305,11 +305,11 @@ The that is the cause of the current exception. Initializes a new instance of the class with the specified message and inner exception. - property with the text in the `message` parameter and initializes the property with the `innerException` parameter value. - + property with the text in the `message` parameter and initializes the property with the `innerException` parameter value. + ]]> diff --git a/xml/System.Security.Authentication/ExchangeAlgorithmType.xml b/xml/System.Security.Authentication/ExchangeAlgorithmType.xml index b5da51d00d9..7af105dbe56 100644 --- a/xml/System.Security.Authentication/ExchangeAlgorithmType.xml +++ b/xml/System.Security.Authentication/ExchangeAlgorithmType.xml @@ -54,7 +54,7 @@ property. + This enumeration specifies valid values for the property. ## Examples The following example displays the properties of an . diff --git a/xml/System.Security.Authentication/HashAlgorithmType.xml b/xml/System.Security.Authentication/HashAlgorithmType.xml index 6c4066bbe4d..44fd3808630 100644 --- a/xml/System.Security.Authentication/HashAlgorithmType.xml +++ b/xml/System.Security.Authentication/HashAlgorithmType.xml @@ -54,7 +54,7 @@ property. + This enumeration specifies valid values for the property. ## Examples The following example displays the properties of an after authentication has succeeded. diff --git a/xml/System.Security.Authentication/InvalidCredentialException.xml b/xml/System.Security.Authentication/InvalidCredentialException.xml index c0c58a6913d..75592ac6996 100644 --- a/xml/System.Security.Authentication/InvalidCredentialException.xml +++ b/xml/System.Security.Authentication/InvalidCredentialException.xml @@ -57,11 +57,11 @@ The exception that is thrown when authentication fails for an authentication stream and cannot be retried. - class throws this exception when authentication fails. This exception indicates that the underlying stream isn't in a valid state and that you can't retry the authentication using the instance. If you retry the authentication, an is thrown instead of the . - + class throws this exception when authentication fails. This exception indicates that the underlying stream isn't in a valid state and that you can't retry the authentication using the instance. If you retry the authentication, an is thrown instead of the . + ]]> @@ -118,11 +118,11 @@ Initializes a new instance of the class with no message. - @@ -174,11 +174,11 @@ A that describes the authentication failure. Initializes a new instance of the class with the specified message. - property with the text in the `message` parameter. The property is set to `null`. - + property with the text in the `message` parameter. The property is set to `null`. + ]]> @@ -296,11 +296,11 @@ The that is the cause of the current exception. Initializes a new instance of the class with the specified message and inner exception. - property with the text in the `message` parameter and initializes the property with the `innerException` parameter value. - + property with the text in the `message` parameter and initializes the property with the `innerException` parameter value. + ]]> diff --git a/xml/System.Security.Claims/AuthorizationContext.xml b/xml/System.Security.Claims/AuthorizationContext.xml index 291f8d509ec..5105bcce35e 100644 --- a/xml/System.Security.Claims/AuthorizationContext.xml +++ b/xml/System.Security.Claims/AuthorizationContext.xml @@ -21,7 +21,7 @@ ## Remarks The class represents the context that is used by a claims authorization manager, an implementation of the class, to determine whether a principal (subject) should be authorized to perform a specified action on a given resource. The claims authorization manager evaluates the authorization context in the method and either denies or grants access based on the claims presented by the principal. - The property contains the principal for which authorization is being requested, the property contains the resource on which the principal is being authorized, and the property contains the actions that the principal intends to perform on the resource. Both the resource and the action are represented as a collection of claims; however, in most cases, each collection contains a single claim. + The property contains the principal for which authorization is being requested, the property contains the resource on which the principal is being authorized, and the property contains the actions that the principal intends to perform on the resource. Both the resource and the action are represented as a collection of claims; however, in most cases, each collection contains a single claim. @@ -139,7 +139,7 @@ property is initialized to contain a name claim () that has the value specified by the `action` parameter. The property is initialized to contain a name claim that has the value specified by the `resource` parameter. + The property is initialized to contain a name claim () that has the value specified by the `action` parameter. The property is initialized to contain a name claim that has the value specified by the `resource` parameter. ]]> diff --git a/xml/System.Security.Claims/Claim.xml b/xml/System.Security.Claims/Claim.xml index 9eaef837394..39a5f2e9d56 100644 --- a/xml/System.Security.Claims/Claim.xml +++ b/xml/System.Security.Claims/Claim.xml @@ -66,17 +66,17 @@ The following describes important properties of the class: -- The property is a string (typically a URI) that contains the semantic information about the claim; it tells you what the value of the claim means. For example, a claim with a claim type of (`"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`) represents a user's first name. The value of the property can be one of the well-known claim types defined in the class, or it can be an arbitrary URI as defined by the issuer. For example, a claim type of "urn:spendinglimit" might represent a user attribute that makes sense within the business context of the issuer. +- The property is a string (typically a URI) that contains the semantic information about the claim; it tells you what the value of the claim means. For example, a claim with a claim type of (`"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`) represents a user's first name. The value of the property can be one of the well-known claim types defined in the class, or it can be an arbitrary URI as defined by the issuer. For example, a claim type of "urn:spendinglimit" might represent a user attribute that makes sense within the business context of the issuer. -- The property contains the value of the claim. In order to reduce dependencies and simplify administration, in WIF the value of a claim is represented only as a string. For more complex value types, it is recommended that you use standard XML schema types to indicate how the value is meant to be serialized into and deserialized from a string. +- The property contains the value of the claim. In order to reduce dependencies and simplify administration, in WIF the value of a claim is represented only as a string. For more complex value types, it is recommended that you use standard XML schema types to indicate how the value is meant to be serialized into and deserialized from a string. -- The property contains a string that identifies the type information for the value. This property should be used to understand the format of the value and to provide information about how to deserialize it. If your solution requires complex value types, it is recommended that you use standard XML schema types in the property to indicate how the property is meant to be serialized into and deserialized from a string. +- The property contains a string that identifies the type information for the value. This property should be used to understand the format of the value and to provide information about how to deserialize it. If your solution requires complex value types, it is recommended that you use standard XML schema types in the property to indicate how the property is meant to be serialized into and deserialized from a string. -- The property is a object that represents the subject of the claim. The subject of the claim is the entity (typically the user who is requesting access to a resource) about which the claim is asserted. The contains, among its properties, a collection of claims that describe the properties and attributes of the subject as attested to by one or more issuers. +- The property is a object that represents the subject of the claim. The subject of the claim is the entity (typically the user who is requesting access to a resource) about which the claim is asserted. The contains, among its properties, a collection of claims that describe the properties and attributes of the subject as attested to by one or more issuers. -- The property contains the name of the entity that issued the claim. The issuer of a claim is represented in WIF by a string that contains a name taken from a list of well-known issuers that is maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name to the cryptographic material needed to verify the signatures of tokens produced by the corresponding issuer. For example, the class, available out of the box with .NET 4.5, associates the mnemonic name for each issuer with its corresponding X.509 certificate. The list of well-known issuers is typically built at startup time by the issuer name registry. The list used by the is specified in the application configuration file. +- The property contains the name of the entity that issued the claim. The issuer of a claim is represented in WIF by a string that contains a name taken from a list of well-known issuers that is maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name to the cryptographic material needed to verify the signatures of tokens produced by the corresponding issuer. For example, the class, available out of the box with .NET 4.5, associates the mnemonic name for each issuer with its corresponding X.509 certificate. The list of well-known issuers is typically built at startup time by the issuer name registry. The list used by the is specified in the application configuration file. -- The property contains the name of the entity that originally issued the claim. This property is designed to facilitate scenarios where a claim may pass through multiple issuers before it is presented by the client to the RP application; such as federation scenarios. You can examine the property to determine the entity that originally issued the claim. The name is taken from the list of well-known issuers maintained by the issuer name registry, as in the case of the property. +- The property contains the name of the entity that originally issued the claim. This property is designed to facilitate scenarios where a claim may pass through multiple issuers before it is presented by the client to the RP application; such as federation scenarios. You can examine the property to determine the entity that originally issued the claim. The name is taken from the list of well-known issuers maintained by the issuer name registry, as in the case of the property. @@ -373,7 +373,7 @@ if (null != principal) property is set to `null`. The and properties are set to . The property is set to + The property is set to `null`. The and properties are set to . The property is set to ]]> @@ -438,7 +438,7 @@ if (null != principal) property is set to `null`. The and properties are set to . + The property is set to `null`. The and properties are set to . ]]> @@ -512,7 +512,7 @@ if (null != principal) property is set to `null`. The property is set according to the value of the `issuer` parameter. + The property is set to `null`. The property is set according to the value of the `issuer` parameter. ]]> @@ -588,7 +588,7 @@ if (null != principal) property is set to `null`. + The property is set to `null`. ]]> @@ -724,7 +724,7 @@ if (null != principal) property of the new object is set to `null`. + This is a shallow copy operation. The property of the new object is set to `null`. ]]> @@ -785,7 +785,7 @@ if (null != principal) property of the new object is set to the value of the `identity` parameter. + This is a shallow copy operation. The property of the new object is set to the value of the `identity` parameter. ]]> @@ -841,7 +841,7 @@ if (null != principal) property is typically set when calling . + The property is typically set when calling . ]]> @@ -890,7 +890,7 @@ if (null != principal) property is a name that is taken from a list of well-known issuers maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name (the issuer name) with the cryptographic material that is needed to verify signatures of tokens produced by the issuer; for example, an X.509 certificate. + The value of the property is a name that is taken from a list of well-known issuers maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name (the issuer name) with the cryptographic material that is needed to verify signatures of tokens produced by the issuer; for example, an X.509 certificate. ]]> @@ -943,9 +943,9 @@ if (null != principal) ## Remarks Contains the name of the entity that originally issued the claim. This property is designed to facilitate scenarios where a claim may pass through multiple issuers before it is presented by the client to the RP application; such as federation scenarios. - The value of the property is a name that is taken from a list of well-known issuers maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name (the issuer name) with the cryptographic material that is needed to verify signatures of tokens produced by the issuer; for example, an X.509 certificate. + The value of the property is a name that is taken from a list of well-known issuers maintained by the issuer name registry. The issuer name registry is an instance of a class that derives from the class. The issuer name registry associates a mnemonic name (the issuer name) with the cryptographic material that is needed to verify signatures of tokens produced by the issuer; for example, an X.509 certificate. - Except for delegation and federation scenarios, the property and the property will usually have the same value. If the value of the property differs from the value of the property, the claim was first issued by the original issuer and was subsequently re-issued by the issuer. + Except for delegation and federation scenarios, the property and the property will usually have the same value. If the value of the property differs from the value of the property, the claim was first issued by the original issuer and was subsequently re-issued by the issuer. ]]> @@ -996,7 +996,7 @@ if (null != principal) property provides a dictionary of name-value pairs that allows metadata or other information about the claim to be associated with it. For claims generated from SAML tokens, this dictionary may contain keys given by the constants in the class. + The property provides a dictionary of name-value pairs that allows metadata or other information about the claim to be associated with it. For claims generated from SAML tokens, this dictionary may contain keys given by the constants in the class. ]]> @@ -1152,7 +1152,7 @@ if (null != principal) property provides the semantic content of the claim, that is, it states what the claim is about. For example, a claim with a claim type of (`"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`) represents a user's first name. The claim type is typically a URI; however, you are not limited to any specific format other than that it must be representable as a string. The only general requirement is that the claim issuer and the claim consumer must agree about the meaning of the claim. Constants for the well-known claim types used by Windows Identity Foundation (WIF) are available through the class. The claim value is provided by the property. + The property provides the semantic content of the claim, that is, it states what the claim is about. For example, a claim with a claim type of (`"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"`) represents a user's first name. The claim type is typically a URI; however, you are not limited to any specific format other than that it must be representable as a string. The only general requirement is that the claim issuer and the claim consumer must agree about the meaning of the claim. Constants for the well-known claim types used by Windows Identity Foundation (WIF) are available through the class. The claim value is provided by the property. ]]> @@ -1203,7 +1203,7 @@ if (null != principal) ## Remarks The value of a claim is represented only as a string. For more complex value types, it is recommended that you use standard XML schema types to indicate how the value is meant to be serialized and deserialized to and from a string. - The property provides the underlying syntactic type information about the value. The property provides the semantic information about the value; that is, it provides the meaning of the value and tells a claim consumer how to interpret it. + The property provides the underlying syntactic type information about the value. The property provides the semantic information about the value; that is, it provides the meaning of the value and tells a claim consumer how to interpret it. ]]> @@ -1254,7 +1254,7 @@ if (null != principal) property contains a string that identifies the type information of the value. This property can be used to understand the format of the value and to provide information about how to serialize and deserialize the value. If your solution requires complex value types, it is recommended that you use standard XML schema types in the property to indicate how the property is meant to be serialized and deserialized from a string. + The property contains a string that identifies the type information of the value. This property can be used to understand the format of the value and to provide information about how to serialize and deserialize the value. If your solution requires complex value types, it is recommended that you use standard XML schema types in the property to indicate how the property is meant to be serialized and deserialized from a string. ]]> diff --git a/xml/System.Security.Claims/ClaimsAuthorizationManager.xml b/xml/System.Security.Claims/ClaimsAuthorizationManager.xml index 74ef699a7e1..92b218f7617 100644 --- a/xml/System.Security.Claims/ClaimsAuthorizationManager.xml +++ b/xml/System.Security.Claims/ClaimsAuthorizationManager.xml @@ -34,7 +34,7 @@ The use of a claims authorization manager is optional. You can configure your application to use a claims authorization manager either programmatically by using the class or declaratively, by specifying the [<claimsAuthorizationManager>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/claimsauthorizationmanager) element, which is a child element of the [<identityConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration) element in your application configuration file. If your application is a web site or a web application hosted in Internet Information Services (IIS), you must also add the in the ASP.NET HTTP Modules collection. > [!IMPORTANT] -> When you use the class or the class, the claims authorization manager that is used to perform the access check is the one that is specified in the identity configuration under the property. In a configuration file, it is the `` section that is referenced from the default `` element. This is true even for Windows Communication Foundation (WCF) services and desktop applications. +> When you use the class or the class, the claims authorization manager that is used to perform the access check is the one that is specified in the identity configuration under the property. In a configuration file, it is the `` section that is referenced from the default `` element. This is true even for Windows Communication Foundation (WCF) services and desktop applications. The base class does not take any additional configuration; however, you can override the in derived classes to provide initialization of your claims authorization manager from child elements of the ``. The typical scenario is to use these child elements to specify authorization policies which determine which claim types and values are required in order to gain access to which resource. This is not a hard requirement, though you are free to define whatever usage and syntax make sense for your implementation. diff --git a/xml/System.Security.Claims/ClaimsIdentity.xml b/xml/System.Security.Claims/ClaimsIdentity.xml index 9cf197def06..7ccc5218e47 100644 --- a/xml/System.Security.Claims/ClaimsIdentity.xml +++ b/xml/System.Security.Claims/ClaimsIdentity.xml @@ -70,15 +70,15 @@ ## Remarks The class is a concrete implementation of a claims-based identity; that is, an identity described by a collection of claims. A claim is a statement about an entity made by an issuer that describes a property, right, or some other quality of that entity. Such an entity is said to be the subject of the claim. A claim is represented by the class. The claims contained in a describe the entity that the corresponding identity represents, and can be used to make authorization and authentication decisions. A claims-based access model has many advantages over more traditional access models that rely exclusively on roles. For example, claims can provide much richer information about the identity they represent and can be evaluated for authorization or authentication in a far more specific manner. - Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity have been fully integrated into the .NET Framework. This means that many classes that represent an identity in the .NET Framework now derive from and describe their properties through a collection of claims. This is different from previous versions of the .NET Framework, in which, these classes implemented the interface directly. The collection of claims that describe the identity can be accessed through the property. The class provides several methods for finding and modifying claims and fully supports language integrated queries (LINQ). In application code, objects are typically accessed through objects; for example, the principal returned by . + Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity have been fully integrated into the .NET Framework. This means that many classes that represent an identity in the .NET Framework now derive from and describe their properties through a collection of claims. This is different from previous versions of the .NET Framework, in which, these classes implemented the interface directly. The collection of claims that describe the identity can be accessed through the property. The class provides several methods for finding and modifying claims and fully supports language integrated queries (LINQ). In application code, objects are typically accessed through objects; for example, the principal returned by . > [!NOTE] -> The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. +> The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. > [!IMPORTANT] > To add or remove claims from the collection, a caller must have full trust. - In the claims-based model, the property and the method are implemented by evaluating the claims contained by an identity. The base implementations in the claims-based model are provided by the property and the method. The and properties enable you to specify a claim type that should be used to evaluate the claims contained by the identity when performing these operations. + In the claims-based model, the property and the method are implemented by evaluating the claims contained by an identity. The base implementations in the claims-based model are provided by the property and the method. The and properties enable you to specify a claim type that should be used to evaluate the claims contained by the identity when performing these operations. Delegation scenarios are supported through the and properties. @@ -148,9 +148,9 @@ ||`null`.| ||`null`.| ||A empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| ||.| ||.| @@ -217,9 +217,9 @@ ||`null`.| ||`null`.| ||Initialized from the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| ||.| ||.| @@ -448,9 +448,9 @@ ||The value of the `identity.AuthenticationType` () property is used.| ||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| ||If `identity` is assignable from , the claims from `identity` are added to the new instance; otherwise, an empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| ||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| ||If `identity` is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| @@ -510,9 +510,9 @@ ||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| ||`null`.| ||An empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| ||.| ||.| @@ -581,9 +581,9 @@ ||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| ||`null`.| ||Initialized from the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| ||.| ||.| @@ -774,9 +774,9 @@ ||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| ||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| ||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| ||If `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| ||If `identity` is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| @@ -840,9 +840,9 @@ ||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| ||`null`.| ||An empty collection.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| ||The value of the `nameType` parameter. If the `nameType` parameter is null or an empty string, the property is set to .| ||The value of the `roleType` parameter. If the `roleType` parameter is null or an empty string, the property is set to .| @@ -915,9 +915,9 @@ ||The value of the `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the property is set to `null`.| ||`null`.| ||Initialized from the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||`null`.| -||**Note:** When accessed, the value of the property is returned based on the and the collection.| +||**Note:** When accessed, the value of the property is returned based on the and the collection.| ||The value of the `nameType` parameter. However, if the `nameType` parameter is `null` or an empty string, the property is set to .| ||The value of the `roleClaimType` parameter. However, if the `roleClaimType` parameter is `null` or an empty string, the property is set to .| @@ -992,9 +992,9 @@ ||The `authenticationType` parameter. If the `authenticationType` parameter is `null` or an empty string, the value of the `identity.AuthenticationType` () property is used.| ||If `identity` is assignable from , the value of the `identity.BootStrapContext` property; otherwise, `null`.| ||Initialized from the `claims` parameter. If `identity` is assignable from , the claims from `identity` are added to the new instance before those specified by the `claims` parameter.| -||**Note:** When accessed, the value of the property is returned based on the value of the property.| +||**Note:** When accessed, the value of the property is returned based on the value of the property.| ||If `identity` is assignable from , the value of the `identity.Label` property; otherwise, `null`.| -||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| +||If `identity` is not assignable from , is not `null`, and has an property that is not `null`; a name claim is added to the new instance using the value of the property. **Note:** When accessed, the value of the property is returned based on the and the collection.| ||The value of the `nameType` parameter. However, if the value of the `nameType` parameter is `null` or an empty string and `identity` is assignable from , the value of the `identity.NameClaimType` property is used; otherwise, is used.| ||The value of the `roleClaimType` parameter. However, if the value of the `roleClaimType` parameter is `null` or an empty string and identity is assignable from , the value of the `identity.RoleClaimType` property is used; otherwise, is used.| @@ -1101,7 +1101,7 @@ property. The token on whose behalf the call is being delegated can be accessed through the property. + An application can access the delegation chain that led to the current call, by recursively examining the property. The token on whose behalf the call is being delegated can be accessed through the property. ]]> @@ -1357,9 +1357,9 @@ ## Remarks The underlying object is an instance of the class. - Set the `saveBootstrapContext` attribute on either the [<identityConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration) or the [<securityTokenHandlerConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/securitytokenhandlerconfiguration) element in a configuration file to specify whether the token used to generate the should be preserved in the property. + Set the `saveBootstrapContext` attribute on either the [<identityConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/identityconfiguration) or the [<securityTokenHandlerConfiguration>](/dotnet/framework/configure-apps/file-schema/windows-identity-foundation/securitytokenhandlerconfiguration) element in a configuration file to specify whether the token used to generate the should be preserved in the property. - If the property is not `null`, applications can access the original token and the claims it produced through the properties and methods of the class. + If the property is not `null`, applications can access the original token and the claims it produced through the properties and methods of the class. ]]> @@ -1424,7 +1424,7 @@ The claims contained in the collection essentially describe the entity that is represented by the . The claims describe the properties and rights possessed by the entity and can be examined by applications to make decisions about authentication and authorization. > [!NOTE] -> The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. +> The class has a property as well. In the majority of cases you should access the user's claims through the collection rather than through the collection. You will need to access the claims of an individual only in the cases where the principal contains more than one and you need to evaluate or modify a specific identity. ]]> @@ -2138,7 +2138,7 @@ The comparison is done in property is not `null` or an empty string. + `true` if the property is not `null` or an empty string. ]]> @@ -2246,7 +2246,7 @@ The comparison is done in property. If no claim is found that matches the name claim type, returns `null`. + Returns the value of the first claim with a type that matches the name claim type set in the property. If no claim is found that matches the name claim type, returns `null`. ]]> @@ -2296,7 +2296,7 @@ The comparison is done in property specifies the claim type () that is used to provide the name for this identity. The name is accessed through the property. + The property specifies the claim type () that is used to provide the name for this identity. The name is accessed through the property. This property is set by the constructor. @@ -2412,7 +2412,7 @@ The comparison is done in ) that is used when evaluating this identity for the method. The method is called to determine whether the current principal is in a specified role. The claims-based model extends this check to use claims presented by the principal. A object can contain one or more objects and each identity object can contain multiple objects. The property specifies the claim type of the claim that should be used to provide the value for the role when evaluating this object. The property is set by the constructor. A common value is . + The role claim type is the claim type () that is used when evaluating this identity for the method. The method is called to determine whether the current principal is in a specified role. The claims-based model extends this check to use claims presented by the principal. A object can contain one or more objects and each identity object can contain multiple objects. The property specifies the claim type of the claim that should be used to provide the value for the role when evaluating this object. The property is set by the constructor. A common value is . ]]> diff --git a/xml/System.Security.Claims/ClaimsPrincipal.xml b/xml/System.Security.Claims/ClaimsPrincipal.xml index 91787c066e0..2568529683b 100644 --- a/xml/System.Security.Claims/ClaimsPrincipal.xml +++ b/xml/System.Security.Claims/ClaimsPrincipal.xml @@ -70,7 +70,7 @@ ## Remarks Beginning with .NET Framework 4.5, Windows Identity Foundation (WIF) and claims-based identity are fully integrated into .NET Framework. This means that many classes that represent a principal in the .NET Framework now derive from rather than simply implementing the interface. In addition to implementing the interface, exposes properties and methods that are useful for working with claims. - exposes a collection of identities, each of which is a . In the common case, this collection, which is accessed through the property, will only have a single element. + exposes a collection of identities, each of which is a . In the common case, this collection, which is accessed through the property, will only have a single element. The introduction of in .NET 4.5 as the principal from which most principal classes derive does not force you to change anything in the way in which you deal with identity. It does, however open up more possibilities and offer more chances to exercise finer access control. For example: @@ -82,14 +82,14 @@ - Inline claims-based code access checks can be performed by configuring your application with a custom claims authorization manager and using either the class to perform imperative access checks or the to perform declarative access checks. Claims-based code access checks are performed inline, outside of the processing pipeline, and so are available to all applications as long as a claims authorization manager is configured. - You can obtain a instance for the principal associated with a request, or the principal under which a thread is executing, in a [relying party (RP) application](/archive/msdn-magazine/2010/august/federated-identity-passive-authentication-for-asp-net-with-wif) by casting the property to . The claims associated with an object are available through its property. The property returns all of the claims contained by the identities associated with the principal. In the uncommon case in which the contains multiple instances, you can use the property or you can access the primary identity by using the property. provides several methods through which these claims may be searched and fully supports Language Integrated Query (LINQ). Identities can be added to the principal by using the or methods. + You can obtain a instance for the principal associated with a request, or the principal under which a thread is executing, in a [relying party (RP) application](/archive/msdn-magazine/2010/august/federated-identity-passive-authentication-for-asp-net-with-wif) by casting the property to . The claims associated with an object are available through its property. The property returns all of the claims contained by the identities associated with the principal. In the uncommon case in which the contains multiple instances, you can use the property or you can access the primary identity by using the property. provides several methods through which these claims may be searched and fully supports Language Integrated Query (LINQ). Identities can be added to the principal by using the or methods. > [!NOTE] > To add identities to the , a caller must have full trust. - By default, WIF prioritizes objects when selecting the primary identity to return through the property. You can modify this behavior by supplying a delegate through the property to perform the selection. The property provides similar functionality for the property. + By default, WIF prioritizes objects when selecting the primary identity to return through the property. You can modify this behavior by supplying a delegate through the property to perform the selection. The property provides similar functionality for the property. - In the claim-based model, whether a principal is in a specified role is determined by the claims presented by its underlying identities. The method essentially examines each identity associated with the principal to determine whether it possesses a claim with the specified role value. The type of the claim (represented by its property) used to determine which claims should be examined during role checks is specified on an identity through its property. Thus, the claims examined during role checks can be of a different type for different identities associated with the principal. + In the claim-based model, whether a principal is in a specified role is determined by the claims presented by its underlying identities. The method essentially examines each identity associated with the principal to determine whether it possesses a claim with the specified role value. The type of the claim (represented by its property) used to determine which claims should be examined during role checks is specified on an identity through its property. Thus, the claims examined during role checks can be of a different type for different identities associated with the principal. ## Examples The following example extracts the claims presented by a user in an HTTP request and writes them to the HTTP response. The current user is read from the as a . The claims are then read from it and then are written to the response. @@ -363,7 +363,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) , all of its identities are added to the collection. If the specified principal is not assignable from , a new is created from the in its property and added to the collection. + If the specified principal is assignable from , all of its identities are added to the collection. If the specified principal is not assignable from , a new is created from the in its property and added to the collection. ]]> @@ -602,9 +602,9 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) objects that is accessible through the Identities property. Each in the collection contains one or more claims. The property returns all of the claims from all of the claims identities in this collection. + A claims principal has a collection of objects that is accessible through the Identities property. Each in the collection contains one or more claims. The property returns all of the claims from all of the claims identities in this collection. - The property can be examined by custom implementations of the class to make authentication decisions or to filter, transform, or enrich an incoming claim set; by custom implementations of the class to enforce authorization policy; or by application code to make authorization decisions or to customize user experience based on the claims present in the collection. + The property can be examined by custom implementations of the class to make authentication decisions or to filter, transform, or enrich an incoming claim set; by custom implementations of the class to enforce authorization policy; or by application code to make authorization decisions or to customize user experience based on the claims present in the collection. ]]> @@ -664,7 +664,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) property. + You can set this property to override the default behavior of the property. ]]> @@ -812,7 +812,7 @@ if (HttpContext.Current.User is ClaimsPrincipal principal) is returned. You can change this behavior by setting the property to specify a delegate to be called to determine the current principal. + By default, is returned. You can change this behavior by setting the property to specify a delegate to be called to determine the current principal. ]]> @@ -1407,7 +1407,7 @@ Each is called. ## Remarks By default, the framework prioritizes identities of type when returning the identity. The first found in the collection is returned. If there is no in the collection, the first identity assignable from is returned. If there is no , `null` is returned. If the collection is empty, an is thrown. - You can change the default behavior by setting the property to specify a delegate to be called to determine the identity. + You can change the default behavior by setting the property to specify a delegate to be called to determine the identity. ]]> @@ -1468,7 +1468,7 @@ Each is called. The method checks whether an identity that this claims principal possesses contains a claim of type where the value of the claim is equal to the value specified by the `role` parameter. > [!NOTE] -> Each has its own definition of the claim type that represents a role. This claim type can be accessed and set through the property. +> Each has its own definition of the claim type that represents a role. This claim type can be accessed and set through the property. ]]> @@ -1528,7 +1528,7 @@ Each is called. property. + You can set this property to override the default behavior of the property. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml b/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml index 69a554093bd..bf498ef4c6c 100644 --- a/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml +++ b/xml/System.Security.Cryptography.Pkcs/CmsSigner.xml @@ -770,9 +770,9 @@ collection retrieved by the property is the signing time attribute. + An example of a signed attribute that might be included in the collection retrieved by the property is the signing time attribute. - A object and a object will be automatically generated and placed in the property for the corresponding signer whenever the property is not empty. + A object and a object will be automatically generated and placed in the property for the corresponding signer whenever the property is not empty. ]]> @@ -856,7 +856,7 @@ collection retrieved by the property is a countersignature. + An example of an unsigned attribute that might be included in the collection retrieved by the property is a countersignature. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml index 3b55ce4ba49..c952cc8bff0 100644 --- a/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml +++ b/xml/System.Security.Cryptography.Pkcs/EnvelopedCms.xml @@ -869,7 +869,7 @@ The following permissions are required to access the decryption key on .NET Fram ## Remarks -This method displays a user interface in which you choose the recipients for whom to encrypt the message. This requires that the current process is running in *user interactive mode*, meaning that the property is `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. +This method displays a user interface in which you choose the recipients for whom to encrypt the message. This requires that the current process is running in *user interactive mode*, meaning that the property is `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. The user interface will only present certificates that are within their validity period and that have Key Encipherment or Key Agreement included in their key usage. @@ -1010,7 +1010,7 @@ The following permissions are required to display the user interface on .NET Fra ## Remarks Although this property is read-only, a modification to the objects in the can be done by using their properties. - The property is not populated as a result of calling the method nor any of the overloaded EnvelopedCms.Encrypt methods. + The property is not populated as a result of calling the method nor any of the overloaded EnvelopedCms.Encrypt methods. The value of this property is replaced with a different collection object during a call to , which then represents the certificates that were read out of the decoded message. diff --git a/xml/System.Security.Cryptography.Pkcs/KeyAgreeRecipientInfo.xml b/xml/System.Security.Cryptography.Pkcs/KeyAgreeRecipientInfo.xml index 483897b7af7..9469fbc2ebb 100644 --- a/xml/System.Security.Cryptography.Pkcs/KeyAgreeRecipientInfo.xml +++ b/xml/System.Security.Cryptography.Pkcs/KeyAgreeRecipientInfo.xml @@ -42,11 +42,11 @@ The class defines key agreement recipient information. Key agreement algorithms typically use the Diffie-Hellman key agreement algorithm, in which the two parties that establish a shared cryptographic key both take part in its generation and, by definition, agree on that key. This is in contrast to key transport algorithms, in which one party generates the key unilaterally and sends, or transports it, to the other party. - property. - + property. + ]]> @@ -375,11 +375,11 @@ The property retrieves the version of the key agreement recipient. This is automatically set for objects in this class, and the value implies that the recipient is taking part in a key agreement algorithm. The version of the object. - object is contained is a PKCS #7 message or a Cryptographic Message Syntax (CMS) message. CMS is a newer superset of PKCS #7. - + object is contained is a PKCS #7 message or a Cryptographic Message Syntax (CMS) message. CMS is a newer superset of PKCS #7. + ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/KeyTransRecipientInfo.xml b/xml/System.Security.Cryptography.Pkcs/KeyTransRecipientInfo.xml index 1d764315329..b49366017ba 100644 --- a/xml/System.Security.Cryptography.Pkcs/KeyTransRecipientInfo.xml +++ b/xml/System.Security.Cryptography.Pkcs/KeyTransRecipientInfo.xml @@ -42,11 +42,11 @@ The class defines key transport recipient information. *Key transport* algorithms typically use the RSA algorithm, in which an originator establishes a shared cryptographic key with a recipient by generating that key and then transporting it to the recipient. This is in contrast to *key agreement* algorithms, in which the two parties that will be using a cryptographic key both take part in its generation, thereby mutually agreeing to that key. - property. - + property. + ]]> @@ -221,11 +221,11 @@ The property retrieves the version of the key transport recipient. The version of the key transport recipient is automatically set for objects in this class, and the value implies that the recipient is taking part in a key transport algorithm. An int value that represents the version of the key transport object. - is contained is a PKCS #7 message or a Cryptographic Message Syntax (CMS) message. CMS is a newer superset of PKCS #7. - + is contained is a PKCS #7 message or a Cryptographic Message Syntax (CMS) message. CMS is a newer superset of PKCS #7. + ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs9AttributeObject.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs9AttributeObject.xml index 54d9bd14a1d..ff79480256d 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs9AttributeObject.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs9AttributeObject.xml @@ -45,7 +45,7 @@ object can be thought of as a strongly typed object because of the addition of the property. + A object can be thought of as a strongly typed object because of the addition of the property. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs9ContentType.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs9ContentType.xml index 941932368ec..8e9c4795998 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs9ContentType.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs9ContentType.xml @@ -42,11 +42,11 @@ The class defines the type of the content of a CMS/PKCS #7 message. - object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. - + object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. + ]]> @@ -157,11 +157,11 @@ The object from which to copy information. Copies information from an object. - object with the specified object. - + object with the specified object. + ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/Pkcs9MessageDigest.xml b/xml/System.Security.Cryptography.Pkcs/Pkcs9MessageDigest.xml index 4a16db8b2be..03119674c71 100644 --- a/xml/System.Security.Cryptography.Pkcs/Pkcs9MessageDigest.xml +++ b/xml/System.Security.Cryptography.Pkcs/Pkcs9MessageDigest.xml @@ -42,11 +42,11 @@ The class defines the message digest of a CMS/PKCS #7 message. - object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. - + object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. + ]]> @@ -121,11 +121,11 @@ The object from which to copy information. Copies information from an object. - object with the specified object. - + object with the specified object. + ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/RecipientInfoCollection.xml b/xml/System.Security.Cryptography.Pkcs/RecipientInfoCollection.xml index 79a2de74343..db125cd6fe0 100644 --- a/xml/System.Security.Cryptography.Pkcs/RecipientInfoCollection.xml +++ b/xml/System.Security.Cryptography.Pkcs/RecipientInfoCollection.xml @@ -49,11 +49,11 @@ The class represents a collection of objects. implements the interface. - property. - + property. + ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml b/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml index 031549cc878..4b0c8cf5629 100644 --- a/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml +++ b/xml/System.Security.Cryptography.Pkcs/SignerInfo.xml @@ -47,7 +47,7 @@ This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. - This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property. + This class does not have a public constructor; therefore, it cannot be publicly instantiated. It is a read-only class accessible from the property. ]]> @@ -150,7 +150,7 @@ ASN1 corrupted data. property, then the certificate will not be returned. + If the signing certificate is not included at signing time by using the property, then the certificate will not be returned. ]]> @@ -379,7 +379,7 @@ ASN1 corrupted data. This implementation of CMS/PKCS #7 supports only one level of countersignature. That is, a signature can be signed, which forms a countersignature, but that countersignature cannot be signed again. -This method displays a user interface in which you choose signers for this message. This requires that the current process is running in *user interactive mode*, meaning that the property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. +This method displays a user interface in which you choose signers for this message. This requires that the current process is running in *user interactive mode*, meaning that the property is set to `true`. A process is normally in user interactive mode unless it is a service process or running inside a Web application. Signers whose certificates meet the following conditions will be displayed in the list: @@ -813,11 +813,11 @@ ASN1 corrupted data. collection retrieved by the property is the signing time attribute. + An example of a signed attribute that might be included in the collection retrieved by the property is the signing time attribute. Signed attributes are signed along with the rest of the message content. This means that a party that successfully verifies the signature can have confidence that the contents of these attributes are authentic and have not been altered. - A object and a object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. + A object and a object will be automatically generated and placed in the property whenever the property for the corresponding signer is not empty. ]]> @@ -919,7 +919,7 @@ ASN1 corrupted data. ## Remarks Unsigned attributes are not signed along with the rest of the message content. Even though a party successfully verifies the signature, the unsigned attributes may have been altered and should not be considered to have authenticity or integrity. - An example of an unsigned attribute that might be included in the collection retrieved by the property is a countersignature. + An example of an unsigned attribute that might be included in the collection retrieved by the property is a countersignature. ]]> diff --git a/xml/System.Security.Cryptography.Pkcs/SignerInfoCollection.xml b/xml/System.Security.Cryptography.Pkcs/SignerInfoCollection.xml index 785a7563e23..89b663af2b4 100644 --- a/xml/System.Security.Cryptography.Pkcs/SignerInfoCollection.xml +++ b/xml/System.Security.Cryptography.Pkcs/SignerInfoCollection.xml @@ -47,11 +47,11 @@ The class represents a collection of objects. implements the interface. - property or the property. - + property or the property. + ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X500DistinguishedName.xml b/xml/System.Security.Cryptography.X509Certificates/X500DistinguishedName.xml index 3b8fce35e6d..43a6bf4b477 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X500DistinguishedName.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X500DistinguishedName.xml @@ -65,7 +65,7 @@ or property, which is the name of the person or entity that the certificate is being issued to. X.500 is an international standard for distributed directory services. The distinguished name uses the following format: + This class is like an extension to the or property, which is the name of the person or entity that the certificate is being issued to. X.500 is an international standard for distributed directory services. The distinguished name uses the following format: [X500:/C=CountryCode/O=Organization/OU=OrganizationUnit/CN=CommonName] diff --git a/xml/System.Security.Cryptography.X509Certificates/X509BasicConstraintsExtension.xml b/xml/System.Security.Cryptography.X509Certificates/X509BasicConstraintsExtension.xml index 4a6ccff18fa..714c8255a11 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509BasicConstraintsExtension.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509BasicConstraintsExtension.xml @@ -71,7 +71,7 @@ ## Examples The following code example demonstrates how to open a user's personal certificate store and display information about each certificate in the store. This example uses the class to display the information. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509BasicConstraintsExtension/Overview/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509BasicConstraintsExtension/Overview/sample.vb" id="Snippet1"::: @@ -492,7 +492,7 @@ property to determine the number of levels allowed. + A certificate issuer can restrict the number of levels in a certificate path. This property indicates whether the certificate has this restriction. If this value is `true`, you can use the property to determine the number of levels allowed. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml index 200cd29bc59..0d2fdfcfc2d 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml @@ -341,7 +341,7 @@ This constructor creates a new object using a handle for the Microsoft Cryptographic API certificate context, `PCCERT_CONTEXT`. > [!IMPORTANT] -> This constructor creates a copy of the certificate context. Do not assume that the context structure you passed to the constructor is valid; it may have been released. You can get a copy of the current `PCCERT_CONTEXT` structure from the property, but it is valid only during the lifetime of the object. +> This constructor creates a copy of the certificate context. Do not assume that the context structure you passed to the constructor is valid; it may have been released. You can get a copy of the current `PCCERT_CONTEXT` structure from the property, but it is valid only during the lifetime of the object. ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml index fe275e80139..98f76634a68 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2.xml @@ -304,7 +304,7 @@ This constructor creates a new object using a handle for the Microsoft Cryptographic API certificate context, `PCCERT_CONTEXT`. Note that the immediate caller of this constructor requires unmanaged code permission. > [!IMPORTANT] -> The constructor creates a copy of the certificate context. Do not assume that the context structure you passed to the constructor is valid; it may have been released. You can get a copy of the current `PCCERT_CONTEXT` structure from the property, but it is valid only during the lifetime of the object. +> The constructor creates a copy of the certificate context. Do not assume that the context structure you passed to the constructor is valid; it may have been released. You can get a copy of the current `PCCERT_CONTEXT` structure from the property, but it is valid only during the lifetime of the object. ]]> @@ -1417,7 +1417,7 @@ If you create an object unless the property is set to `true`. No physical archival activity occurs when the value is set or unset. + In an X.509 store, archived certificates are not included in the returned object unless the property is set to `true`. No physical archival activity occurs when the value is set or unset. @@ -3790,7 +3790,7 @@ The Subject Alternative Name extension or Subject Name could not be decoded. object, which contains the object identifier () representing the public key algorithm, the ASN.1-encoded parameters, and the ASN.1-encoded key value. - You can also obtain the key as an object by referencing the property. This property supports only RSA or DSA keys, so it returns either an or a object that represents the public key. + You can also obtain the key as an object by referencing the property. This property supports only RSA or DSA keys, so it returns either an or a object that represents the public key. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml index 297a7f8ca2a..b5fd8215227 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Collection.xml @@ -83,7 +83,7 @@ ## Examples The following code example opens the current user's personal certificate store, selects only valid certificates, allows the user to select a certificate, and then writes certificate and certificate chain information to the console. The output depends on the certificate the user selects. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/PublicKey/Key/certselect.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/PublicKey/Key/certselect.vb" id="Snippet1"::: @@ -569,7 +569,7 @@ property. That is, this method is an O(`n`) operation, where `n` is . + This method performs a linear search; therefore, the average execution time is proportional to the property. That is, this method is an O(`n`) operation, where `n` is . This method determines equality by calling the method. @@ -1898,7 +1898,7 @@ property already equals the capacity of the list, the capacity is doubled by automatically reallocating the internal array before the new element is inserted. + If the property already equals the capacity of the list, the capacity is doubled by automatically reallocating the internal array before the new element is inserted. If `index` is equal to , `certificate` is added to the end of the collection. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Enumerator.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Enumerator.xml index 765ac10ca60..d45260f7311 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Enumerator.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate2Enumerator.xml @@ -71,15 +71,15 @@ Supports a simple iteration over a object. This class cannot be inherited. - method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - - This class inherits from the interface. For more information about enumerating over a collection, see . - + method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + + This class inherits from the interface. For more information about enumerating over a collection, see . + ]]> @@ -137,11 +137,11 @@ Gets the current element in the object. The current element in the object. - does not move the position of the enumerator. Consecutive calls to the property return the same object until either the or method is called. - + does not move the position of the enumerator. Consecutive calls to the property return the same object until either the or method is called. + ]]> The enumerator is positioned before the first element of the collection or after the last element. @@ -193,11 +193,11 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - topic. - + topic. + ]]> The collection was modified after the enumerator was created. @@ -247,11 +247,11 @@ Sets the enumerator to its initial position, which is before the first element in the object. - or method throws an . - + or method throws an . + ]]> The collection was modified after the enumerator was created. @@ -310,11 +310,11 @@ For a description of this member, see . The current element in the object. - instance is cast to an interface. - + instance is cast to an interface. + ]]> The enumerator is positioned before the first element of the collection or after the last element. @@ -369,11 +369,11 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> The collection was modified after the enumerator was created. @@ -426,11 +426,11 @@ For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> The collection was modified after the enumerator was created. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509CertificateCollection+X509CertificateEnumerator.xml b/xml/System.Security.Cryptography.X509Certificates/X509CertificateCollection+X509CertificateEnumerator.xml index 608dd909c5f..491147736d5 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509CertificateCollection+X509CertificateEnumerator.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509CertificateCollection+X509CertificateEnumerator.xml @@ -67,15 +67,15 @@ Enumerates the objects in an . - method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . - - This class inherits from the interface. For more information about enumerating over a collection, see . - + method also brings the enumerator back to this position. At this position, calling the property throws an exception. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . + + This class inherits from the interface. For more information about enumerating over a collection, see . + ]]> @@ -172,11 +172,11 @@ Gets the current in the . The current in the . - does not move the position of the enumerator. Consecutive calls to the property return the same object until either the or method is called. - + does not move the position of the enumerator. Consecutive calls to the property return the same object until either the or method is called. + ]]> The enumerator is positioned before the first element of the collection or after the last element. @@ -229,11 +229,11 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - topic. - + topic. + ]]> The collection was modified after the enumerator was instantiated. @@ -284,11 +284,11 @@ Sets the enumerator to its initial position, which is before the first element in the collection. - or method throws an . - + or method throws an . + ]]> The collection is modified after the enumerator is instantiated. @@ -341,11 +341,11 @@ For a description of this member, see . The current X.509 certificate object in the object. - instance is cast to an interface. - + instance is cast to an interface. + ]]> The enumerator is positioned before the first element of the collection or after the last element. @@ -401,11 +401,11 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - instance is cast to an interface. - + instance is cast to an interface. + ]]> The collection was modified after the enumerator was instantiated. @@ -459,11 +459,11 @@ For a description of this member, see . - instance is cast to an interface. - + instance is cast to an interface. + ]]> The collection was modified after the enumerator was instantiated. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ChainElement.xml b/xml/System.Security.Cryptography.X509Certificates/X509ChainElement.xml index f5597456905..40ca31b1c84 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ChainElement.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ChainElement.xml @@ -65,7 +65,7 @@ when calling the property. + This object is constructed internally and is returned as part of an when calling the property. ]]> @@ -130,7 +130,7 @@ ## Examples The following code example opens the current user's personal certificate store, allows the user to select a certificate, then writes certificate and certificate chain information to the console. The output depends on the certificate the user selects. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.vb" id="Snippet4"::: diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ChainElementCollection.xml b/xml/System.Security.Cryptography.X509Certificates/X509ChainElementCollection.xml index 84b19748bd6..6703f21ba12 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ChainElementCollection.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ChainElementCollection.xml @@ -80,13 +80,13 @@ property is called. + An instance of this class is returned when the property is called. ## Examples The following code example opens the current user's personal certificate store, allows the user to select a certificate, and then writes certificate and certificate chain information to the console. The output depends on the certificate you select. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.vb" id="Snippet4"::: diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ChainStatus.xml b/xml/System.Security.Cryptography.X509Certificates/X509ChainStatus.xml index b6872022d43..b07e148a438 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ChainStatus.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ChainStatus.xml @@ -65,13 +65,13 @@ property. + This structure is used in conjunction with the property. ## Examples The following example opens the current user's personal certificate store, allows the user to select a certificate, then writes certificate and certificate chain information to the console. The output depends on the certificate you select. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.vb" id="Snippet3"::: diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ChainStatusFlags.xml b/xml/System.Security.Cryptography.X509Certificates/X509ChainStatusFlags.xml index 674bb2bcca2..434e9ceb793 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ChainStatusFlags.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ChainStatusFlags.xml @@ -61,13 +61,13 @@ Defines the status of an X509 chain. - structure and the property. - - The flags ExplicitDistrust, HasNotSupportedCriticalExtension and HasWeakSignature were introduced with the .NET Framework 4.6.1. - + structure and the property. + + The flags ExplicitDistrust, HasNotSupportedCriticalExtension and HasWeakSignature were introduced with the .NET Framework 4.6.1. + ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509EnhancedKeyUsageExtension.xml b/xml/System.Security.Cryptography.X509Certificates/X509EnhancedKeyUsageExtension.xml index 8fab27debd2..46aa153fdc2 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509EnhancedKeyUsageExtension.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509EnhancedKeyUsageExtension.xml @@ -71,7 +71,7 @@ ## Examples The following code example demonstrates how to open a user's personal certificate store and display information about each certificate in the store. This example uses the class to display the information. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509BasicConstraintsExtension/Overview/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/X509BasicConstraintsExtension/Overview/sample.vb" id="Snippet1"::: @@ -133,7 +133,7 @@ class. After the instance has been created, you can then use the property to obtain the collection of object identifiers (OIDs) that indicate the applications that use the key. + Use this method to create a new instance of the class. After the instance has been created, you can then use the property to obtain the collection of object identifiers (OIDs) that indicate the applications that use the key. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml b/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml index dce5e2d6601..2e2c66e56fe 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509ExtensionCollection.xml @@ -77,11 +77,11 @@ Represents a collection of objects. This class cannot be inherited. - objects associated with a certificate. These extensions can provide additional information about the certificate. - + objects associated with a certificate. These extensions can provide additional information about the certificate. + ]]> @@ -176,11 +176,11 @@ Adds an object to an object. The index at which the parameter was added. - method allows duplicate elements to be added to the collection. - + method allows duplicate elements to be added to the collection. + ]]> The value of the parameter is . @@ -337,11 +337,11 @@ Returns an enumerator that can iterate through an object. An object to use to iterate through the object. - @@ -392,11 +392,11 @@ if the collection is thread safe; otherwise, . - interface and is overridden to always return `false`. For more information about this property, see the property of the interface. - + interface and is overridden to always return `false`. For more information about this property, see the property of the interface. + ]]> @@ -460,11 +460,11 @@ Gets the object at the specified index. An object. - object when you know the location of the object in the object. - + object when you know the location of the object in the object. + ]]> @@ -528,11 +528,11 @@ Gets the first object whose value or friendly name is specified by an object identifier (OID). An object. - object when you know the object identifier (OID) of the extension in the object. - + object when you know the object identifier (OID) of the extension in the object. + ]]> @@ -582,13 +582,13 @@ Gets an object that you can use to synchronize access to the object. An object that you can use to synchronize access to the object. - interface. The .NET Framework classes based on provide their own synchronized version of the collection using the property. Classes that use arrays can also implement their own synchronization using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection. Note that some implementations of might return the array itself. - - Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - + interface. The .NET Framework classes based on provide their own synchronized version of the collection using the property. Classes that use arrays can also implement their own synchronization using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection. Note that some implementations of might return the array itself. + + Enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + ]]> @@ -726,7 +726,7 @@ ## Remarks -This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -768,7 +768,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks -This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. +This member is an explicit interface member implementation. It can be used only when the instance is cast to an interface. ]]> @@ -822,11 +822,11 @@ This member is an explicit interface member implementation. It can be used only Returns an enumerator that can iterate through an object. An object to use to iterate through the object. - diff --git a/xml/System.Security.Cryptography.X509Certificates/X509KeyUsageFlags.xml b/xml/System.Security.Cryptography.X509Certificates/X509KeyUsageFlags.xml index ebb0ff2b7d7..3c88f9719f0 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509KeyUsageFlags.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509KeyUsageFlags.xml @@ -61,11 +61,11 @@ Defines how the certificate key can be used. If this value is not defined, the key can be used for any purpose. - file. When the property of the class is invoked, this class can be used directly. - + file. When the property of the class is invoked, this class can be used directly. + ]]> diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Store.xml b/xml/System.Security.Cryptography.X509Certificates/X509Store.xml index 01633fa559e..b89c40bea1f 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Store.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Store.xml @@ -100,7 +100,7 @@ **Example 2** This example opens an X.509 certificate store, adds and deletes certificates, and then closes the store. It assumes that you have three certificates to add to and remove from a local store. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/OpenFlags/Overview/x509store2.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.X509Certificates/OpenFlags/Overview/x509store2.vb" id="Snippet1"::: @@ -1430,7 +1430,7 @@ property to provide compatibility with the unmanaged [Microsoft Cryptographic API (CAPI)](/windows/win32/seccrypto/cryptography-reference). + Use the property to provide compatibility with the unmanaged [Microsoft Cryptographic API (CAPI)](/windows/win32/seccrypto/cryptography-reference). ]]> diff --git a/xml/System.Security.Cryptography.Xml/CipherData.xml b/xml/System.Security.Cryptography.Xml/CipherData.xml index 5defb147d3f..6c55bdf9f99 100644 --- a/xml/System.Security.Cryptography.Xml/CipherData.xml +++ b/xml/System.Security.Cryptography.Xml/CipherData.xml @@ -47,7 +47,7 @@ In many cases, you do not need to directly create a new instance of the class. The , , and classes create instances for you. > [!NOTE] -> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. +> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. @@ -150,7 +150,7 @@ object that represents the `` element in XML encryption. The constructor assigns the `cipherValue` value to the property as the actual encrypted data. + This constructor creates a object that represents the `` element in XML encryption. The constructor assigns the `cipherValue` value to the property as the actual encrypted data. > [!NOTE] > The `` element can have either a or a child element, but not both. A is thrown if both are assigned to a object. @@ -207,7 +207,7 @@ This constructor creates a object that represents the `` element in XML encryption and assigns the `cipherReference` value to the property. The object represents the `` element, which provides the location of the encrypted data. > [!NOTE] -> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. +> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. ## Examples The following code example shows how to create a new instance of the class using information. @@ -261,7 +261,7 @@ The `` element identifies a source that, when processed, yields the encrypted data. For more information about this element, see . > [!NOTE] -> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. +> A object can have either a property or a property, but not both. A is thrown if both are assigned to a object. ## Examples The following code example shows how to create a new instance of the class using information. diff --git a/xml/System.Security.Cryptography.Xml/CipherReference.xml b/xml/System.Security.Cryptography.Xml/CipherReference.xml index 00d4e85ac18..30b04f06967 100644 --- a/xml/System.Security.Cryptography.Xml/CipherReference.xml +++ b/xml/System.Security.Cryptography.Xml/CipherReference.xml @@ -48,7 +48,7 @@ The syntax of the URI and transforms is similar to that of XML digital signatures. However, in XML digital signatures, both generation and validation processing start with the same source data and perform that transform in the same order. In XML encryption, the decrypting application has only the encrypted data and the specified transforms. The transforms are enumerated in the order necessary to obtain the encrypted data. - **Note** By default, you cannot dereference cipher references from documents with unknown sources, such as files from a Web site, because the property is **null**. For example, when you attempt to decrypt a file containing a `` element that references a file on the Web, a is thrown, even if the request is made by a fully trusted assembly. + **Note** By default, you cannot dereference cipher references from documents with unknown sources, such as files from a Web site, because the property is **null**. For example, when you attempt to decrypt a file containing a `` element that references a file on the Web, a is thrown, even if the request is made by a fully trusted assembly. If you are sure the documents you are decrypting can be trusted, you can change this behavior for fully trusted applications by using the following code: diff --git a/xml/System.Security.Cryptography.Xml/DataObject.xml b/xml/System.Security.Cryptography.Xml/DataObject.xml index a4ec5cd1283..774eef0f91f 100644 --- a/xml/System.Security.Cryptography.Xml/DataObject.xml +++ b/xml/System.Security.Cryptography.Xml/DataObject.xml @@ -51,7 +51,7 @@ ## Examples The following code example demonstrates how to generate an enveloping XML signature. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/DataObject/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/DataObject/Overview/source.vb" id="Snippet1"::: @@ -215,7 +215,7 @@ property. + This property is the XML node list that contains the element described in the property. @@ -358,7 +358,7 @@ from another location. The default value of this property is `null`, which implies that no identification is present. This property is commonly referenced by the property. + The identification is used to reference the from another location. The default value of this property is `null`, which implies that no identification is present. This property is commonly referenced by the property. diff --git a/xml/System.Security.Cryptography.Xml/EncryptedKey.xml b/xml/System.Security.Cryptography.Xml/EncryptedKey.xml index d803f86ba7c..0021fcbabab 100644 --- a/xml/System.Security.Cryptography.Xml/EncryptedKey.xml +++ b/xml/System.Security.Cryptography.Xml/EncryptedKey.xml @@ -39,21 +39,21 @@ Represents the element in XML encryption. This class cannot be inherited. - ` element in XML encryption. The `` element is used to send encryption keys. It can be created in a stand-alone XML document, be placed within an application document, or be inside an `` element as a child of a `` element. The key value is always encrypted to the recipient. When `` is decrypted, the resulting key is made available to the `` algorithm without any additional processing. - - The `` element is similar to the `` element of the class except that the data encrypted is always a key value. - - - -## Examples - The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. - + ` element in XML encryption. The `` element is used to send encryption keys. It can be created in a stand-alone XML document, be placed within an application document, or be inside an `` element as a child of a `` element. The key value is always encrypted to the recipient. When `` is decrypted, the resulting key is made available to the `` algorithm without any additional processing. + + The `` element is similar to the `` element of the class except that the data encrypted is always a key value. + + + +## Examples + The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: + ]]> @@ -86,19 +86,19 @@ Initializes a new instance of the class. - class. For more information on XML encryption standards, see the [XML Encryption Syntax and Processing](https://www.w3.org/TR/xmlenc-core/) specification. - - - -## Examples - The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. - + class. For more information on XML encryption standards, see the [XML Encryption Syntax and Processing](https://www.w3.org/TR/xmlenc-core/) specification. + + + +## Examples + The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: + ]]> @@ -147,11 +147,11 @@ A object to add to the property. Adds a element to the element. - object to the property of the object. The `` element points to encrypted data that was encrypted using the key specified in the `` element. - + object to the property of the object. The `` element points to encrypted data that was encrypted using the key specified in the `` element. + ]]> @@ -191,11 +191,11 @@ A object to add to the property. Adds a element to the element. - object to the property of the object. The `` element points to an encrypted key that was encrypted using the key specified in the `` element. - + object to the property of the object. The `` element points to an encrypted key that was encrypted using the key specified in the `` element. + ]]> @@ -239,19 +239,19 @@ Gets or sets the optional element in XML encryption. A string that represents a name for the key value. - ` element is an optional element that associates a user-readable name with a key value. This name can then be used to reference the key using the `` element within the `` element. The same `` element value, unlike an ID value, can occur multiple times within a single document. The value of the key must be the same in all `` elements identified with the same `` name within an XML document. Note that because white space is significant in the value of the `` element, white space is also significant in the value of the `` element. - - - -## Examples - The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. - + ` element is an optional element that associates a user-readable name with a key value. This name can then be used to reference the key using the `` element within the `` element. The same `` element value, unlike an ID value, can occur multiple times within a single document. The value of the key must be the same in all `` elements identified with the same `` name within an XML document. Note that because white space is significant in the value of the `` element, white space is also significant in the value of the `` element. + + + +## Examples + The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: + ]]> @@ -289,11 +289,11 @@ Returns the XML representation of the object. An that represents the element in XML encryption. - ` element in XML. - + ` element in XML. + ]]> The value is . @@ -344,19 +344,19 @@ An representing an XML element to use for the element. Loads the specified XML information into the element in XML encryption. - ` element represented by the object. - - - -## Examples - The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. - + ` element represented by the object. + + + +## Examples + The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: + ]]> The parameter is . @@ -395,19 +395,19 @@ Gets or sets the optional attribute in XML encryption. A string representing the value of the attribute. - ` attribute is an optional attribute that contains information about which recipient this encrypted key value is intended for. Its contents are application dependent. - - - -## Examples - The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. - + ` attribute is an optional attribute that contains information about which recipient this encrypted key value is intended for. Its contents are application dependent. + + + +## Examples + The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: + ]]> @@ -444,19 +444,19 @@ Gets or sets the element in XML encryption. A object. - ` element is an optional element that contains pointers to data and keys encrypted using this key. The reference list can contain multiple references to the `` and `` elements using the `` and `` elements respectively. - - - -## Examples - The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. - + ` element is an optional element that contains pointers to data and keys encrypted using this key. The reference list can contain multiple references to the `` and `` elements using the `` and `` elements respectively. + + + +## Examples + The following example illustrates how to encrypt and decrypt an XML element by using the class. This example then displays the values of various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedKey/Overview/example.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.Cryptography.Xml/EncryptedType.xml b/xml/System.Security.Cryptography.Xml/EncryptedType.xml index 69464b109b9..57e15c2b813 100644 --- a/xml/System.Security.Cryptography.Xml/EncryptedType.xml +++ b/xml/System.Security.Cryptography.Xml/EncryptedType.xml @@ -39,21 +39,21 @@ Represents the abstract base class from which the classes and derive. - class represents the abstract base class from which the classes and derive. These two classes contain the actual encrypted data or key information in XML encryption. To comply with XML encryption standards, you should use these two derived classes. - - For more information on XML encryption standards, see [XML Encryption Syntax and Processing Version 1.1](https://www.w3.org/TR/xmlenc-core/). - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. - + class represents the abstract base class from which the classes and derive. These two classes contain the actual encrypted data or key information in XML encryption. To comply with XML encryption standards, you should use these two derived classes. + + For more information on XML encryption standards, see [XML Encryption Syntax and Processing Version 1.1](https://www.w3.org/TR/xmlenc-core/). + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -86,19 +86,19 @@ Initializes a new instance of the class. - class. This class represents the abstract base class from which the classes and derive. To comply with XML encryption standards, you should use the two derived classes. For more information on XML encryption standards, see [XML Encryption Syntax and Processing Version 1.1](https://www.w3.org/TR/xmlenc-core/). - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. - + class. This class represents the abstract base class from which the classes and derive. To comply with XML encryption standards, you should use the two derived classes. For more information on XML encryption standards, see [XML Encryption Syntax and Processing Version 1.1](https://www.w3.org/TR/xmlenc-core/). + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -138,11 +138,11 @@ An object. Adds an child element to the element in the current object in XML encryption. - ` child elements to the `` element. The `` element provides additional information for the `` element. - + ` child elements to the `` element. The `` element provides additional information for the `` element. + ]]> @@ -185,21 +185,21 @@ Gets or sets the value for an instance of an class. A object. - ` element is a required element in XML encryption that provides the encrypted data. It must either contain the encrypted octet sequence as the base64-encoded text of the property, or provide a reference to an external location containing the encrypted octet sequence using the property. - - For more information about this element, see . - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. - + ` element is a required element in XML encryption that provides the encrypted data. It must either contain the encrypted octet sequence as the base64-encoded text of the property, or provide a reference to an external location containing the encrypted octet sequence using the property. + + For more information about this element, see . + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: + ]]> The property was set to . @@ -238,19 +238,19 @@ Gets or sets the attribute of an instance in XML encryption. A string that describes the encoding of the encrypted data. - '. - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. This sample then displays various properties of the class to the console. - + '. + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. This sample then displays various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -288,19 +288,19 @@ Gets or sets the element for XML encryption. An object that represents the element. - ` is an optional element that describes the encryption algorithm applied to the encrypted data. If the element is absent, the encryption algorithm must be known by the recipient or decryption will fail. - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. - + ` is an optional element that describes the encryption algorithm applied to the encrypted data. If the element is absent, the encryption algorithm must be known by the recipient or decryption will fail. + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -343,19 +343,19 @@ Gets or sets the element in XML encryption. An object. - ` element can contain additional information about the creation of the instance, such as a date and time stamp or the serial number of cryptographic hardware used during encryption. - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. This sample then displays various properties of the class to the console. - + ` element can contain additional information about the creation of the instance, such as a date and time stamp or the serial number of cryptographic hardware used during encryption. + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. This sample then displays various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -393,11 +393,11 @@ Returns the XML representation of the object. An object that represents the element in XML encryption. - ` element in XML. - + ` element in XML. + ]]> @@ -435,19 +435,19 @@ Gets or sets the attribute of an instance in XML encryption. A string of the attribute of the element. - ` element that provides a standard method for assigning a string identifier to an element within an XML document. - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. This sample then displays various properties of the class to the console. - + ` element that provides a standard method for assigning a string identifier to an element within an XML document. + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. This sample then displays various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -490,19 +490,19 @@ Gets of sets the element in XML encryption. A object. - ` element is an optional element that contains information about the key used to encrypt the data. - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. This sample then displays various properties of the class to the console. - + ` element is an optional element that contains information about the key used to encrypt the data. + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. This sample then displays various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -552,19 +552,19 @@ An object representing an XML element to use in the element. Loads XML information into the element in XML encryption. - object. - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. - + object. + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: + ]]> The provided is . @@ -603,19 +603,19 @@ Gets or sets the attribute of an instance in XML encryption. A string that describes the media type of the encrypted data. - ' and the `MimeType` would be 'image/png'. This attribute is optional and no validation of the `MimeType` information is required. The attribute does not indicate that the encryption application must do any additional processing. Note that this information may not be necessary if it is already bound to the identifier in the `Type` attribute. - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. This sample then displays various properties of the class to the console. - + ' and the `MimeType` would be 'image/png'. This attribute is optional and no validation of the `MimeType` information is required. The attribute does not indicate that the encryption application must do any additional processing. Note that this information may not be necessary if it is already bound to the identifier in the `Type` attribute. + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. This sample then displays various properties of the class to the console. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedData/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -653,19 +653,19 @@ Gets or sets the attribute of an instance in XML encryption. A string that describes the text form of the encrypted data. - ` element contains data of type `'element'` or element `'content'`, and replaces that data in an XML document, it is strongly recommended that the `Type` attribute be provided. Without this information, the application attempting to decrypt the information will be unable to automatically restore the XML document to its original text form. - - - -## Examples - The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. - + ` element contains data of type `'element'` or element `'content'`, and replaces that data in an XML document, it is strongly recommended that the `Type` attribute be provided. Without this information, the application attempting to decrypt the information will be unable to automatically restore the XML document to its original text form. + + + +## Examples + The following code example demonstrates how to encrypt and decrypt an XML element using the class that derives from the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedType/Overview/sample.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.Cryptography.Xml/EncryptedXml.xml b/xml/System.Security.Cryptography.Xml/EncryptedXml.xml index 39f6fbc8e5a..5866955f58b 100644 --- a/xml/System.Security.Cryptography.Xml/EncryptedXml.xml +++ b/xml/System.Security.Cryptography.Xml/EncryptedXml.xml @@ -796,7 +796,7 @@ object has any security evidence, you should add the evidence to the property. If you do not set this property, any associated objects will not be dereferenced because they will not be granted the required permission set. + If the XML document used to create the object has any security evidence, you should add the evidence to the property. If you do not set this property, any associated objects will not be dereferenced because they will not be granted the required permission set. ]]> @@ -1633,9 +1633,9 @@ The value of the parameter is not a su object referenced by a key name by examining the property. + You can access the object referenced by a key name by examining the property. - Use the property to identify the element that the current recipient can decrypt to retrieve a decryption key. + Use the property to identify the element that the current recipient can decrypt to retrieve a decryption key. ]]> diff --git a/xml/System.Security.Cryptography.Xml/EncryptionMethod.xml b/xml/System.Security.Cryptography.Xml/EncryptionMethod.xml index fe5cbd9f751..f9fc498b061 100644 --- a/xml/System.Security.Cryptography.Xml/EncryptionMethod.xml +++ b/xml/System.Security.Cryptography.Xml/EncryptionMethod.xml @@ -52,7 +52,7 @@ ## Examples The following code example demonstrates how to create a simple utility class that uses the algorithm to encrypt an XML document. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample.vb" id="Snippet1"::: @@ -246,7 +246,7 @@ property describes the Uniform Resource Identifier (URI) of the encryption algorithm used to encrypt data associated with either the element or the element. + The property describes the Uniform Resource Identifier (URI) of the encryption algorithm used to encrypt data associated with either the element or the element. Use one of the URI identifiers defined by the World Wide Web Consortium [XML Encryption Syntax and Processing](https://www.w3.org/TR/xmlenc-core/) specification. All URI identifiers are accessible as static fields of the class. @@ -289,7 +289,7 @@ property describes the key size of the encryption algorithm used to encrypt data associated with either the element or the element. + The property describes the key size of the encryption algorithm used to encrypt data associated with either the element or the element. ]]> diff --git a/xml/System.Security.Cryptography.Xml/KeyInfoEncryptedKey.xml b/xml/System.Security.Cryptography.Xml/KeyInfoEncryptedKey.xml index fc959ee715c..50ec0d6681a 100644 --- a/xml/System.Security.Cryptography.Xml/KeyInfoEncryptedKey.xml +++ b/xml/System.Security.Cryptography.Xml/KeyInfoEncryptedKey.xml @@ -56,7 +56,7 @@ ## Examples The following code example demonstrates how to encrypt an XML document using an asymmetric key. This example creates a symmetric session key to encrypt the document and then uses the asymmetric key to embed an encrypted version of the session key into the XML document. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/EncryptedXml/Overview/sample1.vb" id="Snippet1"::: @@ -115,7 +115,7 @@ class using an instance of the class. Use the property to specify an object when you use this constructor. + This constructor does not initialize the class using an instance of the class. Use the property to specify an object when you use this constructor. ]]> @@ -207,7 +207,7 @@ class wraps the class, which allows you to add the class as a subelement of the class. Use the property to access the class contained within the class. + The class wraps the class, which allows you to add the class as a subelement of the class. Use the property to access the class contained within the class. ]]> diff --git a/xml/System.Security.Cryptography.Xml/KeyInfoName.xml b/xml/System.Security.Cryptography.Xml/KeyInfoName.xml index 422f10d3722..4e12c4ab0c3 100644 --- a/xml/System.Security.Cryptography.Xml/KeyInfoName.xml +++ b/xml/System.Security.Cryptography.Xml/KeyInfoName.xml @@ -51,7 +51,7 @@ ## 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="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigdetach.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigdetach.vb" id="Snippet1"::: @@ -177,7 +177,7 @@ ## Remarks The `keyName` parameter can contain any string; the interpretation of the string is specific to the application. White space is significant in the string value. - The `keyName` parameter specifies the value of the property. + The `keyName` parameter specifies the value of the property. ]]> @@ -309,7 +309,7 @@ property can contain any string; the interpretation of the string is specific to the application. White space is significant in the string value. + The property can contain any string; the interpretation of the string is specific to the application. White space is significant in the string value. diff --git a/xml/System.Security.Cryptography.Xml/KeyInfoX509Data.xml b/xml/System.Security.Cryptography.Xml/KeyInfoX509Data.xml index f69bcad866f..1317b41cadd 100644 --- a/xml/System.Security.Cryptography.Xml/KeyInfoX509Data.xml +++ b/xml/System.Security.Cryptography.Xml/KeyInfoX509Data.xml @@ -55,7 +55,7 @@ This section contains two code examples. The first example demonstrates how to sign an XML file using a detached signature. The second example demonstrates how to sign an XML file using an envelope signature. **Example #1** - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfoX509Data/Overview/examplecreatedetached.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/KeyInfoX509Data/Overview/examplecreatedetached.vb" id="Snippet1"::: @@ -332,7 +332,7 @@ ## Remarks For identification, each X.509v3 certificate carries the name of the certification authority that issued the certificate paired with a unique serial number assigned by the certification authority. - The method adds information about an issuer name and serial number pair to a list of objects that are accessible through the property. + The method adds information about an issuer name and serial number pair to a list of objects that are accessible through the property. ]]> @@ -641,7 +641,7 @@ property represents the `` element of an XML digital signature using a list of structures contained within. The `` element represents an issuer name and serial number pair, which identify a specific X.509v3 certificate. + The property represents the `` element of an XML digital signature using a list of structures contained within. The `` element represents an issuer name and serial number pair, which identify a specific X.509v3 certificate. The issuer of an X.509 certificate is the name of the certification authority that issued the certificate. Certification authorities assign each certificate they issue a unique serial number. diff --git a/xml/System.Security.Cryptography.Xml/RSAKeyValue.xml b/xml/System.Security.Cryptography.Xml/RSAKeyValue.xml index cb9712c6774..d14a4fbfdc4 100644 --- a/xml/System.Security.Cryptography.Xml/RSAKeyValue.xml +++ b/xml/System.Security.Cryptography.Xml/RSAKeyValue.xml @@ -55,7 +55,7 @@ ## Examples The following code example demonstrates how to generate and verify an enveloped XML signature using the object. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigenv.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigenv.vb" id="Snippet1"::: @@ -243,7 +243,7 @@ Based upon [The RSAKeyValue Element](https://www.w3.org/TR/2002/REC-xmldsig-core property represents the public key to add to an XML digital signature using the `` subelement and the `` subelement of the `` element. + The property represents the public key to add to an XML digital signature using the `` subelement and the `` subelement of the `` element. For more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/). diff --git a/xml/System.Security.Cryptography.Xml/Reference.xml b/xml/System.Security.Cryptography.Xml/Reference.xml index bc12c2f83a3..3827fb1dbe1 100644 --- a/xml/System.Security.Cryptography.Xml/Reference.xml +++ b/xml/System.Security.Cryptography.Xml/Reference.xml @@ -324,7 +324,7 @@ property uses a URI string to represent the `` element of an XML digital signature. + The property uses a URI string to represent the `` element of an XML digital signature. The digest method is the algorithm used to hash the . The default algorithm is . @@ -371,11 +371,11 @@ property uses an array of bytes to represent the `` element of an XML digital signature. + The property uses an array of bytes to represent the `` element of an XML digital signature. - The property contains the Base 64 encoded value of the digest of the object described by the property. + The property contains the Base 64 encoded value of the digest of the object described by the property. - The property is automatically populated with the appropriate value whenever you make a call to . + The property is automatically populated with the appropriate value whenever you make a call to . For more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/). @@ -461,7 +461,7 @@ property to add a string ID to the XML representation of the current element. The ID is used to reference the element from another location. + Use the property to add a string ID to the XML representation of the current element. The ID is used to reference the element from another location. ]]> @@ -571,9 +571,9 @@ property represents the `` element and associated subelements of an XML digital signature. + The property represents the `` element and associated subelements of an XML digital signature. - The transform chain is an ordered list of transforms. The output of these transforms constitutes the input to the hash algorithm specified in the property. + The transform chain is an ordered list of transforms. The output of these transforms constitutes the input to the hash algorithm specified in the property. For more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/). @@ -654,13 +654,13 @@ property uses a string Uniform Resource Identifier (URI) to represent the `` element of an XML digital signature. + The property uses a string Uniform Resource Identifier (URI) to represent the `` element of an XML digital signature. - Use the property to specify the location of a document to sign, and to specify which element of the current XML document to sign or to indicate that the entire document should be signed. + Use the property to specify the location of a document to sign, and to specify which element of the current XML document to sign or to indicate that the entire document should be signed. - To successfully create an XML digital signature, you must set the property. The following table describes the values that you can pass to the property. + To successfully create an XML digital signature, you must set the property. The following table describes the values that you can pass to the property. -|Object to sign|Value passed to the property| +|Object to sign|Value passed to the property| |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |An entire XML document using an enveloped signature.|An empty string: ""| |A specific element within an XML document using an enveloped signature.|The name of an XML element identified by an attribute name ID. The string should take the following form where `IDname` is the name of a valid attribute name ID:

"#Idname"| diff --git a/xml/System.Security.Cryptography.Xml/Signature.xml b/xml/System.Security.Cryptography.Xml/Signature.xml index 176574ada0c..12f51d0d46a 100644 --- a/xml/System.Security.Cryptography.Xml/Signature.xml +++ b/xml/System.Security.Cryptography.Xml/Signature.xml @@ -51,7 +51,7 @@ ## Examples The following code example uses the class with the class to sign and verify an XML document using an envelope signature. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/Reference/.ctor/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/Reference/.ctor/sample.vb" id="Snippet1"::: @@ -151,7 +151,7 @@ method adds a object to a collection that is accessible using the property. + The method adds a object to a collection that is accessible using the property. ]]> @@ -243,7 +243,7 @@ property to add a string ID to the XML representation of the current element. The ID is used to reference the from another location. + Use the property to add a string ID to the XML representation of the current element. The ID is used to reference the from another location. ]]> @@ -286,7 +286,7 @@ property uses a object to represent the `` element of an XML digital signature. + The property uses a object to represent the `` element of an XML digital signature. For more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/). @@ -399,7 +399,7 @@ property uses a collection of objects to represent the `` tag of an XML digital signature. + The property uses a collection of objects to represent the `` tag of an XML digital signature. You can also add a to this collection using the method. @@ -453,7 +453,7 @@ property uses a byte array to represent the `` element of an XML digital signature contained within. + The property uses a byte array to represent the `` element of an XML digital signature contained within. For more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/). @@ -505,7 +505,7 @@ property uses the class to represent the `` element of an XML digital signature contained within. + The property uses the class to represent the `` element of an XML digital signature contained within. For more information about XML digital signatures, see the [W3C specification](https://www.w3.org/TR/xmldsig-core/). diff --git a/xml/System.Security.Cryptography.Xml/SignedInfo.xml b/xml/System.Security.Cryptography.Xml/SignedInfo.xml index f95befbeed4..7426e4abb1c 100644 --- a/xml/System.Security.Cryptography.Xml/SignedInfo.xml +++ b/xml/System.Security.Cryptography.Xml/SignedInfo.xml @@ -60,7 +60,7 @@ ## Remarks The class represents the `` element of an XML signature defined by the XML digital signature specification. The `` element, which is a subelement of the `` element, contains the canonicalization method used for signing, the algorithm used for signing and validation, and references that describe a digital signature. - For most scenarios, you should use the class available from the property to sign and verify XML digital signatures. + For most scenarios, you should use the class available from the property to sign and verify XML digital signatures. For more information about the `` element, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/xmldsig-core/). @@ -138,7 +138,7 @@ method adds a object to a collection that is accessible using the property. + The method adds a object to a collection that is accessible using the property. ]]> @@ -181,9 +181,9 @@ property uses a string Uniform Resource Identifier (URI) to represent the `` element of an XML digital signature. + The property uses a string Uniform Resource Identifier (URI) to represent the `` element of an XML digital signature. - Use the property to specify the canonicalization algorithm applied to the XML output of the class before performing signature calculations. + Use the property to specify the canonicalization algorithm applied to the XML output of the class before performing signature calculations. Use one of the URIs listed in the following table with this property. @@ -241,9 +241,9 @@ property contains the object used by the class to canonicalize an XML document before signing or verifying. + The property contains the object used by the class to canonicalize an XML document before signing or verifying. - The property is read-only. You can modify the object within this property by passing the desired transform Uniform Resource Identifier (URI) to the property. + The property is read-only. You can modify the object within this property by passing the desired transform Uniform Resource Identifier (URI) to the property. ]]> @@ -467,7 +467,7 @@ property to add a string ID to the XML representation of the current element. The ID is used to reference the from another location. + Use the property to add a string ID to the XML representation of the current element. The ID is used to reference the from another location. ]]> @@ -640,9 +640,9 @@ property uses a list of objects to represent the `` elements of an XML digital signature. + The property uses a list of objects to represent the `` elements of an XML digital signature. - Use the property to describe the transforms, digest algorithms, and digest values of an XML digital signature. + Use the property to describe the transforms, digest algorithms, and digest values of an XML digital signature. For more information about XML digital signatures, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/xmldsig-core/). @@ -735,9 +735,9 @@ property uses a string Uniform Resource Identifier (URI) to represents the `` element of an XML digital signature. + The property uses a string Uniform Resource Identifier (URI) to represents the `` element of an XML digital signature. - Use the property to specify the algorithm to use for signature generation and verification. This property identifies all cryptographic functions involved in creating an XML digital signature, including hashing, public key algorithms, Message Authentication Codes (MACs), and padding. + Use the property to specify the algorithm to use for signature generation and verification. This property identifies all cryptographic functions involved in creating an XML digital signature, including hashing, public key algorithms, Message Authentication Codes (MACs), and padding. Use one of the URIs in the following table with this property. diff --git a/xml/System.Security.Cryptography.Xml/SignedXml.xml b/xml/System.Security.Cryptography.Xml/SignedXml.xml index 7860b2dac5a..28368225cd5 100644 --- a/xml/System.Security.Cryptography.Xml/SignedXml.xml +++ b/xml/System.Security.Cryptography.Xml/SignedXml.xml @@ -283,7 +283,7 @@ The following code example shows how to sign and verify a single element of an X ## Remarks The 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. + 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/). @@ -340,7 +340,7 @@ The following code example shows how to sign and verify a single element of an X ## Remarks The 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. + 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/). @@ -767,7 +767,7 @@ The following code example shows how to sign and verify a single element of an X ## Remarks The 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. + You must set the data to be signed and the property before calling this method. @@ -1086,9 +1086,9 @@ The following code example shows how to sign and verify a single element of an X property represents the `` element of an XML digital signature using a object contained within the property. The `` element is a subelement of the `` element. + The 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. + 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/). @@ -1290,7 +1290,7 @@ The following code example shows how to sign and verify a single element of an X 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). + The 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). ]]> @@ -1375,21 +1375,21 @@ The following code example shows how to sign and verify a single element of an X 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. + The 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. + 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. + The following code example uses the property to sign and verify an entire XML document using an enveloped signature. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/Reference/.ctor/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/Reference/.ctor/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. + The following code example uses the property to sign and verify a Uniform Resource Identifier (URI) addressable object using a detached signature. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/Signature/Overview/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/Signature/Overview/sample.vb" id="Snippet1"::: @@ -1530,9 +1530,9 @@ The following code example shows how to sign and verify a single element of an X 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. + The 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. + 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/). @@ -1583,9 +1583,9 @@ The following code example shows how to sign and verify a single element of an X 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. + The 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. + 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/). @@ -1636,9 +1636,9 @@ The following code example shows how to sign and verify a single element of an X 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. + The 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. + 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/). @@ -1689,7 +1689,7 @@ The following code example shows how to sign and verify a single element of an X property to specify the asymmetric key you want to use to create an XML digital signature. + Use the property to specify the asymmetric key you want to use to create an XML digital signature. diff --git a/xml/System.Security.Cryptography.Xml/Transform.xml b/xml/System.Security.Cryptography.Xml/Transform.xml index c60013d0d00..0922f84d660 100644 --- a/xml/System.Security.Cryptography.Xml/Transform.xml +++ b/xml/System.Security.Cryptography.Xml/Transform.xml @@ -40,15 +40,15 @@ Represents the abstract base class from which all elements that can be used in an XML digital signature derive. - ` element describes how the signer transformed the data object that was signed. The verifier of a document then uses the `` element to transform the signed data in the same manner. If the verifier cannot transform the signed data in the same manner, the document cannot be verified. - - Use a class that derives from the class whenever you need to add one or more transform objects to an encrypted XML document or to a signed XML document. - - For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/) or the [XML encryption specification](https://www.w3.org/TR/xmlenc-core/), which are available on the W3C website. - + ` element describes how the signer transformed the data object that was signed. The verifier of a document then uses the `` element to transform the signed data in the same manner. If the verifier cannot transform the signed data in the same manner, the document cannot be verified. + + Use a class that derives from the class whenever you need to add one or more transform objects to an encrypted XML document or to a signed XML document. + + For more information about the `` element, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/) or the [XML encryption specification](https://www.w3.org/TR/xmlenc-core/), which are available on the W3C website. + ]]> @@ -128,13 +128,13 @@ Gets or sets the Uniform Resource Identifier (URI) that identifies the algorithm performed by the current transform. The URI that identifies the algorithm performed by the current object. - attribute of a `` element in an XMLDSIG signature. For example, the algorithm URI for the Base64 decoding transform is defined in the [XMLDSIG specification (Section 6.6.2)](https://www.w3.org/TR/xmldsig-core1/#sec-Base-64). - - You can conveniently set this value using one of the static fields associated with the class. - + attribute of a `` element in an XMLDSIG signature. For example, the algorithm URI for the Base64 decoding transform is defined in the [XMLDSIG specification (Section 6.6.2)](https://www.w3.org/TR/xmldsig-core1/#sec-Base-64). + + You can conveniently set this value using one of the static fields associated with the class. + ]]> @@ -182,13 +182,13 @@ Gets or sets an object that represents the document context under which the current object is running. An object that represents the document context under which the current object is running. - property represents the value passed to the constructor. When verifying a document, the property represents object. - - The property is set automatically during signature computation and checking, but before transforms are invoked. - + property represents the value passed to the constructor. When verifying a document, the property represents object. + + The property is set automatically during signature computation and checking, but before transforms are invoked. + ]]> @@ -272,27 +272,27 @@ When overridden in a derived class, returns an XML representation of the parameters of the object that are suitable to be included as subelements of an XMLDSIG element. A list of the XML nodes that represent the transform-specific content needed to describe the current object in an XMLDSIG element. - object represents an XPath transform using the XPath expression `self::text()`,a call to results in an object that represents the following XML element: - -``` - - self::text() - -``` - - This element corresponds to the transform-specific content of the `` element as defined in Section 4.3.3.4 of the XMLDSIG specification. For the above XPath transform, the entire `` element is as follows: - -``` - - - self::text() - - -``` - + object represents an XPath transform using the XPath expression `self::text()`,a call to results in an object that represents the following XML element: + +``` + + self::text() + +``` + + This element corresponds to the transform-specific content of the `` element as defined in Section 4.3.3.4 of the XMLDSIG specification. For the above XPath transform, the entire `` element is as follows: + +``` + + + self::text() + + +``` + ]]> @@ -379,13 +379,13 @@ When overridden in a derived class, returns the output of the current object of the specified type. The output of the current object as an object of the specified type. - method returns the output of the current transform after it is run on the value previously set by a call to the method. - - The type of the returned object must be one of the type objects in the property. - + method returns the output of the current transform after it is run on the value previously set by a call to the method. + + The type of the returned object must be one of the type objects in the property. + ]]> @@ -424,11 +424,11 @@ Returns the XML representation of the current object. The XML representation of the current object. - object returned by this method conforms to the XML Scheme for the `` element defined in Section 4.3.3.4 of the XMLDSIG specification. - + object returned by this method conforms to the XML Scheme for the `` element defined in Section 4.3.3.4 of the XMLDSIG specification. + ]]> @@ -466,13 +466,13 @@ When overridden in a derived class, gets an array of types that are valid inputs to the method of the current object. An array of valid input types for the current object; you can pass only objects of one of these types to the method of the current object. - property must contain at least one element because every object must accept at least one type as valid input. - - A object typically accepts one or more of the following types as input: , , or . - + property must contain at least one element because every object must accept at least one type as valid input. + + A object typically accepts one or more of the following types as input: , , or . + ]]> @@ -513,11 +513,11 @@ An object that specifies transform-specific content for the current object. When overridden in a derived class, parses the specified object as transform-specific content of a element and configures the internal state of the current object to match the element. - ` element. - + ` element. + ]]> @@ -558,11 +558,11 @@ The input to load into the current object. When overridden in a derived class, loads the specified input into the current object. - property. - + property. + ]]> @@ -600,11 +600,11 @@ When overridden in a derived class, gets an array of types that are possible outputs from the methods of the current object. An array of valid output types for the current object; only objects of one of these types are returned from the methods of the current object. - property must contain at least one element because every transform must generate at least one type as output. - + property must contain at least one element because every transform must generate at least one type as output. + ]]> @@ -647,15 +647,15 @@ Gets or sets a object that contains the namespaces that are propagated into the signature. A object that contains the namespaces that are propagated into the signature. - keys of the property are the namespace prefixes and the values are the namespace Uniform Resource Identifiers (URIs). - - The property is set automatically during signature computation and checking, but before transforms are invoked. - + keys of the property are the namespace prefixes and the values are the namespace Uniform Resource Identifiers (URIs). + + The property is set automatically during signature computation and checking, but before transforms are invoked. + ]]> The property was set to . @@ -705,11 +705,11 @@ Sets the current object. The current object. This property defaults to an 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. The property allows you 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. The property allows you 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). + ]]> diff --git a/xml/System.Security.Cryptography.Xml/TransformChain.xml b/xml/System.Security.Cryptography.Xml/TransformChain.xml index 498968be6b6..2ff0c3e9a20 100644 --- a/xml/System.Security.Cryptography.Xml/TransformChain.xml +++ b/xml/System.Security.Cryptography.Xml/TransformChain.xml @@ -40,19 +40,19 @@ Defines an ordered list of objects that is applied to unsigned content prior to digest calculation. - class contains a list of objects that determine how to order XML data before creating a digest. - - Use the class whenever you need to add one or more transform objects to an encrypted XML document or to a signed XML document. - - Both the class and the class contain a object. You can add a object to the class by calling the method. You can add a object to the class by calling the method. You can also create a object manually and pass it to either the property or the property. - - If you want to sign only a portion of an XML document, you can use a transform to identify the XML elements you intend to sign. Note that the property and the property automatically create internal transforms that allow you to sign a portion of a document. - - For more information about transforms, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/) or the [XML encryption specification](https://www.w3.org/TR/xmlenc-core/), which are available from the W3C website. - + class contains a list of objects that determine how to order XML data before creating a digest. + + Use the class whenever you need to add one or more transform objects to an encrypted XML document or to a signed XML document. + + Both the class and the class contain a object. You can add a object to the class by calling the method. You can add a object to the class by calling the method. You can also create a object manually and pass it to either the property or the property. + + If you want to sign only a portion of an XML document, you can use a transform to identify the XML elements you intend to sign. Note that the property and the property automatically create internal transforms that allow you to sign a portion of a document. + + For more information about transforms, see the [XMLDSIG specification](https://www.w3.org/TR/xmldsig-core/) or the [XML encryption specification](https://www.w3.org/TR/xmlenc-core/), which are available from the W3C website. + ]]> @@ -124,11 +124,11 @@ The transform to add to the list of transforms. Adds a transform to the list of transforms to be applied to the unsigned content prior to digest calculation. - object. - + object. + ]]> diff --git a/xml/System.Security.Cryptography.Xml/X509IssuerSerial.xml b/xml/System.Security.Cryptography.Xml/X509IssuerSerial.xml index 624cf1f8b60..7de85653700 100644 --- a/xml/System.Security.Cryptography.Xml/X509IssuerSerial.xml +++ b/xml/System.Security.Cryptography.Xml/X509IssuerSerial.xml @@ -42,25 +42,25 @@ Represents the <> element of an XML digital signature. - structure represents the `` element of an XML digital signature defined by the XML digital signature specification. The `` element is the subelement of the `` element that contains an X.509v3 certificate issuer's distinguished name and serial number pair. The distinguished name and serial number pair help identify a specific X.509v3 certificate. - - The issuer of an X.509 certificate is the name of the certification authority that issued the certificate. Certification authorities assign each certificate they issue a unique serial number for identification purposes. - - Use the structure to specify a certificate issuer's distinguished name and serial number pair when using the class. You can add an structure to the class using the property. Alternatively, you can add string values that represent the X.509 certificate issuer's distinguished name and serial number pair using the method. - - For more information about the `` element, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/xmldsig-core/). - - - -## Examples - The following code example demonstrates how to sign and verify an XML document using an X.509 certificate from a certificate store. This example saves key information to the signed document using the object. - + structure represents the `` element of an XML digital signature defined by the XML digital signature specification. The `` element is the subelement of the `` element that contains an X.509v3 certificate issuer's distinguished name and serial number pair. The distinguished name and serial number pair help identify a specific X.509v3 certificate. + + The issuer of an X.509 certificate is the name of the certification authority that issued the certificate. Certification authorities assign each certificate they issue a unique serial number for identification purposes. + + Use the structure to specify a certificate issuer's distinguished name and serial number pair when using the class. You can add an structure to the class using the property. Alternatively, you can add string values that represent the X.509 certificate issuer's distinguished name and serial number pair using the method. + + For more information about the `` element, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/xmldsig-core/). + + + +## Examples + The following code example demonstrates how to sign and verify an XML document using an X.509 certificate from a certificate store. This example saves key information to the signed document using the object. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/X509IssuerSerial/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/X509IssuerSerial/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/X509IssuerSerial/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -105,21 +105,21 @@ Gets or sets an X.509 certificate issuer's distinguished name. An X.509 certificate issuer's distinguished name. - property represents an X.509 certificate issuer's distinguished name specified in the `` element. - - For more information about the `` element, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/xmldsig-core/). - - - -## Examples - The following code example demonstrates how to sign and verify an XML document using an X.509 certificate from a certificate store. This example saves key information to the signed document using the object. - + property represents an X.509 certificate issuer's distinguished name specified in the `` element. + + For more information about the `` element, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/xmldsig-core/). + + + +## Examples + The following code example demonstrates how to sign and verify an XML document using an X.509 certificate from a certificate store. This example saves key information to the signed document using the object. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/X509IssuerSerial/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/X509IssuerSerial/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/X509IssuerSerial/Overview/sample.vb" id="Snippet1"::: + ]]> @@ -164,21 +164,21 @@ Gets or sets an X.509 certificate issuer's serial number. An X.509 certificate issuer's serial number. - property represents an X.509 certificate issuer's serial number specified in the `` element. - - For more information about the `` element, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/xmldsig-core/). - - - -## Examples - The following code example demonstrates how to sign and verify an XML document using an X.509 certificate from a certificate store. This example saves key information to the signed document using the object. - + property represents an X.509 certificate issuer's serial number specified in the `` element. + + For more information about the `` element, see the [World Wide Web Consortium (W3C) specification](https://www.w3.org/TR/xmldsig-core/). + + + +## Examples + The following code example demonstrates how to sign and verify an XML document using an X.509 certificate from a certificate store. This example saves key information to the signed document using the object. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/X509IssuerSerial/Overview/sample.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/X509IssuerSerial/Overview/sample.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/X509IssuerSerial/Overview/sample.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Security.Cryptography.Xml/XmlDecryptionTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDecryptionTransform.xml index 6245439327d..9cd2bd315ef 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDecryptionTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDecryptionTransform.xml @@ -47,15 +47,15 @@ Specifies the order of XML Digital Signature and XML Encryption operations when both are performed on the same document. - class provides a transform that determines the order of XML Digital Signature and XML Encryption operations when both are performed on the same document. - - Use the class whenever you need to perform XML encryption and apply an XML digital signature to the same XML document. - - You must pass an object to the property that contains the necessary key information to decrypt the document. - + class provides a transform that determines the order of XML Digital Signature and XML Encryption operations when both are performed on the same document. + + Use the class whenever you need to perform XML encryption and apply an XML digital signature to the same XML document. + + You must pass an object to the property that contains the necessary key information to decrypt the document. + ]]> @@ -160,11 +160,11 @@ Gets or sets an object that contains information about the keys necessary to decrypt an XML document. An object that contains information about the keys necessary to decrypt an XML document. - object to the property that contains the necessary key information to decrypt the document. - + object to the property that contains the necessary key information to decrypt the document. + ]]> @@ -321,13 +321,13 @@ Gets an array of types that are valid inputs to the method of the current object. An array of valid input types for the current object; you can pass only objects of one of these types to the method of the current object. - property must contain at least one element because every object must accept at least one type as valid input. - - An object typically accepts one or more of the following types as input: , , or . - + property must contain at least one element because every object must accept at least one type as valid input. + + An object typically accepts one or more of the following types as input: , , or . + ]]> @@ -416,25 +416,25 @@ An object that specifies transform-specific content for the current object. Parses the specified object as transform-specific content of a element and configures the internal state of the current object to match the element. - ` element. - + ` element. + ]]> - The parameter is . - - -or- - - The Uniform Resource Identifier (URI) value of an object in was not found. - - -or- - - The length of the URI value of an object in is 0. - - -or- - + The parameter is . + + -or- + + The Uniform Resource Identifier (URI) value of an object in was not found. + + -or- + + The length of the URI value of an object in is 0. + + -or- + The first character of the URI value of an object in is not '#'. @@ -473,11 +473,11 @@ The input to load into the current object. When overridden in a derived class, loads the specified input into the current object. - property. - + property. + ]]> The parameter is . @@ -515,11 +515,11 @@ Gets an array of types that are possible outputs from the methods of the current object. An array of valid output types for the current object; only objects of one of these types are returned from the methods of the current object. - property must contain at least one element because every transform must generate at least one type as output. - + property must contain at least one element because every transform must generate at least one type as output. + ]]> diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigBase64Transform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigBase64Transform.xml index cd8310e3b03..e82fae489ec 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigBase64Transform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigBase64Transform.xml @@ -295,7 +295,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the valid input types for the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the valid input types for the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.vb" id="Snippet4"::: @@ -388,7 +388,7 @@ property. + The type of the input object must be one of the types in the property. @@ -444,7 +444,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the valid output types for the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the valid output types for the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigBase64TransformUrl/members.vb" id="Snippet5"::: diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigC14NTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigC14NTransform.xml index e64031e744a..b63afacee9a 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigC14NTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigC14NTransform.xml @@ -47,7 +47,7 @@ Use the class when you need to sign an XML document that does not contain comments. - In most cases, a new instance of a canonicalization transform class is not required. To specify a canonicalization transform, pass the Uniform Resource Identifier (URI) that describes the transform to the property, which is accessible from the property. To acquire a reference to the canonicalization transform, use the property, which is accessible from the property. + In most cases, a new instance of a canonicalization transform class is not required. To specify a canonicalization transform, pass the Uniform Resource Identifier (URI) that describes the transform to the property, which is accessible from the property. To acquire a reference to the canonicalization transform, use the property, which is accessible from the property. The URI that describes the class is defined by the field and the field. @@ -61,7 +61,7 @@ This section contains two code examples. The first example demonstrates how to sign non-XML data using a detached signature. Example #1 creates a signature of `www.microsoft.com` in an XML file and then verifies the file. The second example demonstrates how to call members of the class. **Example #1** - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigdetach.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigdetach.vb" id="Snippet1"::: @@ -407,7 +407,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the valid input types for the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the valid input types for the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.vb" id="Snippet5"::: @@ -500,7 +500,7 @@ property. + The type of the input object must be one of the types in the property. @@ -556,7 +556,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the valid output types for the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the valid output types for the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigC14NTransformUrl/members.vb" id="Snippet6"::: diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigC14NWithCommentsTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigC14NWithCommentsTransform.xml index 09dabdabbd6..6a032f830d0 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigC14NWithCommentsTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigC14NWithCommentsTransform.xml @@ -41,7 +41,7 @@ Use the class when you need to sign an XML document that contains comments. - Note that you cannot directly create a new instance of a canonicalization transform class. To specify a canonicalization transform, pass the Uniform Resource Identifier (URI) that describes the transform to the property, which is accessible from the property. To acquire a reference to the canonicalization transform, use the property, which is accessible from the property. + Note that you cannot directly create a new instance of a canonicalization transform class. To specify a canonicalization transform, pass the Uniform Resource Identifier (URI) that describes the transform to the property, which is accessible from the property. To acquire a reference to the canonicalization transform, use the property, which is accessible from the property. The URI that describes the class is defined by the field. @@ -55,7 +55,7 @@ This section contains two code examples. The first example demonstrates how to sign an XML file using a detached signature. This example creates a signature of `www.microsoft.com` in an XML file and then verifies the file. The second example demonstrates how to sign an XML file using an envelope signature. This example creates a signature of an XML file and then saves the signature in new XML file. **Example #1** - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/XmlDsigC14NWithCommentsTransform/Overview/sampledetached.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/XmlDsigC14NWithCommentsTransform/Overview/sampledetached.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigEnvelopedSignatureTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigEnvelopedSignatureTransform.xml index d532c467dd4..d19f293c00b 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigEnvelopedSignatureTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigEnvelopedSignatureTransform.xml @@ -57,7 +57,7 @@ This section contains two code examples. The first example demonstrates how to sign an XML file using an envelope signature. The second example demonstrates how to use members of the class. **Example #1** - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigenv.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/KeyInfo/Overview/xmldsigenv.vb" id="Snippet1"::: @@ -360,7 +360,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the valid input types for the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the valid input types for the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.vb" id="Snippet5"::: @@ -461,7 +461,7 @@ property. + The type of the input object must be one of the types in the property. @@ -518,7 +518,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the valid output types for the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the valid output types for the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigEnvelopedSignatureTransformUrl/members.vb" id="Snippet6"::: diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NTransform.xml index a72194b14ab..e8d88ffa4f7 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NTransform.xml @@ -46,7 +46,7 @@ Use the class when you need to canonicalize an XML subdocument so that it is independent from its XML context. For example, applications such as Web services that use signed XML within complex communication protocols often need to canonicalize XML in this manner. Such applications often envelop XML within various dynamically constructed elements, which can substantially change the document and cause XML signature verification to fail. The class solves this problem by excluding such ancestor context from the canonical subdocument. - Typically, you do not create a new instance of a canonicalization transform class. To specify a canonicalization transform, pass the Uniform Resource Identifier (URI) that describes a transform to the property, which is accessible from the property. To acquire a reference to the canonicalization transform, use the property, which is accessible from the property. + Typically, you do not create a new instance of a canonicalization transform class. To specify a canonicalization transform, pass the Uniform Resource Identifier (URI) that describes a transform to the property, which is accessible from the property. To acquire a reference to the canonicalization transform, use the property, which is accessible from the property. You are required to create a new instance of a canonicalization transform class only when you want to manually hash an XML document or use your own canonicalization algorithm. @@ -60,7 +60,7 @@ ## Examples The following code example shows how to sign an XML document with the class using an envelope signature. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigExcC14NTransformUrl/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigExcC14NTransformUrl/example.vb" id="Snippet1"::: @@ -387,7 +387,7 @@ ## Remarks The method returns the output of the current transform after it is run on the value previously set by a call to the method. - The type of the returned object must be one of the type objects in the property. + The type of the returned object must be one of the type objects in the property. ]]> @@ -440,7 +440,7 @@ property contains a white-space delimited list of namespace prefixes to canonicalize using the standard canonicalization algorithm rather than the exclusive canonicalization algorithm. To specify the default namespace, which does not have a prefix, pass the special prefix "#default". + The property contains a white-space delimited list of namespace prefixes to canonicalize using the standard canonicalization algorithm rather than the exclusive canonicalization algorithm. To specify the default namespace, which does not have a prefix, pass the special prefix "#default". @@ -489,7 +489,7 @@ property must contain at least one element because every object must accept at least one type as valid input. + The array returned by the property must contain at least one element because every object must accept at least one type as valid input. A object typically accepts one or more of the following types as input: , , or . @@ -579,7 +579,7 @@ property. + The type of the input object must be one of the types in the property. ]]> @@ -629,7 +629,7 @@ property must contain at least one element because every transform must generate at least one type as output. + The array returned by the property must contain at least one element because every transform must generate at least one type as output. ]]> diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NWithCommentsTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NWithCommentsTransform.xml index 47939fdc0a9..ba5f2e5874c 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NWithCommentsTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigExcC14NWithCommentsTransform.xml @@ -40,7 +40,7 @@ Use the class when you need to canonicalize an XML subdocument so that it is independent from its XML context. For example, applications such as Web services that use signed XML within complex communication protocols often need to canonicalize XML in this manner. Such applications often envelop XML within various dynamically constructed elements, which can substantially change the document and cause XML signature verification to fail. The class solves this problem by excluding such ancestor context from the canonical subdocument. - Note that you cannot directly create a new instance of a canonicalization transform class. To specify a canonicalization transform, pass the Uniform Resource Identifier (URI) that describes the transform to the property, which is accessible from the property. To acquire a reference to the canonicalization transform, use the property, which is accessible from the property. + Note that you cannot directly create a new instance of a canonicalization transform class. To specify a canonicalization transform, pass the Uniform Resource Identifier (URI) that describes the transform to the property, which is accessible from the property. To acquire a reference to the canonicalization transform, use the property, which is accessible from the property. The URI that describes the class is defined by the field. @@ -50,7 +50,7 @@ ## Examples The following code example shows how to sign and verify an XML document using the class. This example creates an envelope signature. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigExcC14NWithCommentsTransformUrl/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigExcC14NWithCommentsTransformUrl/sample.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigXPathTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigXPathTransform.xml index 08fa127c731..db78ed9c4f1 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigXPathTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigXPathTransform.xml @@ -57,7 +57,7 @@ This section contains two code examples. The first code example shows how to sign and verify an XML document using the class with an envelope signature. This example signs an XML document and saves the signature in a new XML document. The second code example demonstrates how to call members of the class. **Example #1** - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/XmlDsigXPathTransform/Overview/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/XmlDsigXPathTransform/Overview/sample.vb" id="Snippet1"::: @@ -316,7 +316,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the valid input types for the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the valid input types for the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.vb" id="Snippet4"::: @@ -368,7 +368,7 @@ To initialize the class with an XPath transform, complete the following steps. -1. Create a new class and set the property to the value of an XPath transform string. +1. Create a new class and set the property to the value of an XPath transform string. 2. Call the method to create an object that represents the transform. @@ -432,7 +432,7 @@ ## Remarks Use the method to initialize an object to the value of an XPath transform using an , , or object. For information about initializing an object using an XPath transform string, see the method. - The type of the input object must be one of the types in the property. + The type of the input object must be one of the types in the property. @@ -487,7 +487,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the valid output types for the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the valid output types for the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigXPathTransformUrl/members.vb" id="Snippet5"::: diff --git a/xml/System.Security.Cryptography.Xml/XmlDsigXsltTransform.xml b/xml/System.Security.Cryptography.Xml/XmlDsigXsltTransform.xml index f3911a73a33..41b0abff3e0 100644 --- a/xml/System.Security.Cryptography.Xml/XmlDsigXsltTransform.xml +++ b/xml/System.Security.Cryptography.Xml/XmlDsigXsltTransform.xml @@ -61,7 +61,7 @@ This section contains two code examples. The first code example shows how to sign and verify an XML document using the class with an envelope signature. The second code example demonstrates how to use members of the class. **Example #1** - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/XmlDsigXsltTransform/Overview/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/XmlDsigXsltTransform/Overview/sample.vb" id="Snippet1"::: @@ -353,7 +353,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the valid input types for the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the valid input types for the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.vb" id="Snippet4"::: @@ -459,7 +459,7 @@ property. The valid input types to are , , and . + The type of the input object must be one of the types in the property. The valid input types to are , , and . @@ -514,7 +514,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the valid output types for the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the valid output types for the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography.Xml/SignedXml/XmlDsigXsltTransformUrl/members.vb" id="Snippet5"::: diff --git a/xml/System.Security.Cryptography/AesCng.xml b/xml/System.Security.Cryptography/AesCng.xml index 956f9e309a8..fdeaf628816 100644 --- a/xml/System.Security.Cryptography/AesCng.xml +++ b/xml/System.Security.Cryptography/AesCng.xml @@ -462,7 +462,7 @@ This method decrypts an encrypted message created using the overload with the same signature. > [!NOTE] -> If you've created the object using an existing persisted key and you want to make use of that key when decrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. +> If you've created the object using an existing persisted key and you want to make use of that key when decrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. ]]> @@ -605,7 +605,7 @@ Use this method to encrypt a message and then use the overload with the same signature to decrypt the result of this method. > [!NOTE] -> If you've created the object using an existing persisted key and you want to make use of that key when encrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. +> If you've created the object using an existing persisted key and you want to make use of that key when encrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. ]]> @@ -802,9 +802,9 @@ Use this method to encrypt a message and then use the object using an existing persisted key, when you read the value of the property, an attempt to export the key will be made. In this case, if the key is not exportable, a will be thrown. + If you've created the object using an existing persisted key, when you read the value of the property, an attempt to export the key will be made. In this case, if the key is not exportable, a will be thrown. - In addition to that, if you set the value of the property, the persisted key will no longer be used and a temporary key will be used instead. If you need to use the persisted key again, a new instance of class needs to be created. + In addition to that, if you set the value of the property, the persisted key will no longer be used and a temporary key will be used instead. If you need to use the persisted key again, a new instance of class needs to be created. ]]> @@ -856,7 +856,7 @@ Use this method to encrypt a message and then use the object using an existing persisted key and you set the value of the property, the persisted key will no longer be used and an ephemeral key will be used instead. If you need to use the persisted key again, a new instance of class needs to be created. + If you've created the object using an existing persisted key and you set the value of the property, the persisted key will no longer be used and an ephemeral key will be used instead. If you need to use the persisted key again, a new instance of class needs to be created. ]]> diff --git a/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml b/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml index d2411be6b50..6813bcb98f1 100644 --- a/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/AesCryptoServiceProvider.xml @@ -68,15 +68,15 @@ Performs symmetric encryption and decryption using the Cryptographic Application Programming Interfaces (CAPI) implementation of the Advanced Encryption Standard (AES) algorithm. - class. - + class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.vb" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aescryptoservprovider/fs/program.fs" id="Snippet1"::: - + ]]> @@ -167,11 +167,11 @@ Gets or sets the block size, in bits, of the cryptographic operation. The block size, in bits. - The block size is invalid. @@ -318,15 +318,15 @@ Creates a symmetric AES decryptor object using the specified key and initialization vector (IV). A symmetric AES decryptor object. - method to decrypt an encrypted message. This code example is part of a larger example provided for the class. - + method to decrypt an encrypted message. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.vb" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aescryptoservprovider/fs/program.fs" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.vb" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aescryptoservprovider/fs/program.fs" id="Snippet3"::: + ]]> @@ -475,20 +475,20 @@ Creates a symmetric encryptor object using the specified key and initialization vector (IV). A symmetric AES encryptor object. - and properties to determine the size of the `key` and `iv` parameters. - - - -## Examples - The following example shows how to use the method to encrypt a message. This code example is part of a larger example provided for the class. - + and properties to determine the size of the `key` and `iv` parameters. + + + +## Examples + The following example shows how to use the method to encrypt a message. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.vb" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aescryptoservprovider/fs/program.fs" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AesCryptoServiceProvider/Overview/program.vb" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/VS_Snippets_CLR/aescryptoservprovider/fs/program.fs" id="Snippet2"::: + ]]> The or parameter is . @@ -747,15 +747,15 @@ Gets or sets the initialization vector () for the symmetric algorithm. The initialization vector. - property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. - - The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key and an initialization vector to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and property to the same values that were used for encryption. - - For a given secret key *k*, a simple block cipher that does not use an initialization vector will encrypt the same input block of plain text into the same output block of cipher text. If you have duplicate blocks within your plain text stream, you will have duplicate blocks within your cipher text stream. If unauthorized users know anything about the structure of a block of your plain text, they can use that information to decipher the known cipher text block and possibly recover your key. To combat this problem, information from the previous block is mixed into the process of encrypting the next block. Thus, the output of two identical plain text blocks is different. Because this technique uses the previous block to encrypt the next block, an initialization vector is needed to encrypt the first block of data. - + property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. + + The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key and an initialization vector to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and property to the same values that were used for encryption. + + For a given secret key *k*, a simple block cipher that does not use an initialization vector will encrypt the same input block of plain text into the same output block of cipher text. If you have duplicate blocks within your plain text stream, you will have duplicate blocks within your cipher text stream. If unauthorized users know anything about the structure of a block of your plain text, they can use that information to decipher the known cipher text block and possibly recover your key. To combat this problem, information from the previous block is mixed into the process of encrypting the next block. Thus, the output of two identical plain text blocks is different. Because this technique uses the previous block to encrypt the next block, an initialization vector is needed to encrypt the first block of data. + ]]> An attempt was made to set the initialization vector to . @@ -878,13 +878,13 @@ Gets or sets the size, in bits, of the secret key. The size, in bits, of the key. - @@ -924,9 +924,9 @@ Gets the block sizes, in bits, that are supported by the symmetric algorithm. An array that contains the block sizes supported by the algorithm. - @@ -967,9 +967,9 @@ Gets the key sizes, in bits, that are supported by the symmetric algorithm. An array that contains the key sizes supported by the algorithm. - @@ -1015,11 +1015,11 @@ Gets or sets the mode for operation of the symmetric algorithm. The mode for operation of the symmetric algorithm. The default is . - enumeration for a description of specific modes. - + enumeration for a description of specific modes. + ]]> The cipher mode is not one of the values. @@ -1065,11 +1065,11 @@ Gets or sets the padding mode used in the symmetric algorithm. The padding mode used in the symmetric algorithm. The default is . - enumeration for a description of specific modes. - + enumeration for a description of specific modes. + ]]> The padding mode is not one of the values. diff --git a/xml/System.Security.Cryptography/AsnEncodedDataCollection.xml b/xml/System.Security.Cryptography/AsnEncodedDataCollection.xml index 1347ed8d2a5..488865b1267 100644 --- a/xml/System.Security.Cryptography/AsnEncodedDataCollection.xml +++ b/xml/System.Security.Cryptography/AsnEncodedDataCollection.xml @@ -76,7 +76,7 @@ ## Examples The following code example shows how to use the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.vb" id="Snippet1"::: @@ -670,7 +670,7 @@ One of the OIDs is and the OIDs do not match. is not thread safe. Derived classes can provide their own synchronized version of the using this property. The synchronizing code must perform operations on the property of the class, not directly on the class itself. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. + is not thread safe. Derived classes can provide their own synchronized version of the using this property. The synchronizing code must perform operations on the property of the class, not directly on the class itself. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the object. diff --git a/xml/System.Security.Cryptography/AsnEncodedDataEnumerator.xml b/xml/System.Security.Cryptography/AsnEncodedDataEnumerator.xml index 010ba088c00..75680d3df65 100644 --- a/xml/System.Security.Cryptography/AsnEncodedDataEnumerator.xml +++ b/xml/System.Security.Cryptography/AsnEncodedDataEnumerator.xml @@ -73,7 +73,7 @@ ## Examples The following code example shows how to use the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsnEncodedData/Overview/asnencodeddata.vb" id="Snippet1"::: @@ -127,7 +127,7 @@ method must be called to advance the enumerator to the first element of the collection before reading the value of the property; otherwise, returns `null` or throws an exception. + After an enumerator is created, the method must be called to advance the enumerator to the first element of the collection before reading the value of the property; otherwise, returns `null` or throws an exception. also returns `null` or throws an exception if the last call to returns `false`, which indicates that the end of the collection has been reached. diff --git a/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml b/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml index 35403aeb151..d1451ca7c45 100644 --- a/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml +++ b/xml/System.Security.Cryptography/AsymmetricAlgorithm.xml @@ -1584,7 +1584,7 @@ The algorithm-specific key import failed. property to return the name for the key exchange algorithm. This code example is part of a larger example provided for the class. + The following code example demonstrates how to override the property to return the name for the key exchange algorithm. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet6"::: @@ -1641,12 +1641,12 @@ The algorithm-specific key import failed. property. + The valid key sizes are specified by the particular implementation of the asymmetric algorithm and are listed in the property. ## Examples - The following code example demonstrates how to override the property to verify that it falls within the range identified in the local `keySizes` member variable. This code example is part of a larger example provided for the class. + The following code example demonstrates how to override the property to verify that it falls within the range identified in the local `keySizes` member variable. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet9"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet9"::: @@ -1703,9 +1703,9 @@ The algorithm-specific key import failed. property. + The valid key sizes are specified by the particular implementation of the asymmetric algorithm and are listed in the property. - This field is accessed through the property. + This field is accessed through the property. ]]> @@ -1770,7 +1770,7 @@ The algorithm-specific key import failed. ## Examples - The following code example demonstrates how to call the property to retrieve the , , and properties. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the , , and properties. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet10"::: @@ -1838,7 +1838,7 @@ The algorithm-specific key import failed. ## Remarks The asymmetric algorithm supports only key sizes that match an entry in this array. - This field is accessed through the property. + This field is accessed through the property. ]]> @@ -1901,7 +1901,7 @@ The algorithm-specific key import failed. property to return the name of the signature algorithm. This code example is part of a larger example provided for the class. + The following code example demonstrates how to override the property to return the name of the signature algorithm. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricAlgorithm/Overview/customcrypto.vb" id="Snippet7"::: diff --git a/xml/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter.xml b/xml/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter.xml index 05797c683cd..64c823efa5a 100644 --- a/xml/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter.xml +++ b/xml/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter.xml @@ -68,24 +68,24 @@ Represents the base class from which all asymmetric key exchange deformatters derive. - [!CAUTION] -> It is highly recommended that you not attempt to create your own key exchange method from the basic functionality provided, because many details of the operation must be performed carefully in order for the key exchange to be successful. - - - -## Examples - The following example demonstrates how to extend the class. - +> It is highly recommended that you not attempt to create your own key exchange method from the basic functionality provided, because many details of the operation must be performed carefully in order for the key exchange to be successful. + + + +## Examples + The following example demonstrates how to extend the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.vb" id="Snippet1"::: + ]]> @@ -133,13 +133,13 @@ Initializes a new instance of . - to establish the key before calling an implementation of . - + to establish the key before calling an implementation of . + ]]> Cryptographic Services @@ -192,19 +192,19 @@ When overridden in a derived class, extracts secret information from the encrypted key exchange data. The secret information derived from the key exchange data. - method to create an encrypted key exchange for the specified input data. This code example is part of a larger example provided for the class. - + method to create an encrypted key exchange for the specified input data. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.vb" id="Snippet4"::: + ]]> Cryptographic Services @@ -254,14 +254,14 @@ When overridden in a derived class, gets or sets the parameters for the asymmetric key exchange. A string in XML format containing the parameters of the asymmetric key exchange operation. - property to disallow access to the parameters of the formatter. This code example is part of a larger example provided for the class. - + property to disallow access to the parameters of the formatter. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.vb" id="Snippet3"::: + ]]> Cryptographic Services @@ -313,19 +313,19 @@ The instance of the implementation of that holds the private key. When overridden in a derived class, sets the private key to use for decrypting the secret information. - implementation. - - - -## Examples - The following code example demonstrates how to override the to set the public key for encryption operations. This code example is part of a larger example provided for the class. - + implementation. + + + +## Examples + The following code example demonstrates how to override the to set the public key for encryption operations. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/AsymmetricKeyExchangeDeformatter/Overview/contosodeformatter.vb" id="Snippet5"::: + ]]> Cryptographic Services diff --git a/xml/System.Security.Cryptography/CngAlgorithm.xml b/xml/System.Security.Cryptography/CngAlgorithm.xml index 0be887331f9..183faa21500 100644 --- a/xml/System.Security.Cryptography/CngAlgorithm.xml +++ b/xml/System.Security.Cryptography/CngAlgorithm.xml @@ -72,7 +72,7 @@ You can also use this class to create objects for algorithm types that are not covered by the static properties. - Several Cryptography Next Generation (CNG) classes (such as ) accept objects through an `algorithm` parameter. When the class receives the object, it retrieves the embedded algorithm name by calling the object's property. + Several Cryptography Next Generation (CNG) classes (such as ) accept objects through an `algorithm` parameter. When the class receives the object, it retrieves the embedded algorithm name by calling the object's property. Therefore, serves as an enumeration of well-known algorithms. It lets you specify a well-known algorithm by using a strongly typed value instead of a string. diff --git a/xml/System.Security.Cryptography/CngAlgorithmGroup.xml b/xml/System.Security.Cryptography/CngAlgorithmGroup.xml index 238333a4e6a..34ec85a2bc5 100644 --- a/xml/System.Security.Cryptography/CngAlgorithmGroup.xml +++ b/xml/System.Security.Cryptography/CngAlgorithmGroup.xml @@ -63,22 +63,22 @@ Encapsulates the name of an encryption algorithm group. - class is a utility class. It consists of static properties, comparison methods, and a private, internally maintained string that defines an algorithm group name. - - The static properties return objects. Each object's internal string is initialized to the algorithm group name that corresponds to the name of the static property. - - You can also use this class to create objects for algorithm groups that are not covered by the static properties. - - Several Cryptography Next Generation (CNG) classes (such as ) return objects. Classes that receive objects can retrieve the embedded algorithm group name by calling the object's property. - - Therefore, serves as an enumeration of well-known algorithm groups. It lets you specify an algorithm group name by using a strongly typed value instead of a string. + class is a utility class. It consists of static properties, comparison methods, and a private, internally maintained string that defines an algorithm group name. + + The static properties return objects. Each object's internal string is initialized to the algorithm group name that corresponds to the name of the static property. + + You can also use this class to create objects for algorithm groups that are not covered by the static properties. + + Several Cryptography Next Generation (CNG) classes (such as ) return objects. Classes that receive objects can retrieve the embedded algorithm group name by calling the object's property. + + Therefore, serves as an enumeration of well-known algorithm groups. It lets you specify an algorithm group name by using a strongly typed value instead of a string. > [!NOTE] > CNG classes don't work on non-Windows platforms. - + ]]> @@ -125,13 +125,13 @@ The name of the algorithm group to initialize. Initializes a new instance of the class. - class internally maintain the algorithm group name that is specified by the `algorithmGroup` parameter. - - The primary purpose of this constructor is to provide a method for creating objects for algorithm groups that are not represented by the static properties of the class. This capacity enables future .NET Framework releases, service packs, and third-party developers to add new algorithm groups, which can be accessed just like the algorithm groups that are currently available. - + class internally maintain the algorithm group name that is specified by the `algorithmGroup` parameter. + + The primary purpose of this constructor is to provide a method for creating objects for algorithm groups that are not represented by the static properties of the class. This capacity enables future .NET Framework releases, service packs, and third-party developers to add new algorithm groups, which can be accessed just like the algorithm groups that are currently available. + ]]> The parameter is . diff --git a/xml/System.Security.Cryptography/CngExportPolicies.xml b/xml/System.Security.Cryptography/CngExportPolicies.xml index 1a155c9e9b2..cf8d9de4771 100644 --- a/xml/System.Security.Cryptography/CngExportPolicies.xml +++ b/xml/System.Security.Cryptography/CngExportPolicies.xml @@ -53,11 +53,11 @@ Specifies the key export policies for a key. - property and the class. - + property and the class. + ]]> diff --git a/xml/System.Security.Cryptography/CngKey.xml b/xml/System.Security.Cryptography/CngKey.xml index e299125b4a5..b1cfe8c7a79 100644 --- a/xml/System.Security.Cryptography/CngKey.xml +++ b/xml/System.Security.Cryptography/CngKey.xml @@ -2271,7 +2271,7 @@ property will return the file name of the key as this property. The name returned by the is implementation-dependent. + This property gets an alternate name that can be used when accessing the key. You can use this property if the original key name does not uniquely identify the persisted key. The property will return the file name of the key as this property. The name returned by the is implementation-dependent. ]]> diff --git a/xml/System.Security.Cryptography/CngKeyBlobFormat.xml b/xml/System.Security.Cryptography/CngKeyBlobFormat.xml index 45e830d8f9b..451ad726a31 100644 --- a/xml/System.Security.Cryptography/CngKeyBlobFormat.xml +++ b/xml/System.Security.Cryptography/CngKeyBlobFormat.xml @@ -63,22 +63,22 @@ Specifies a key BLOB format for use with Microsoft Cryptography Next Generation (CNG) objects. - class is a utility class. It consists of static properties, comparison methods, and a private, internally maintained string that specifies the key BLOB format name. - - The static properties return objects. Each object's internal string name is initialized to the key BLOB format name that corresponds to the name of the static property. - - You can also use this class to create objects for key BLOB formats that are not covered by the static properties. - - Several CNG classes (such as ) accept objects through a `format` parameter. When the class receives the object, it retrieves the embedded name of the key BLOB format by calling the object's property. - - Therefore, serves as an enumeration of well-known key BLOB formats. It lets you identify a well-known key BLOB format by using a strongly typed value instead of a string. + class is a utility class. It consists of static properties, comparison methods, and a private, internally maintained string that specifies the key BLOB format name. + + The static properties return objects. Each object's internal string name is initialized to the key BLOB format name that corresponds to the name of the static property. + + You can also use this class to create objects for key BLOB formats that are not covered by the static properties. + + Several CNG classes (such as ) accept objects through a `format` parameter. When the class receives the object, it retrieves the embedded name of the key BLOB format by calling the object's property. + + Therefore, serves as an enumeration of well-known key BLOB formats. It lets you identify a well-known key BLOB format by using a strongly typed value instead of a string. > [!NOTE] > CNG classes don't work on non-Windows platforms. - + ]]> @@ -125,11 +125,11 @@ The key BLOB format to initialize. Initializes a new instance of the class by using the specified format. - objects for format types that are not represented by the static properties of the class. This capacity allows future .NET Framework releases, service packs, and third-party developers to add new key BLOB formats, which can be accessed just like the key BLOB formats that are currently available. - + objects for format types that are not represented by the static properties of the class. This capacity allows future .NET Framework releases, service packs, and third-party developers to add new key BLOB formats, which can be accessed just like the key BLOB formats that are currently available. + ]]> The parameter is . @@ -264,11 +264,11 @@ Gets a object that specifies a private key BLOB for an elliptic curve cryptography (ECC) key. An object that specifies an ECC private key BLOB. - @@ -315,11 +315,11 @@ Gets a object that specifies a public key BLOB for an elliptic curve cryptography (ECC) key. An object that specifies an ECC public key BLOB. - @@ -542,11 +542,11 @@ Gets a object that specifies a generic private key BLOB. An object that specifies a generic private key BLOB. - @@ -593,11 +593,11 @@ Gets a object that specifies a generic public key BLOB. An object that specifies a generic public key BLOB. - @@ -880,11 +880,11 @@ Gets a object that specifies an opaque transport key BLOB. An object that specifies an opaque transport key BLOB. - @@ -931,11 +931,11 @@ Gets a object that specifies a Private Key Information Syntax Standard (PKCS #8) key BLOB. An object that specifies a PKCS #8 private key BLOB. - diff --git a/xml/System.Security.Cryptography/CngKeyCreationOptions.xml b/xml/System.Security.Cryptography/CngKeyCreationOptions.xml index 975448556ee..93427c4e488 100644 --- a/xml/System.Security.Cryptography/CngKeyCreationOptions.xml +++ b/xml/System.Security.Cryptography/CngKeyCreationOptions.xml @@ -53,11 +53,11 @@ Specifies options used for key creation. - property. - + property. + ]]> diff --git a/xml/System.Security.Cryptography/CngKeyCreationParameters.xml b/xml/System.Security.Cryptography/CngKeyCreationParameters.xml index bd6b3051239..6618ab556f3 100644 --- a/xml/System.Security.Cryptography/CngKeyCreationParameters.xml +++ b/xml/System.Security.Cryptography/CngKeyCreationParameters.xml @@ -54,20 +54,20 @@ Contains advanced properties for key creation. - objects contain properties. Some properties must be added to a key when it is created. Other properties can be added after the key is created. - - The class enables you to add properties to a key as it is being created. You can do this by passing a object that contains standard key properties, such as key storage provider (KSP), export policy, key usage, user interface (UI) policy, and parent window handle, to the method. The object that is being created will be initialized with these values before it is finalized. - - You can also add non-standard properties to a key by using the property. - - If you need to add properties after a key is created, use the method. + objects contain properties. Some properties must be added to a key when it is created. Other properties can be added after the key is created. + + The class enables you to add properties to a key as it is being created. You can do this by passing a object that contains standard key properties, such as key storage provider (KSP), export policy, key usage, user interface (UI) policy, and parent window handle, to the method. The object that is being created will be initialized with these values before it is finalized. + + You can also add non-standard properties to a key by using the property. + + If you need to add properties after a key is created, use the method. > [!NOTE] > CNG classes don't work on non-Windows platforms. - + ]]> @@ -164,11 +164,11 @@ Gets or sets the key export policy. An object that specifies a key export policy. The default value is , which indicates that the key storage provider's default export policy is set. - class. - + class. + ]]> @@ -225,11 +225,11 @@ Gets or sets the key creation options. An object that specifies options for creating keys. The default value is , which indicates that the key storage provider's default key creation options are set. - object defines options that are used when you create a new object. These options determine whether the key is created in the user or machine key store, and whether a new key should overwrite an existing key. By default, if is not specified, the key is created in the user store. - + object defines options that are used when you create a new object. These options determine whether the key is created in the user or machine key store, and whether a new key should overwrite an existing key. By default, if is not specified, the key is created in the user store. + ]]> @@ -286,11 +286,11 @@ Gets or sets the cryptographic operations that apply to the current key. A bitwise combination of one or more enumeration values that specify key usage. The default value is , which indicates that the key storage provider's default key usage is set. - object. It specifies the usages (such as encryption/decryption, signing/verification, and secret agreement generation) that will be enabled on the new key. - + object. It specifies the usages (such as encryption/decryption, signing/verification, and secret agreement generation) that will be enabled on the new key. + ]]> @@ -347,19 +347,19 @@ Enables a object to be created with additional properties that are set before the key is finalized. A collection object that contains any additional parameters that you must set on a object during key creation. - class enables you to create a new object and initialize it with common properties. If you must set additional properties on the key during its creation, follow these steps: - -1. Create a new object for each additional property that you must set. - -2. Call the property to obtain an empty object. - -3. Add the objects to the object. - -4. Call the method overload and pass the initialized object to it. - + class enables you to create a new object and initialize it with common properties. If you must set additional properties on the key during its creation, follow these steps: + +1. Create a new object for each additional property that you must set. + +2. Call the property to obtain an empty object. + +3. Add the objects to the object. + +4. Call the method overload and pass the initialized object to it. + ]]> @@ -420,11 +420,11 @@ Gets or sets the window handle that should be used as the parent window for dialog boxes that are created by Cryptography Next Generation (CNG) classes. The HWND of the parent window that is used for CNG dialog boxes. - diff --git a/xml/System.Security.Cryptography/CngProvider.xml b/xml/System.Security.Cryptography/CngProvider.xml index 8374f8ce906..e36e64299b2 100644 --- a/xml/System.Security.Cryptography/CngProvider.xml +++ b/xml/System.Security.Cryptography/CngProvider.xml @@ -63,22 +63,22 @@ Encapsulates the name of a key storage provider (KSP) for use with Cryptography Next Generation (CNG) objects. - class is a utility class. It consists of static properties, comparison methods, and a private, internally maintained string that specifies a key storage provider. - - The static properties return objects. Each object's internal string is initialized to the provider name that corresponds to the name of the static property. - - You can also use this class to create objects for provider types that are not covered by the static properties. - - Several CNG classes (such as ) accept objects through a `provider` parameter. When the class receives the object, it retrieves the embedded provider name by calling the object's property. - - Therefore, serves as an enumeration of well-known providers. It lets you identify a provider by using a strongly typed value instead of a string. + class is a utility class. It consists of static properties, comparison methods, and a private, internally maintained string that specifies a key storage provider. + + The static properties return objects. Each object's internal string is initialized to the provider name that corresponds to the name of the static property. + + You can also use this class to create objects for provider types that are not covered by the static properties. + + Several CNG classes (such as ) accept objects through a `provider` parameter. When the class receives the object, it retrieves the embedded provider name by calling the object's property. + + Therefore, serves as an enumeration of well-known providers. It lets you identify a provider by using a strongly typed value instead of a string. > [!NOTE] > CNG classes don't work on non-Windows platforms. - + ]]> @@ -125,13 +125,13 @@ The name of the key storage provider (KSP) to initialize. Initializes a new instance of the class. - class internally maintain the provider name specified by the `provider` parameter. - - The primary purpose of this constructor is to provide a method for creating objects for KSPs that are not represented by the static properties of the class. This capacity enables future .NET Framework releases, service packs, and third-party developers to add new providers, which can be accessed just like the providers that are currently available. - + class internally maintain the provider name specified by the `provider` parameter. + + The primary purpose of this constructor is to provide a method for creating objects for KSPs that are not represented by the static properties of the class. This capacity enables future .NET Framework releases, service packs, and third-party developers to add new providers, which can be accessed just like the providers that are currently available. + ]]> The parameter is . diff --git a/xml/System.Security.Cryptography/CryptoAPITransform.xml b/xml/System.Security.Cryptography/CryptoAPITransform.xml index 8e6d3ff40f1..ecc8cfd6ee5 100644 --- a/xml/System.Security.Cryptography/CryptoAPITransform.xml +++ b/xml/System.Security.Cryptography/CryptoAPITransform.xml @@ -32,15 +32,15 @@ Performs a cryptographic transformation of data. This class cannot be inherited. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -70,15 +70,15 @@ Gets a value indicating whether the current transform can be reused. Always . - property to determine if the current transform can be reused. This code example is part of a larger example provided for the class. - + property to determine if the current transform can be reused. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet2"::: + ]]> Cryptographic Services @@ -109,15 +109,15 @@ if multiple blocks can be transformed; otherwise, . - property to determine if multiple blocks can be transformed. This code example is part of a larger example provided for the class. - + property to determine if multiple blocks can be transformed. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet3"::: + ]]> Cryptographic Services @@ -150,22 +150,22 @@ Releases all resources used by the method. - . - - Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). - - - -## Examples - The following code example demonstrates how to call the method to release the resources used by the current transform. This code example is part of a larger example provided for the class. - + . + + Calling `Dispose` allows the resources used by the to be reallocated for other purposes. For more information about `Dispose`, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged). + + + +## Examples + The following code example demonstrates how to call the method to release the resources used by the current transform. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet7"::: + ]]> @@ -198,16 +198,16 @@ Releases all resources used by the current instance of the class. - . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - - For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + + For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + > [!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. - +> 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. + ]]> @@ -257,15 +257,15 @@ Gets the input block size. The input block size in bytes. - property to retrieve the input block size. This code example is part of a larger example provided for the class. - + property to retrieve the input block size. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet4"::: + ]]> Cryptographic Services @@ -325,15 +325,15 @@ Gets the output block size. The output block size in bytes. - property to retrieve the output block size. This code example is part of a larger example provided for the class. - + property to retrieve the output block size. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet6"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet6"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet6"::: + ]]> Cryptographic Services @@ -369,11 +369,11 @@ Resets the internal state of so that it can be used again to do a different encryption or decryption. - method is called automatically when you call TransformFinalBlock. The `Reset` method is not called when, for example, the encrypted input data is garbage and cannot be decrypted. In this case, an exception is thrown and `Reset` is not called. You can choose to manually call the `Reset` method in this case. - + method is called automatically when you call TransformFinalBlock. The `Reset` method is not called when, for example, the encrypted input data is garbage and cannot be decrypted. In this case, an exception is thrown and `Reset` is not called. You can choose to manually call the `Reset` method in this case. + ]]> @@ -455,21 +455,21 @@ This member is an explicit interface member implementation. It can be used only Computes the transformation for the specified region of the input byte array and copies the resulting transformation to the specified region of the output byte array. The number of bytes written. - method to transform the bytes from `currentPosition` in the `sourceBytes` array, writing the bytes to the `targetBytes` array. This code example is part of a larger example provided for the class. - + method to transform the bytes from `currentPosition` in the `sourceBytes` array, writing the bytes to the `targetBytes` array. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet8"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . The length of the input buffer is less than the sum of the input offset and the input count. @@ -515,26 +515,26 @@ This member is an explicit interface member implementation. It can be used only Computes the transformation for the specified region of the specified byte array. The computed transformation. - method to transform the final block of bytes. This code example is part of a larger example provided for the class. - + method to transform the final block of bytes. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Cryptography.CryptoAPITransform/CPP/members.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptoAPITransform/Overview/members.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptoAPITransform/Overview/members.vb" id="Snippet9"::: + ]]> The parameter is . - The parameter is less than zero. - - -or- - - The parameter is less than zero. - - -or- - + The parameter is less than zero. + + -or- + + The parameter is less than zero. + + -or- + The length of the input buffer is less than the sum of the input offset and the input count. The padding is invalid. The parameter is out of range. This parameter requires a non-negative number. diff --git a/xml/System.Security.Cryptography/CryptoStream.xml b/xml/System.Security.Cryptography/CryptoStream.xml index 51d8652ce32..0cd889e0440 100644 --- a/xml/System.Security.Cryptography/CryptoStream.xml +++ b/xml/System.Security.Cryptography/CryptoStream.xml @@ -276,7 +276,7 @@ The current position in the stream is updated when the asynchronous read or writ Multiple simultaneous asynchronous requests render the request completion order uncertain. -Use the property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from `BeginRead`. Errors that occur during an asynchronous read request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling `EndRead`. @@ -359,7 +359,7 @@ If a stream is writable, writing at the end of the stream expands the stream. The current position in the stream is updated when you issue the asynchronous read or write, not when the I/O operation completes. Multiple simultaneous asynchronous requests render the request completion order uncertain. -Use the property to determine whether the current instance supports writing. +Use the property to determine whether the current instance supports writing. If a stream is closed or you pass an invalid argument, exceptions are thrown immediately from `BeginWrite`. Errors that occur during an asynchronous write request, such as a disk failure during the I/O request, occur on the thread pool thread and throw exceptions when calling `EndWrite`. @@ -1091,7 +1091,7 @@ Flushing the stream will not flush its underlying encoder unless you explicitly You must preface your call to with the `await` (C#) or `Await` (Visual Basic) operator to suspend execution of the method until the task is complete. For more information, see [Asynchronous programming (C#)](/dotnet/csharp/async) or [Asynchronous programming with Async and Await (Visual Basic)](/dotnet/visual-basic/programming-guide/concepts/async/). -If the operation is canceled before it completes, the returned task contains the value for the property. +If the operation is canceled before it completes, the returned task contains the value for 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 . @@ -1521,7 +1521,7 @@ This property exists only to support inheritance from , a You must preface your call to with the `await` (C#) or `Await` (Visual Basic) operator to suspend execution of the method until the task is complete. For more information, see [Asynchronous programming (C#)](/dotnet/csharp/async) or [Asynchronous programming with Async and Await (Visual Basic)](/dotnet/visual-basic/programming-guide/concepts/async/). -If the operation is canceled before it completes, the returned task contains the value for the property. +If the operation is canceled before it completes, the returned task contains the value for 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 . @@ -1577,7 +1577,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property to determine whether the current instance supports reading. +Use the property to determine whether the current instance supports reading. If you attempt to manipulate the stream after the stream has been closed, an might be thrown. @@ -1904,7 +1904,7 @@ This member is an explicit interface member implementation. It can be used only You must preface your call to with the `await` (C#) or `Await` (Visual Basic) operator to suspend execution of the method until the task is complete. For more information, see [Asynchronous programming (C#)](/dotnet/csharp/async) or [Asynchronous programming with Async and Await (Visual Basic)](/dotnet/visual-basic/programming-guide/concepts/async/). -If the operation is canceled before it completes, the returned task contains the value for the property. +If the operation is canceled before it completes, the returned task contains the value for 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 . @@ -1962,7 +1962,7 @@ This method stores in the task it returns all non-usage exceptions that the meth property to determine whether the current instance supports writing. +Use the property to determine whether the current instance supports writing. ]]> diff --git a/xml/System.Security.Cryptography/CryptographicException.xml b/xml/System.Security.Cryptography/CryptographicException.xml index 290879c4be9..3cbe8808325 100644 --- a/xml/System.Security.Cryptography/CryptographicException.xml +++ b/xml/System.Security.Cryptography/CryptographicException.xml @@ -92,7 +92,7 @@ ## Examples The following code example demonstrates how to use members of the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptographicException/Overview/cryptographicexceptionmembers.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicException/Overview/cryptographicexceptionmembers.vb" id="Snippet2"::: @@ -227,7 +227,7 @@ constructor accepts a system `HRESULT` error code and sets the property to a localized message that corresponds to the `HRESULT`. + The constructor accepts a system `HRESULT` error code and sets the property to a localized message that corresponds to the `HRESULT`. The following table shows the initial property values for an instance of . @@ -433,7 +433,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Security.Cryptography/CryptographicUnexpectedOperationException.xml b/xml/System.Security.Cryptography/CryptographicUnexpectedOperationException.xml index f74d6c436db..3fdac4bc6dd 100644 --- a/xml/System.Security.Cryptography/CryptographicUnexpectedOperationException.xml +++ b/xml/System.Security.Cryptography/CryptographicUnexpectedOperationException.xml @@ -69,21 +69,21 @@ The exception that is thrown when an unexpected operation occurs during a cryptographic operation. - uses the HRESULT CORSEC_E_CRYPTO_UNEX_OPER, which has the value 0x80131431. - - For a list of initial property values for an instance of , see the constructor. - - - -## Examples - The following code example demonstrates how to use members of the class. - + uses the HRESULT CORSEC_E_CRYPTO_UNEX_OPER, which has the value 0x80131431. + + For a list of initial property values for an instance of , see the constructor. + + + +## Examples + The following code example demonstrates how to use members of the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.vb" id="Snippet2"::: + ]]> @@ -140,24 +140,24 @@ Initializes a new instance of the class with default properties. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - - - -## Examples - The following code example demonstrates how to construct a with no parameters. This code example is part of a larger example provided for the class. - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + + + +## Examples + The following code example demonstrates how to construct a with no parameters. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.vb" id="Snippet1"::: + ]]> @@ -206,24 +206,24 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string.| - - - -## Examples - The following code example demonstrates how to construct a using a custom error message. This code example is part of a larger example provided for the class. - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string.| + + + +## Examples + The following code example demonstrates how to construct a using a custom error message. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.vb" id="Snippet3"::: + ]]> @@ -287,11 +287,11 @@ The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -342,26 +342,26 @@ 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.| - - - -## Examples - The following code example demonstrates how to construct a using a custom error message and an inner exception. This code example is part of a larger example provided for the class. - + 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.| + + + +## Examples + The following code example demonstrates how to construct a using a custom error message and an inner exception. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.vb" id="Snippet4"::: + ]]> @@ -421,24 +421,24 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message in the specified format. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string.| - - - -## Examples - The following code example demonstrates how to construct a using a time format and the current date. This code example is part of a larger example provided for the class. - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string.| + + + +## Examples + The following code example demonstrates how to construct a using a time format and the current date. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CryptographicUnexpectedOperationException/Overview/members.vb" id="Snippet5"::: + ]]> diff --git a/xml/System.Security.Cryptography/CspKeyContainerInfo.xml b/xml/System.Security.Cryptography/CspKeyContainerInfo.xml index a2b78f820cf..473f7012820 100644 --- a/xml/System.Security.Cryptography/CspKeyContainerInfo.xml +++ b/xml/System.Security.Cryptography/CspKeyContainerInfo.xml @@ -80,7 +80,7 @@ ## Examples The following code example creates a key container and retrieves information about that container. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CspKeyContainerInfo/Overview/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CspKeyContainerInfo/Overview/sample.vb" id="Snippet1"::: @@ -495,7 +495,7 @@ property is derived from the field of the object that was used to initialize the object. + The value of the property is derived from the field of the object that was used to initialize the object. An exchange key is an asymmetric key pair used to encrypt session keys so that they can be safely stored and exchanged with other users. The value specifies an exchange key. This value corresponds to the `AT_KEYEXCHANGE` value used in the unmanaged Microsoft Cryptographic API (CAPI). diff --git a/xml/System.Security.Cryptography/CspParameters.xml b/xml/System.Security.Cryptography/CspParameters.xml index daae13a8e25..2905e86fd2a 100644 --- a/xml/System.Security.Cryptography/CspParameters.xml +++ b/xml/System.Security.Cryptography/CspParameters.xml @@ -513,7 +513,7 @@ property to specify a object that manages the creation of discretionary access control lists (DACLS) and system access control lists (SACLS) for a container. + Use the property to specify a object that manages the creation of discretionary access control lists (DACLS) and system access control lists (SACLS) for a container. ]]> @@ -677,7 +677,7 @@ field initializes the property when you initialize a object with a object. + The field initializes the property when you initialize a object with a object. An exchange key is an asymmetric key pair used to encrypt session keys so that they can be safely stored and exchanged with other users. You can use the value (`1`) to specify an exchange key. This value corresponds to the `AT_KEYEXCHANGE` value used in the unmanaged Microsoft Cryptographic API (CAPI). @@ -750,7 +750,7 @@ property to supply a password for a smart card key. When you specify a password using this property, a password dialog box will not be presented to the user. + Use the property to supply a password for a smart card key. When you specify a password using this property, a password dialog box will not be presented to the user. ]]> @@ -802,9 +802,9 @@ property to specify a handle to the unmanaged parent window for a smart card password dialog box. When you specify a handle using this property, a smart card password dialog box will be presented to the user. + Use the property to specify a handle to the unmanaged parent window for a smart card password dialog box. When you specify a handle using this property, a smart card password dialog box will be presented to the user. - You can avoid presenting a smart card password dialog box by explicitly specifying a password by using the property. + You can avoid presenting a smart card password dialog box by explicitly specifying a password by using the property. ]]> diff --git a/xml/System.Security.Cryptography/DESCryptoServiceProvider.xml b/xml/System.Security.Cryptography/DESCryptoServiceProvider.xml index 44102045c07..048c9b15eca 100644 --- a/xml/System.Security.Cryptography/DESCryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/DESCryptoServiceProvider.xml @@ -83,7 +83,7 @@ ## Examples The following code example uses (an implementation of ) with the specified key () and initialization vector () to encrypt a file specified by `inName`. It then outputs the encrypted result to the file specified by `outName`. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/DESCryptoServiceProvider/Overview/source.vb" id="Snippet1"::: @@ -334,7 +334,7 @@ property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . + If the current property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . Use the overload with the same signature to decrypt the result of this method. diff --git a/xml/System.Security.Cryptography/DSACng.xml b/xml/System.Security.Cryptography/DSACng.xml index d081b5988fd..6b8458290ca 100644 --- a/xml/System.Security.Cryptography/DSACng.xml +++ b/xml/System.Security.Cryptography/DSACng.xml @@ -674,7 +674,7 @@ An error occurred during signature creation. object is disposed if the key is reset, for instance by changing the property, by using the method to create a new key, or by disposing the parent object. Therefore, you should ensure that the key object is no longer used in these cases. + The object is disposed if the key is reset, for instance by changing the property, by using the method to create a new key, or by disposing the parent object. Therefore, you should ensure that the key object is no longer used in these cases. This object is not the same as the object passed to the constructor, if that constructor was used. However, it will point to the same CNG key. diff --git a/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml index ef098f4c772..d029767d022 100644 --- a/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/DSACryptoServiceProvider.xml @@ -446,9 +446,9 @@ property to retrieve additional information about a cryptographic key pair. The returned object describes whether the key is exportable, and specifies the key container name, information about the provider, and other information. + Use the property to retrieve additional information about a cryptographic key pair. The returned object describes whether the key is exportable, and specifies the key container name, information about the provider, and other information. - In cases where a random key is generated, a key container will not be created until you call a method that uses the key. Some properties of the object returned by the property will throw a if a key container has not been created. To make sure that a key container has been created, call a method such as , , , , and so on, before you call the property. + In cases where a random key is generated, a key container will not be created until you call a method that uses the key. Some properties of the object returned by the property will throw a if a key container has not been created. To make sure that a key container has been created, call a method such as , , , , and so on, before you call the property. ]]> @@ -1079,7 +1079,7 @@ ## Remarks This algorithm supports key lengths from 512 bits to 1024 bits in increments of 64 bits. - The class does not allow you to change key sizes using the property. Any value written to this property will fail to update the property without error. To change the key size, use one of the constructor overloads. + The class does not allow you to change key sizes using the property. Any value written to this property will fail to update the property without error. To change the key size, use one of the constructor overloads. ]]> @@ -1257,7 +1257,7 @@ This algorithm supports key lengths from 512 bits to 1024 bits in increments of class can be initialized either with a public key only or with both a public and private key. Use the property to determine whether the current instance contains only a public key or both a public and private key. + The class can be initialized either with a public key only or with both a public and private key. Use the property to determine whether the current instance contains only a public key or both a public and private key. ]]> @@ -1648,7 +1648,7 @@ This algorithm supports key lengths from 512 bits to 1024 bits in increments of flag to a object. The property applies to all code in the current application domain, while the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. + Setting this property to true is equivalent to passing the flag to a object. The property applies to all code in the current application domain, while the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. ]]> diff --git a/xml/System.Security.Cryptography/ECCurve.xml b/xml/System.Security.Cryptography/ECCurve.xml index d2a7f4eedfa..e9259eab443 100644 --- a/xml/System.Security.Cryptography/ECCurve.xml +++ b/xml/System.Security.Cryptography/ECCurve.xml @@ -67,11 +67,11 @@ Represents an elliptic curve. - field to determine whether the curve is a named curve or an explicit curve (either a prime or a characteristic 2 curve). - + field to determine whether the curve is a named curve or an explicit curve (either a prime or a characteristic 2 curve). + ]]> @@ -713,13 +713,13 @@ Gets the identifier of a named curve. The identifier of a named curve. - property directly. Instead, to create a named curve, use the , the , or the methods. - - On some systems, the property is the primary referenced identifier, while on others it's the property. Manually creating an object with mismatched values may produce undesirable results. - + property directly. Instead, to create a named curve, use the , the , or the methods. + + On some systems, the property is the primary referenced identifier, while on others it's the property. Manually creating an object with mismatched values may produce undesirable results. + ]]> @@ -766,11 +766,11 @@ The order of the curve. Applies only to explicit curves. - field represents the order of the group generated by G = (x,y). - + field represents the order of the group generated by G = (x,y). + ]]> diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml b/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml index 1ceec72b7dd..a0c47b16c03 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanCng.xml @@ -1196,7 +1196,7 @@ This instance represents only a public key. or value is set in the property. + This property is used by Cryptography Next Generation (CNG) objects only if the or value is set in the property. This property accepts the following algorithms: , , , , and . @@ -1262,7 +1262,7 @@ This instance represents only a public key. value is set in the property, and the property is `false`. By default, the value is `null`. + This property applies only when the value is set in the property, and the property is `false`. By default, the value is `null`. ]]> @@ -1612,7 +1612,7 @@ Because key sizes do not uniquely identify elliptic curves, the use of the prope value is set in the property. By default, it is `null`. + This value is used for key derivation if the value is set in the property. By default, it is `null`. ]]> @@ -1802,7 +1802,7 @@ Because key sizes do not uniquely identify elliptic curves, the use of the prope property is set to one of the following values: + This value is used for key derivation if the property is set to one of the following values: - @@ -1867,7 +1867,7 @@ Because key sizes do not uniquely identify elliptic curves, the use of the prope property is set to . By default, the value is `null`. + This value is used for key derivation if the property is set to . By default, the value is `null`. ]]> @@ -2143,7 +2143,7 @@ Because key sizes do not uniquely identify elliptic curves, the use of the prope ## Remarks -This value is used for key derivation if the property is set to . By default, the value is `false`. +This value is used for key derivation if the property is set to . By default, the value is `false`. ]]> diff --git a/xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml b/xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml index 7774d58b2e9..629cf2a4a0a 100644 --- a/xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml +++ b/xml/System.Security.Cryptography/ECDiffieHellmanKeyDerivationFunction.xml @@ -40,13 +40,13 @@ Specifies the key derivation function that the class will use to convert secret agreements into key material. - method. - - The property uses this enumeration to get the key derivation function for the class. - + method. + + The property uses this enumeration to get the key derivation function for the class. + ]]> diff --git a/xml/System.Security.Cryptography/ECDsaCng.xml b/xml/System.Security.Cryptography/ECDsaCng.xml index 5cfc8fd9fed..9cbaaf90a56 100644 --- a/xml/System.Security.Cryptography/ECDsaCng.xml +++ b/xml/System.Security.Cryptography/ECDsaCng.xml @@ -1228,7 +1228,7 @@ but that is not reflected in this property. property, and then signing the result. + This method generates a signature for the specified data by hashing the input data using the property, and then signing the result. The flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. @@ -1293,7 +1293,7 @@ but that is not reflected in this property. property, and then signing the result. + This method generates a signature for the specified data stream by hashing the input data using the property, and then signing the result. The flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. @@ -1362,7 +1362,7 @@ but that is not reflected in this property. property, and then signing the result + This method generates a signature for the specified data by hashing the input data using the property, and then signing the result The flag is required if the Cryptography Next Generation (CNG) key is not randomly generated by the object. @@ -1807,7 +1807,7 @@ but that is not reflected in this property. property, and then signing the result. + This method generates a signature for the given data by hashing the input data using the property, and then signing the result. ]]> @@ -1872,7 +1872,7 @@ but that is not reflected in this property. property before verification. + This method hashes the input data by using the property before verification. ]]> @@ -1941,7 +1941,7 @@ but that is not reflected in this property. property before verification. + This method hashes the input data by using the property before verification. ]]> diff --git a/xml/System.Security.Cryptography/HashAlgorithm.xml b/xml/System.Security.Cryptography/HashAlgorithm.xml index b17dcf172e1..b34716be923 100644 --- a/xml/System.Security.Cryptography/HashAlgorithm.xml +++ b/xml/System.Security.Cryptography/HashAlgorithm.xml @@ -925,7 +925,7 @@ This method is obsolete in .NET 5 and later versions. property is a byte array; the property is a value that represent bits. Therefore, the number of elements in is one-eighth the size of . + The property is a byte array; the property is a value that represent bits. Therefore, the number of elements in is one-eighth the size of . ]]> @@ -1191,7 +1191,7 @@ Derived types should override this method to avoid the intermediate data copying ## Remarks The hash algorithm specifies the size of the hash code. For example, uses a hash size of 160 bits. - This field is accessed through the property. + This field is accessed through the property. ]]> @@ -1253,7 +1253,7 @@ Derived types should override this method to avoid the intermediate data copying property. + This field is accessed through the property. ]]> @@ -1593,7 +1593,7 @@ For more information about Dispose and Finalize, see [Cleaning Up Unmanaged Reso ## Remarks You must call the method before calling the method. You must call both methods before you retrieve the final hash value. - To retrieve the final hash value after calling the method, get the byte array contained within the property. + To retrieve the final hash value after calling the method, get the byte array contained within the property. Calling the method with different input and output arrays results in an . @@ -1685,7 +1685,7 @@ For more information about Dispose and Finalize, see [Cleaning Up Unmanaged Reso ## Remarks You must call the method after calling the method but before you retrieve the final hash value. - Note that the return value of this method is not the hash value, but only a copy of the hashed part of the input data. To retrieve the final hashed value after calling the method, get the byte array contained in the property. + Note that the return value of this method is not the hash value, but only a copy of the hashed part of the input data. To retrieve the final hashed value after calling the method, get the byte array contained in the property. diff --git a/xml/System.Security.Cryptography/HashAlgorithmName.xml b/xml/System.Security.Cryptography/HashAlgorithmName.xml index a37fe0063a7..94a08fb73fa 100644 --- a/xml/System.Security.Cryptography/HashAlgorithmName.xml +++ b/xml/System.Security.Cryptography/HashAlgorithmName.xml @@ -71,7 +71,7 @@ structure includes some static properties that return predefined hash algorithm names, as well as a property that can represent a custom hash algorithm name as a strongly-typed string. Hash algorithm names are case-sensitive. + The structure includes some static properties that return predefined hash algorithm names, as well as a property that can represent a custom hash algorithm name as a strongly-typed string. Hash algorithm names are case-sensitive. Asymmetric algorithms implemented using Microsoft's CNG (Cryptographic Next Generation) API interpret the underlying string value as a [CNG algorithm identifier](/windows/win32/seccng/cng-algorithm-identifiers). @@ -868,7 +868,7 @@ May be `null` or empty to indicate that no hash algorithm is applicable. method returns the property, if it has been assigned. Otherwise, it returns . + The method returns the property, if it has been assigned. Otherwise, it returns . ]]> diff --git a/xml/System.Security.Cryptography/KeyNumber.xml b/xml/System.Security.Cryptography/KeyNumber.xml index dae2ab18e65..cef086d7bb7 100644 --- a/xml/System.Security.Cryptography/KeyNumber.xml +++ b/xml/System.Security.Cryptography/KeyNumber.xml @@ -68,11 +68,11 @@ property to inspect a key type or with the field to specify a key type. + Use the `KeyNumber` enumeration with the property to inspect a key type or with the field to specify a key type. ## Examples The following code example demonstrates how to use the enumeration to specify a key type for an object. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/CspParameters/KeyNumber/sample.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/CspParameters/KeyNumber/sample.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography/KeySizes.xml b/xml/System.Security.Cryptography/KeySizes.xml index 0d9e5715b01..6dcb64b9964 100644 --- a/xml/System.Security.Cryptography/KeySizes.xml +++ b/xml/System.Security.Cryptography/KeySizes.xml @@ -65,7 +65,7 @@ ## Examples The following example shows the use of members of the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/KeySizes/Overview/members.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/KeySizes/Overview/members.vb" id="Snippet1"::: @@ -181,7 +181,7 @@ property. This code example is part of a larger example provided for the class. + The following code shows how to retrieve the use of the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/KeySizes/Overview/members.cs" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/KeySizes/Overview/members.vb" id="Snippet4"::: @@ -237,7 +237,7 @@ property. This code example is part of a larger example provided for the class. + The following code shows how to retrieve the use of the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/KeySizes/Overview/members.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/KeySizes/Overview/members.vb" id="Snippet3"::: @@ -293,7 +293,7 @@ property. This code example is part of a larger example provided for the class. + The following code shows how to retrieve the use of the property. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/KeySizes/Overview/members.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/KeySizes/Overview/members.vb" id="Snippet5"::: diff --git a/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml b/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml index b8aea914ff9..a067b333aaa 100644 --- a/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml +++ b/xml/System.Security.Cryptography/KeyedHashAlgorithm.xml @@ -487,7 +487,7 @@ Allows an to attempt to free resources and perfor ## Examples - The following code example demonstrates how to override the property to retrieve the key used in the current object. This code example is part of a larger example provided for the class. + The following code example demonstrates how to override the property to retrieve the key used in the current object. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/KeyedHashAlgorithm/Key/contosokeyedhash.cs" id="Snippet22"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/KeyedHashAlgorithm/Key/contosokeyedhash.vb" id="Snippet22"::: @@ -543,7 +543,7 @@ Allows an to attempt to free resources and perfor property. + This field is accessed through the property. ]]> diff --git a/xml/System.Security.Cryptography/MACTripleDES.xml b/xml/System.Security.Cryptography/MACTripleDES.xml index 5b18e58dd3a..f317237f834 100644 --- a/xml/System.Security.Cryptography/MACTripleDES.xml +++ b/xml/System.Security.Cryptography/MACTripleDES.xml @@ -358,7 +358,7 @@ ## Remarks Most plain text messages do not consist of a number of bytes that completely fill blocks. Often, there are not enough bytes to fill the last block. When this happens, a padding string is added to the text. For example, if the block length is 64 bits and the last block contains only 40 bits, 24 bits of padding are added. See for a description of specific modes. - This field is accessed through the property. + This field is accessed through the property. ]]> diff --git a/xml/System.Security.Cryptography/Oid.xml b/xml/System.Security.Cryptography/Oid.xml index 75db8d8b98c..1e888aa77dd 100644 --- a/xml/System.Security.Cryptography/Oid.xml +++ b/xml/System.Security.Cryptography/Oid.xml @@ -63,11 +63,11 @@ property is set to "1.3.6.1.5.5.7.3.4", the property, which is localized, is set automatically to "Secure Email". + Cryptographic object identifiers consist of a value/name pair. If one property in a pair is set to a known value, the other property is updated automatically to a corresponding value. For example, if the property is set to "1.3.6.1.5.5.7.3.4", the property, which is localized, is set automatically to "Secure Email". ## Examples The following code example shows how to use the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Oid/Overview/cryptography.oid.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/Oid/Overview/cryptography.oid.vb" id="Snippet1"::: @@ -383,7 +383,7 @@ ## Remarks -If one property is set to a known value, the value of the other property is updated automatically to a corresponding value. For example, if the property is set to "Secure Email", the property is set automatically to "1.3.6.1.5.5.7.3.4". +If one property is set to a known value, the value of the other property is updated automatically to a corresponding value. For example, if the property is set to "Secure Email", the property is set automatically to "1.3.6.1.5.5.7.3.4". In .NET 5 and later versions, this property is *init only*, meaning that its value can't be changed once it's been set. @@ -562,7 +562,7 @@ In .NET 5 and later versions, this property is *init only*, meaning that its val ## Remarks -If one property is set to a known value, the value of the other property is updated automatically to a corresponding value. For example, if the property is set to "1.3.6.1.5.5.7.3.4", the property is set automatically to "Secure Email". +If one property is set to a known value, the value of the other property is updated automatically to a corresponding value. For example, if the property is set to "1.3.6.1.5.5.7.3.4", the property is set automatically to "Secure Email". In .NET 5 and later versions, this property is *init only*, meaning that its value can't be changed once it's been set. diff --git a/xml/System.Security.Cryptography/OidCollection.xml b/xml/System.Security.Cryptography/OidCollection.xml index 83af92cbc68..9cb77e50e2d 100644 --- a/xml/System.Security.Cryptography/OidCollection.xml +++ b/xml/System.Security.Cryptography/OidCollection.xml @@ -76,7 +76,7 @@ ## Examples The following code example shows how to use the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Oid/Overview/cryptography.oid.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/Oid/Overview/cryptography.oid.vb" id="Snippet1"::: @@ -511,7 +511,7 @@ object from an object, if you know its location. You can use the property to retrieve an object if you know the value of the object's property or property. + Use this method to retrieve an object from an object, if you know its location. You can use the property to retrieve an object if you know the value of the object's property or property. @@ -582,7 +582,7 @@ object from an object if you know the value of the or property of the object. You can use the property to retrieve an object if you know its location in the collection. + Use this property to retrieve an object from an object if you know the value of the or property of the object. You can use the property to retrieve an object if you know its location in the collection. @@ -644,7 +644,7 @@ is not thread safe. Derived classes can provide their own synchronized version of the class using this property. The synchronizing code must perform operations on the property of the object, not directly on the object itself. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might simultaneously be modifying the object. + is not thread safe. Derived classes can provide their own synchronized version of the class using this property. The synchronizing code must perform operations on the property of the object, not directly on the object itself. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might simultaneously be modifying the object. ]]> diff --git a/xml/System.Security.Cryptography/OidEnumerator.xml b/xml/System.Security.Cryptography/OidEnumerator.xml index b9602f83573..3801ef4a637 100644 --- a/xml/System.Security.Cryptography/OidEnumerator.xml +++ b/xml/System.Security.Cryptography/OidEnumerator.xml @@ -73,7 +73,7 @@ ## Examples The following code example shows how to use the class. - + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Oid/Overview/cryptography.oid.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/Oid/Overview/cryptography.oid.vb" id="Snippet1"::: @@ -127,7 +127,7 @@ method must be called to advance the enumerator to the first element of the collection before reading the value of the property; otherwise, returns `null` or throws an exception. + After an enumerator is created, the method must be called to advance the enumerator to the first element of the collection before reading the value of the property; otherwise, returns `null` or throws an exception. also returns `null` or throws an exception if the last call to returns `false`, which indicates that the end of the collection has been reached. diff --git a/xml/System.Security.Cryptography/RC2.xml b/xml/System.Security.Cryptography/RC2.xml index 6fb31b26c97..6a3da889659 100644 --- a/xml/System.Security.Cryptography/RC2.xml +++ b/xml/System.Security.Cryptography/RC2.xml @@ -403,7 +403,7 @@ property. + This field is accessed through the property. ]]> diff --git a/xml/System.Security.Cryptography/RC2CryptoServiceProvider.xml b/xml/System.Security.Cryptography/RC2CryptoServiceProvider.xml index 0c172890582..d42738d34a2 100644 --- a/xml/System.Security.Cryptography/RC2CryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/RC2CryptoServiceProvider.xml @@ -601,13 +601,13 @@ property allows you to interoperate with an existing application that uses an 11-byte-long, zero-value salt. For most scenarios, you should not use a salt with an key. + The property allows you to interoperate with an existing application that uses an 11-byte-long, zero-value salt. For most scenarios, you should not use a salt with an key. ## Examples - The following code example sets the property to `true`, and then encrypts and decrypts a value. - + The following code example sets the property to `true`, and then encrypts and decrypts a value. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RC2CryptoServiceProvider/UseSalt/example.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RC2CryptoServiceProvider/UseSalt/example.vb" id="Snippet1"::: diff --git a/xml/System.Security.Cryptography/RSACng.xml b/xml/System.Security.Cryptography/RSACng.xml index 48daec9fd78..0815a34d09e 100644 --- a/xml/System.Security.Cryptography/RSACng.xml +++ b/xml/System.Security.Cryptography/RSACng.xml @@ -949,7 +949,7 @@ any already open key is unaffected by this method. object is disposed if the key is reset, for instance by changing the property, by using the to create a new key, or by disposing of the parent object. Therefore, you should ensure that the key object is no longer used in these cases. + The returned object is disposed if the key is reset, for instance by changing the property, by using the to create a new key, or by disposing of the parent object. Therefore, you should ensure that the key object is no longer used in these cases. This object is not the same as the object passed to the constructor, if that constructor was used. However, it will point to the same CNG key. diff --git a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml index 0e349248068..14e7e087531 100644 --- a/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/RSACryptoServiceProvider.xml @@ -482,9 +482,9 @@ If no key is loaded via the property to retrieve additional information about a cryptographic key pair. The returned object describes whether the key is exportable, and specifies the key container name, information about the provider, and other information. + Use the property to retrieve additional information about a cryptographic key pair. The returned object describes whether the key is exportable, and specifies the key container name, information about the provider, and other information. - In cases where a random key is generated, a key container will not be created until you call a method that uses the key. Some properties of the object returned by the property will throw a if a key container has not been created. To make sure that a key container has been created, call a method such as , , , , and so on, before you call the property. + In cases where a random key is generated, a key container will not be created until you call a method that uses the key. Some properties of the object returned by the property will throw a if a key container has not been created. To make sure that a key container has been created, call a method such as , , , , and so on, before you call the property. @@ -1619,7 +1619,7 @@ If no key is loaded via the instance. Windows CSPs enable key 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. - The class does not allow you to change key sizes using the property. Any value written to this property will fail to update the property without error. To change the key size, use one of the constructor overloads. + The class does not allow you to change key sizes using the property. Any value written to this property will fail to update the property without error. To change the key size, use one of the constructor overloads. ]]> @@ -1732,9 +1732,9 @@ The supported RSA key sizes depend on the available cryptographic service provid ## Remarks Use this property to persist a key in a key container. - The property is automatically set to `true` when you specify a key container name in the field of a object and use it to initialize an object by calling one of the constructors with a `parameters` parameter. + The property is automatically set to `true` when you specify a key container name in the field of a object and use it to initialize an object by calling one of the constructors with a `parameters` parameter. - The property has no effect if the object is created with a `null` key container name. + The property has no effect if the object is created with a `null` key container name. @@ -1806,7 +1806,7 @@ The supported RSA key sizes depend on the available cryptographic service provid class can be initialized either with a public key only or with both a public and private key. Use the property to determine whether the current instance contains only a public key or both a public and private key. + The class can be initialized either with a public key only or with both a public and private key. Use the property to determine whether the current instance contains only a public key or both a public and private key. ]]> @@ -2336,12 +2336,12 @@ The supported RSA key sizes depend on the available cryptographic service provid flag to a object. The property applies to all code in the current application domain, whereas the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. Setting affects the key store location only if is initialized with no parameters. + Setting this property to `true` is equivalent to passing the flag to a object. The property applies to all code in the current application domain, whereas the object applies only to classes that explicitly reference it. These settings are useful when impersonating or running under an account whose user profile is not loaded. Setting affects the key store location only if is initialized with no parameters. ## Examples - The following code example creates an object and sets the static property to use the machine key store instead of the user profile key store. + The following code example creates an object and sets the static property to use the machine key store instead of the user profile key store. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSACryptoServiceProvider/UseMachineKeyStore/example2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSACryptoServiceProvider/UseMachineKeyStore/example2.vb" id="Snippet2"::: diff --git a/xml/System.Security.Cryptography/RSAEncryptionPadding.xml b/xml/System.Security.Cryptography/RSAEncryptionPadding.xml index 6727b7c0ec3..1659a6997cf 100644 --- a/xml/System.Security.Cryptography/RSAEncryptionPadding.xml +++ b/xml/System.Security.Cryptography/RSAEncryptionPadding.xml @@ -194,7 +194,7 @@ object and the two objects have identical and property values. + `obj` is equal to the current instance if it is a object and the two objects have identical and property values. ]]> @@ -263,7 +263,7 @@ and property values. + `instance` and the current instance are equal if they have identical and property values. ]]> @@ -748,7 +748,7 @@ If the value of the objects are equal if their and property values are equal. + Two objects are equal if their and property values are equal. ]]> @@ -809,7 +809,7 @@ If the value of the objects are not equal if their and property values are not equal. + Two objects are not equal if their and property values are not equal. ]]> diff --git a/xml/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter.xml b/xml/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter.xml index 7aa68ec4afd..ad53e4c7601 100644 --- a/xml/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter.xml +++ b/xml/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter.xml @@ -324,8 +324,8 @@ property to retrieve an XML representation of the parameters. This code example is part of a larger example provided for the class. - + The following code example demonstrates how to call the property to retrieve an XML representation of the parameters. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Parameters/rsaencoder.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Parameters/rsaencoder.vb" id="Snippet12"::: diff --git a/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml b/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml index 7b4041eb480..c7556d68ef8 100644 --- a/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml +++ b/xml/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter.xml @@ -394,8 +394,8 @@ property to an field. This code example is part of a larger example provided for the class. - + The following code example demonstrates how to set the property to an field. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Parameters/rsaencoder.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Parameters/rsaencoder.vb" id="Snippet7"::: @@ -451,7 +451,7 @@ property to retrieve an XML representation of the parameters. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve an XML representation of the parameters. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Parameters/rsaencoder.cs" id="Snippet13"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Parameters/rsaencoder.vb" id="Snippet13"::: @@ -513,7 +513,7 @@ ## Examples - The following code example demonstrates how to set the property to a random number. This code example is part of a larger example provided for the class. + The following code example demonstrates how to set the property to a random number. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Parameters/rsaencoder.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeDeformatter/Parameters/rsaencoder.vb" id="Snippet6"::: diff --git a/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml b/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml index 0047a86d14e..d125f98c080 100644 --- a/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml +++ b/xml/System.Security.Cryptography/RSAPKCS1KeyExchangeFormatter.xml @@ -68,24 +68,24 @@ Creates the PKCS#1 key exchange data using . - to receive the key exchange and extract the secret information from it. - + to receive the key exchange and extract the secret information from it. + > [!CAUTION] -> We recommend that you do not attempt to create your own key exchange method from the basic functionality provided, because many details of the operation must be performed carefully in order for the key exchange to be successful. - - - -## Examples - The following example shows how to use the class to create an exchange key for a message recipient. - +> We recommend that you do not attempt to create your own key exchange method from the basic functionality provided, because many details of the operation must be performed carefully in order for the key exchange to be successful. + + + +## Examples + The following example shows how to use the class to create an exchange key for a message recipient. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.vb" id="Snippet1"::: + ]]> Cryptographic Services @@ -140,11 +140,11 @@ Initializes a new instance of the class. - method to set the key to be used for key exchange before calling . - + method to set the key to be used for key exchange before calling . + ]]> Cryptographic Services @@ -261,11 +261,11 @@ Creates the encrypted key exchange data from the specified input data. The encrypted key exchange data to be sent to the intended recipient. - @@ -331,19 +331,19 @@ Creates the encrypted key exchange data from the specified input data. The encrypted key exchange data to be sent to the intended recipient. - method to create an exchange key for a message recipient. This code example is part of a larger example provided for the class. - + method to create an exchange key for a message recipient. This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/RSAOAEPKeyExchangeFormatter/CreateKeyExchange/program.vb" id="Snippet2"::: + ]]> Cryptographic Services @@ -392,11 +392,11 @@ Gets the parameters for the PKCS #1 key exchange. An XML string containing the parameters of the PKCS #1 key exchange operation. - property returns an XML string that contains Uniform Resource Identifiers (URIs) that describe the parameters of the PKCS #1 key exchange operation. Note that the URIs are not guaranteed to point to active addresses. - + property returns an XML string that contains Uniform Resource Identifiers (URIs) that describe the parameters of the PKCS #1 key exchange operation. Note that the URIs are not guaranteed to point to active addresses. + ]]> Cryptographic Services @@ -452,11 +452,11 @@ Gets or sets the random number generator algorithm to use in the creation of the key exchange. The instance of a random number generator algorithm to use. - Cryptographic Services @@ -508,11 +508,11 @@ The instance of the algorithm that holds the public key. Sets the public key to use for encrypting the key exchange data. - . - + . + ]]> diff --git a/xml/System.Security.Cryptography/RSASignaturePadding.xml b/xml/System.Security.Cryptography/RSASignaturePadding.xml index 00f0f0739ef..82de6f2b7e4 100644 --- a/xml/System.Security.Cryptography/RSASignaturePadding.xml +++ b/xml/System.Security.Cryptography/RSASignaturePadding.xml @@ -140,11 +140,11 @@ if the specified object is equal to the current object; otherwise, . - instance and the property of the two objects is equal. - + instance and the property of the two objects is equal. + ]]> @@ -209,11 +209,11 @@ if the specified object is equal to the current object; otherwise, . - property of the two objects is equal. - + property of the two objects is equal. + ]]> @@ -363,13 +363,13 @@ if and are equal; otherwise, . - method defines the operation of the equality operator for values. - - Two values are equal if their property values are equal. - + method defines the operation of the equality operator for values. + + Two values are equal if their property values are equal. + ]]> @@ -426,13 +426,13 @@ if and are unequal; otherwise, . - method defines the operation of the inequality operator for values. - - Two values are unequal if their property values are different. - + method defines the operation of the inequality operator for values. + + Two values are unequal if their property values are different. + ]]> @@ -574,11 +574,11 @@ Returns the string representation of the current instance. The string representation of the current object. - method returns the value of the `RSASignaturePadding.Mode.ToString` method. - + method returns the value of the `RSASignaturePadding.Mode.ToString` method. + ]]> diff --git a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml index de0a3729aec..4eef4e096de 100644 --- a/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml +++ b/xml/System.Security.Cryptography/Rfc2898DeriveBytes.xml @@ -1002,7 +1002,7 @@ For more information about PBKDF2, see [RFC 2898](https://www.rfc-editor.org/inf ## Examples - The following example shows how to use the property to display the number of iterations used in the generation of the key. This code example is part of a larger example provided for the class. + The following example shows how to use the property to display the number of iterations used in the generation of the key. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/Rfc2898DeriveBytes/Overview/rfc28981.vb" id="Snippet3"::: diff --git a/xml/System.Security.Cryptography/RijndaelManaged.xml b/xml/System.Security.Cryptography/RijndaelManaged.xml index 8d04419b691..f1746426921 100644 --- a/xml/System.Security.Cryptography/RijndaelManaged.xml +++ b/xml/System.Security.Cryptography/RijndaelManaged.xml @@ -368,7 +368,7 @@ property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . + If the current property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . Use the overload with the same signature to decrypt the result of this method. ]]> diff --git a/xml/System.Security.Cryptography/StrongNameSignatureInformation.xml b/xml/System.Security.Cryptography/StrongNameSignatureInformation.xml index a7e99ab50e2..47bdb9679fd 100644 --- a/xml/System.Security.Cryptography/StrongNameSignatureInformation.xml +++ b/xml/System.Security.Cryptography/StrongNameSignatureInformation.xml @@ -118,11 +118,11 @@ Gets the public key that is used to verify the signature. The public key that is used to verify the signature. - is `false`. If the signature is valid, there will always be a key. - + is `false`. If the signature is valid, there will always be a key. + ]]> @@ -153,11 +153,11 @@ Gets the results of verifying the strong name signature. The result codes for signature verification. - property are two ways to determine whether an error occurred during verification. This property lists well-known errors that might occur. The property can be checked if the error is not covered by the enumeration. - + property are two ways to determine whether an error occurred during verification. This property lists well-known errors that might occur. The property can be checked if the error is not covered by the enumeration. + ]]> diff --git a/xml/System.Security.Cryptography/SymmetricAlgorithm.xml b/xml/System.Security.Cryptography/SymmetricAlgorithm.xml index cf2a3881756..89ac1b00764 100644 --- a/xml/System.Security.Cryptography/SymmetricAlgorithm.xml +++ b/xml/System.Security.Cryptography/SymmetricAlgorithm.xml @@ -68,7 +68,7 @@ class use a chaining mode called cipher block chaining (CBC), which requires a key () and an initialization vector () to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and the property to the same values that were used for encryption. For a symmetric algorithm to be useful, the secret key must be known only to the sender and the receiver. + The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key () and an initialization vector () to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and the property to the same values that were used for encryption. For a symmetric algorithm to be useful, the secret key must be known only to the sender and the receiver. , , , and are implementations of symmetric algorithms. @@ -79,7 +79,7 @@ ## Examples - The following code example uses the class with the specified property and initialization vector () to encrypt a file specified by `inName`, and outputs the encrypted result to the file specified by `outName`. The `desKey` and `desIV` parameters to the method are 8-byte arrays. You must have the high encryption pack installed to run this example. + The following code example uses the class with the specified property and initialization vector () to encrypt a file specified by `inName`, and outputs the encrypted result to the file specified by `outName`. The `desKey` and `desIV` parameters to the method are 8-byte arrays. You must have the high encryption pack installed to run this example. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/SymmetricAlgorithm/Overview/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/SymmetricAlgorithm/Overview/source.vb" id="Snippet1"::: @@ -250,7 +250,7 @@ ## Remarks The block size is the basic unit of data that can be encrypted or decrypted in one operation. Messages longer than the block size are handled as successive blocks; messages shorter than the block size must be padded with extra bits to reach the size of a block. Valid block sizes are determined by the symmetric algorithm used. - This field is accessed through the property. + This field is accessed through the property. ]]> @@ -656,7 +656,7 @@ We recommend that you specify the algorithm by calling the property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . + If the current property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . Use the overload with the same signature to decrypt the result of this method. @@ -2029,7 +2029,7 @@ This method's behavior is defined by property. + This field is accessed through the property. ]]> @@ -2405,9 +2405,9 @@ Allows an to attempt to free resources and perfor property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. + The property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. - The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key and an initialization vector to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and property to the same values that were used for encryption. + The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key and an initialization vector to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and property to the same values that were used for encryption. For a given secret key *k*, a simple block cipher that does not use an initialization vector will encrypt the same input block of plain text into the same output block of cipher text. If you have duplicate blocks within your plain text stream, you will have duplicate blocks within your cipher text stream. If unauthorized users know anything about the structure of a block of your plain text, they can use that information to decipher the known cipher text block and possibly recover your key. To combat this problem, information from the previous block is mixed into the process of encrypting the next block. Thus, the output of two identical plain text blocks is different. Because this technique uses the previous block to encrypt the next block, an initialization vector is needed to encrypt the first block of data. @@ -2471,7 +2471,7 @@ Allows an to attempt to free resources and perfor property. + This field is accessed through the property. ]]> @@ -2531,7 +2531,7 @@ Allows an to attempt to free resources and perfor property. + The secret key is used both for encryption and for decryption. For a symmetric algorithm to be successful, the secret key must be known only to the sender and the receiver. The valid key sizes are specified by the particular symmetric algorithm implementation and are listed in the property. If this property is `null` when it is used, the method is called to create a new random value. @@ -2589,7 +2589,7 @@ Allows an to attempt to free resources and perfor property. + The valid key sizes are specified by the particular symmetric algorithm implementation and are listed in the property. Changing the `KeySize` value resets the key and generates a new random key. This happens whenever the `KeySize` property setter is invoked (including when it's assigned the same value). @@ -2645,9 +2645,9 @@ Allows an to attempt to free resources and perfor property. + The valid key sizes are specified by the particular symmetric algorithm implementation and are listed in the property. - This field is accessed through the property. + This field is accessed through the property. ]]> @@ -2707,9 +2707,9 @@ Allows an to attempt to free resources and perfor property. + The secret key is used both for encryption and for decryption. For a symmetric algorithm to be successful, the secret key must be known only to the sender and the receiver. The valid key sizes are specified by the particular symmetric algorithm implementation and are listed in the property. - This field is accessed through the property. + This field is accessed through the property. ]]> @@ -2842,7 +2842,7 @@ Allows an to attempt to free resources and perfor ## Remarks The symmetric algorithm supports only block sizes that match an entry in this array. - This field is accessed through the property. + This field is accessed through the property. ]]> @@ -2975,7 +2975,7 @@ Allows an to attempt to free resources and perfor ## Remarks The symmetric algorithm supports only key sizes that match an entry in this array. - This field is accessed through the property. + This field is accessed through the property. ]]> @@ -3085,7 +3085,7 @@ Allows an to attempt to free resources and perfor ## Remarks See enumeration for a description of specific modes. - This field is accessed through the property. + This field is accessed through the property. ]]> @@ -3195,7 +3195,7 @@ Allows an to attempt to free resources and perfor ## Remarks Most plain text messages do not consist of a number of bytes that completely fill blocks. Often, there are not enough bytes to fill the last block. When this happens, a padding string is added to the text. For example, if the block length is 64 bits and the last block contains only 40 bits, 24 bits of padding are added. See the enumeration for a description of specific modes. - This field is accessed through the property. + This field is accessed through the property. ]]> diff --git a/xml/System.Security.Cryptography/ToBase64Transform.xml b/xml/System.Security.Cryptography/ToBase64Transform.xml index e7187129793..909427b638f 100644 --- a/xml/System.Security.Cryptography/ToBase64Transform.xml +++ b/xml/System.Security.Cryptography/ToBase64Transform.xml @@ -180,7 +180,7 @@ property to determine if the current transform can be reused. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to determine if the current transform can be reused. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/ToBase64Transform/Overview/members.vb" id="Snippet3"::: @@ -546,7 +546,7 @@ ## Examples - The following code example demonstrates how to call the property to retrieve the input block size of the current transform. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to retrieve the input block size of the current transform. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet5"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/ToBase64Transform/Overview/members.vb" id="Snippet5"::: @@ -610,7 +610,7 @@ ## Examples - The following code example demonstrates how to call the property to create a new byte array with the size of the output block size. This code example is part of a larger example provided for the class. + The following code example demonstrates how to call the property to create a new byte array with the size of the output block size. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography/ToBase64Transform/Overview/members.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Cryptography/ToBase64Transform/Overview/members.vb" id="Snippet6"::: diff --git a/xml/System.Security.Cryptography/TripleDESCng.xml b/xml/System.Security.Cryptography/TripleDESCng.xml index 82c52be070e..9f364faea4f 100644 --- a/xml/System.Security.Cryptography/TripleDESCng.xml +++ b/xml/System.Security.Cryptography/TripleDESCng.xml @@ -430,7 +430,7 @@ This method decrypts an encrypted message created using the overload with the same signature. > [!NOTE] -> If you've created the object using an existing persisted key and you want to make use of that key when decrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. +> If you've created the object using an existing persisted key and you want to make use of that key when decrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. ]]> @@ -572,7 +572,7 @@ Use this method to encrypt a message and then use the overload with the same signature to decrypt the result of this method. > [!NOTE] -> If you've created the object using an existing persisted key and you want to make use of that key when encrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. +> If you've created the object using an existing persisted key and you want to make use of that key when encrypting the message, you want to set the property and then call the parameterless overload instead; otherwise, using this method will create an ephemeral key as specified by the `rgbKey` parameter. ]]> @@ -779,9 +779,9 @@ object using an existing persisted key, when you read the value of the property, an attempt to export the key will be made. In this case, if the key is not exportable, a will be thrown. + If you've created the object using an existing persisted key, when you read the value of the property, an attempt to export the key will be made. In this case, if the key is not exportable, a will be thrown. - In addition to that, if you set the value of the property, the persisted key will no longer be used and a temporary key will be used instead. If you need to use the persisted key again, a new instance of class needs to be created. + In addition to that, if you set the value of the property, the persisted key will no longer be used and a temporary key will be used instead. If you need to use the persisted key again, a new instance of class needs to be created. ]]> @@ -831,7 +831,7 @@ object using an existing persisted key and you set the value of the property, the persisted key will no longer be used and a temporary key will be used instead. If you need to use the persisted key again, a new instance of class needs to be created. + If you've created the object using an existing persisted key and you set the value of the property, the persisted key will no longer be used and a temporary key will be used instead. If you need to use the persisted key again, a new instance of class needs to be created. ]]> diff --git a/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml b/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml index 00fe86c071e..135b62472ee 100644 --- a/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml +++ b/xml/System.Security.Cryptography/TripleDESCryptoServiceProvider.xml @@ -73,14 +73,14 @@ Defines a wrapper object to access the cryptographic service provider (CSP) version of the algorithm. This class cannot be inherited. - method instead. > [!NOTE] -> A newer symmetric encryption algorithm, Advanced Encryption Standard (AES), is available. Consider using the class instead of the class. Use only for compatibility with legacy applications and data. - +> A newer symmetric encryption algorithm, Advanced Encryption Standard (AES), is available. Consider using the class instead of the class. Use only for compatibility with legacy applications and data. + ]]> Cryptographic Services @@ -131,11 +131,11 @@ Initializes a new instance of the class. - method instead. - + ]]> The cryptographic service provider is not available. @@ -177,11 +177,11 @@ Gets or sets the block size, in bits, of the cryptographic operation. The block size, in bits. - @@ -222,11 +222,11 @@ Creates a symmetric decryptor object with the current property and initialization vector (). A symmetric decryptor object. - overload with the same signature. - + overload with the same signature. + ]]> @@ -294,25 +294,25 @@ Creates a symmetric decryptor object with the specified key () and initialization vector (). A symmetric decryptor object. - overload with the same parameters. - + overload with the same parameters. + ]]> - The value of the property is . - - -or- - - The value of the property is and the value of the property is not 8. - - -or- - - An invalid key size was used. - - -or- - + The value of the property is . + + -or- + + The value of the property is and the value of the property is not 8. + + -or- + + An invalid key size was used. + + -or- + The algorithm key size was not available. Cryptographic Services @@ -362,12 +362,12 @@ Creates a symmetric encryptor object with the current property and initialization vector (). A symmetric encryptor object. - property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . - - Use the overload with the same signature to decrypt the result of this method. + property is `null`, the method is called to create a new random . If the current property is `null`, the method is called to create a new random . + + Use the overload with the same signature to decrypt the result of this method. ]]> @@ -431,31 +431,31 @@ The secret key to use for the symmetric algorithm. - The initialization vector to use for the symmetric algorithm. - + The initialization vector to use for the symmetric algorithm. + Note: The initialization vector must be 8 bytes long. If it is longer than 8 bytes, it is truncated and an exception is not thrown. Before you call , check the length of the initialization vector and throw an exception if it is too long. Creates a symmetric encryptor object with the specified key () and initialization vector (). A symmetric encryptor object. - overload with the same parameters to decrypt the result of this method. - + overload with the same parameters to decrypt the result of this method. + ]]> - The value of the property is . - - -or- - - The value of the property is and the value of the property is not 8. - - -or- - - An invalid key size was used. - - -or- - + The value of the property is . + + -or- + + The value of the property is and the value of the property is not 8. + + -or- + + An invalid key size was used. + + -or- + The algorithm key size was not available. Cryptographic Services @@ -582,11 +582,11 @@ Generates a random initialization vector () to use for the algorithm. - Cryptographic Services @@ -635,13 +635,13 @@ Generates a random to be used for the algorithm. - ). - - This algorithm supports key lengths from 128 bits to 192 bits in increments of 64 bits. - + ). + + This algorithm supports key lengths from 128 bits to 192 bits in increments of 64 bits. + ]]> Cryptographic Services @@ -682,15 +682,15 @@ Gets or sets the initialization vector () for the symmetric algorithm. The initialization vector. - property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. - - The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key and an initialization vector to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and property to the same values that were used for encryption. - - For a given secret key *k*, a simple block cipher that does not use an initialization vector will encrypt the same input block of plain text into the same output block of cipher text. If you have duplicate blocks within your plain text stream, you will have duplicate blocks within your cipher text stream. If unauthorized users know anything about the structure of a block of your plain text, they can use that information to decipher the known cipher text block and possibly recover your key. To combat this problem, information from the previous block is mixed into the process of encrypting the next block. Thus, the output of two identical plain text blocks is different. Because this technique uses the previous block to encrypt the next block, an initialization vector is needed to encrypt the first block of data. - + property is automatically set to a new random value whenever you create a new instance of one of the classes or when you manually call the method. The size of the property must be the same as the property divided by 8. + + The classes that derive from the class use a chaining mode called cipher block chaining (CBC), which requires a key and an initialization vector to perform cryptographic transformations on data. To decrypt data that was encrypted using one of the classes, you must set the property and property to the same values that were used for encryption. + + For a given secret key *k*, a simple block cipher that does not use an initialization vector will encrypt the same input block of plain text into the same output block of cipher text. If you have duplicate blocks within your plain text stream, you will have duplicate blocks within your cipher text stream. If unauthorized users know anything about the structure of a block of your plain text, they can use that information to decipher the known cipher text block and possibly recover your key. To combat this problem, information from the previous block is mixed into the process of encrypting the next block. Thus, the output of two identical plain text blocks is different. Because this technique uses the previous block to encrypt the next block, an initialization vector is needed to encrypt the first block of data. + ]]> An attempt was made to set the initialization vector to . @@ -732,11 +732,11 @@ Gets or sets the secret key for the algorithm. The secret key for the algorithm. - @@ -776,13 +776,13 @@ Gets or sets the size, in bits, of the secret key. The size, in bits, of the key. - @@ -822,9 +822,9 @@ Gets the block sizes, in bits, that are supported by the symmetric algorithm. An array that contains the block sizes supported by the algorithm. - @@ -865,9 +865,9 @@ Gets the key sizes, in bits, that are supported by the symmetric algorithm. An array that contains the key sizes supported by the algorithm. - @@ -908,11 +908,11 @@ Gets or sets the mode for operation of the symmetric algorithm. The mode for operation of the symmetric algorithm. The default is . - enumeration for a description of specific modes. - + enumeration for a description of specific modes. + ]]> The cipher mode is not one of the values. @@ -953,11 +953,11 @@ Gets or sets the padding mode used in the symmetric algorithm. The padding mode used in the symmetric algorithm. The default is . - enumeration for a description of specific modes. - + enumeration for a description of specific modes. + ]]> The padding mode is not one of the values. diff --git a/xml/System.Security.Permissions/KeyContainerPermission.xml b/xml/System.Security.Permissions/KeyContainerPermission.xml index ad5975027f3..ae384ebca30 100644 --- a/xml/System.Security.Permissions/KeyContainerPermission.xml +++ b/xml/System.Security.Permissions/KeyContainerPermission.xml @@ -320,7 +320,7 @@ property is set by the constructor. + The property is set by the constructor. ]]> diff --git a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml index ae36c1b959d..c79fdff744b 100644 --- a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml +++ b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryCollection.xml @@ -317,7 +317,7 @@ property to determine the number of objects in the collection. The property is commonly used when iterating through the collection to determine the upper bound of the collection. + Use the property to determine the number of objects in the collection. The property is commonly used when iterating through the collection to determine the upper bound of the collection. ]]> @@ -365,14 +365,14 @@ ## Remarks Use this method to create a object that can be used to iterate through the collection to get each item. - Use the property of the enumerator to get the item currently pointed to in the collection. + Use the property of the enumerator to get the item currently pointed to in the collection. Use the method of the enumerator to move to the next item in the collection. Use the method of the enumerator to move to the initial position. > [!NOTE] -> After you create a object or use the method to move the enumerator to the first item in the collection, you must call the method. Otherwise, the item represented by the property is undefined. +> After you create a object or use the method to move the enumerator to the first item in the collection, you must call the method. Otherwise, the item represented by the property is undefined. ]]> @@ -465,7 +465,7 @@ property and always returns `false`. + This property implements the property and always returns `false`. ]]> @@ -612,7 +612,7 @@ ## Remarks The object returned in this implementation is the object itself. - For more information on the property, see the property of the interface. + For more information on the property, see the property of the interface. ]]> diff --git a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryEnumerator.xml b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryEnumerator.xml index d674ecba8e9..626d11f5850 100644 --- a/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryEnumerator.xml +++ b/xml/System.Security.Permissions/KeyContainerPermissionAccessEntryEnumerator.xml @@ -53,24 +53,24 @@ Represents the enumerator for objects in a . - method also brings the enumerator back to this position. At this position, calling the property throws an exception. 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. - - After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling returns `false`. If the last call to returned `false`, calling throws an exception. To reset to the first element of the collection, call followed by a call to . - - 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 . If the collection is modified between calling and , returns the element to which it is currently set, even if the enumerator is already invalidated. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - + Enumerators allow only reading the data in the collection. Enumerators cannot be used to modify the underlying collection. + + Initially, the enumerator is positioned before the first element in the collection. The method also brings the enumerator back to this position. At this position, calling the property throws an exception. 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. + + After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling returns `false`. If the last call to returned `false`, calling throws an exception. To reset to the first element of the collection, call followed by a call to . + + 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 . If the collection is modified between calling and , returns the element to which it is currently set, even if the enumerator is already invalidated. + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + ]]> @@ -136,19 +136,19 @@ Gets the current entry in the collection. The current object in the collection. - property is not valid and will throw an exception if it is accessed. You must first call the method to position the cursor at the first object in the collection. - - Getting the property multiple times with no intervening calls to will return the same object each time. - + property is not valid and will throw an exception if it is accessed. You must first call the method to position the cursor at the first object in the collection. + + Getting the property multiple times with no intervening calls to will return the same object each time. + ]]> - The property is accessed before first calling the method. The cursor is located before the first object in the collection. - - -or- - + The property is accessed before first calling the method. The cursor is located before the first object in the collection. + + -or- + The property is accessed after a call to the method returns , which indicates that the cursor is located after the last object in the collection. @@ -190,15 +190,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - method returns `false` immediately if there are no objects in the collection. - - returns `true` until it has reached the end of the collection. It then returns `false` for each successive call. However, once has returned `false`, accessing the property throws an exception. - - Upon creation, an enumerator is positioned before the first object in the collection, and the first call to positions the enumerator to the first object in the collection. - + method returns `false` immediately if there are no objects in the collection. + + returns `true` until it has reached the end of the collection. It then returns `false` for each successive call. However, once has returned `false`, accessing the property throws an exception. + + Upon creation, an enumerator is positioned before the first object in the collection, and the first call to positions the enumerator to the first object in the collection. + ]]> @@ -239,13 +239,13 @@ Resets the enumerator to the beginning of the collection. - method positions the cursor at the first object in the collection. After calling , you do not need to call to move the cursor forward to the first object. - + method positions the cursor at the first object in the collection. After calling , you do not need to call to move the cursor forward to the first object. + ]]> @@ -286,11 +286,11 @@ Gets the current object in the collection. The current object in the collection. - property instead. - + property instead. + ]]> diff --git a/xml/System.Security.Permissions/MediaPermissionImage.xml b/xml/System.Security.Permissions/MediaPermissionImage.xml index 1c918076eeb..93a3d36b394 100644 --- a/xml/System.Security.Permissions/MediaPermissionImage.xml +++ b/xml/System.Security.Permissions/MediaPermissionImage.xml @@ -52,7 +52,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - Use this enumeration to set the property of the class. The default is SafeImage. + Use this enumeration to set the property of the class. The default is SafeImage. ]]> diff --git a/xml/System.Security.Permissions/MediaPermissionVideo.xml b/xml/System.Security.Permissions/MediaPermissionVideo.xml index aee2b4cab9e..ade8c15a3b8 100644 --- a/xml/System.Security.Permissions/MediaPermissionVideo.xml +++ b/xml/System.Security.Permissions/MediaPermissionVideo.xml @@ -52,7 +52,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - Use this enumeration to set the property of the class. The default is SafeVideo. + Use this enumeration to set the property of the class. The default is SafeVideo. ]]> diff --git a/xml/System.Security.Permissions/PermissionSetAttribute.xml b/xml/System.Security.Permissions/PermissionSetAttribute.xml index 545cd1f28f2..e416b3c60c9 100644 --- a/xml/System.Security.Permissions/PermissionSetAttribute.xml +++ b/xml/System.Security.Permissions/PermissionSetAttribute.xml @@ -242,7 +242,7 @@ property to `true`. + If the file specified is Unicode, set the property to `true`. ]]> diff --git a/xml/System.Security.Permissions/ResourcePermissionBaseEntry.xml b/xml/System.Security.Permissions/ResourcePermissionBaseEntry.xml index 9db85a68036..203bb73d2ad 100644 --- a/xml/System.Security.Permissions/ResourcePermissionBaseEntry.xml +++ b/xml/System.Security.Permissions/ResourcePermissionBaseEntry.xml @@ -96,7 +96,7 @@ property is set to zero. + The property is set to zero. ]]> diff --git a/xml/System.Security.Permissions/SecurityAttribute.xml b/xml/System.Security.Permissions/SecurityAttribute.xml index a3618bd6bf9..08c909399b7 100644 --- a/xml/System.Security.Permissions/SecurityAttribute.xml +++ b/xml/System.Security.Permissions/SecurityAttribute.xml @@ -165,7 +165,7 @@ property. + You cannot create an instance of this class. You must inherit from this class to make use of its functionality. The value of `action` is used to set the property. ]]> diff --git a/xml/System.Security.Permissions/SecurityPermissionAttribute.xml b/xml/System.Security.Permissions/SecurityPermissionAttribute.xml index 5ac0fdc53dd..e29641e16c0 100644 --- a/xml/System.Security.Permissions/SecurityPermissionAttribute.xml +++ b/xml/System.Security.Permissions/SecurityPermissionAttribute.xml @@ -94,21 +94,21 @@ Allows security actions for to be applied to code using declarative security. This class cannot be inherited. - 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. - - When you use the class, follow the security action with the permission(s) that are being requested. Each security permission that can be requested, as defined in the enumeration, has a corresponding property in the class. For example, to demand the ability to access unmanaged code, follow the demand statement with the property setting that is being requested, as follows: `SecurityPermissionAttribute(SecurityAction.Demand, UnmanagedCode=true)`. - + 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. + + When you use the class, follow the security action with the permission(s) that are being requested. Each security permission that can be requested, as defined in the enumeration, has a corresponding property in the class. For example, to demand the ability to access unmanaged code, follow the demand statement with the property setting that is being requested, as follows: `SecurityPermissionAttribute(SecurityAction.Demand, UnmanagedCode=true)`. + > [!NOTE] -> An exception to the equivalence between the enumeration and the properties is that the enumeration value is represented by the property (inherited from the class). To demand all security permissions, specify `Unrestricted=true`. - +> An exception to the equivalence between the enumeration and the properties is that the enumeration value is represented by the property (inherited from the class). To demand all security permissions, specify `Unrestricted=true`. + ]]> @@ -271,11 +271,11 @@ if code can perform binding redirects; otherwise, . - @@ -596,11 +596,11 @@ if permission to manipulate threads is declared; otherwise, . - . - + . + ]]> @@ -657,13 +657,13 @@ Creates and returns a new . A that corresponds to this attribute. - @@ -719,11 +719,11 @@ if permission to execute code is declared; otherwise, . - permission at the assembly level is ignored. If an assembly has the right to execute, permission is automatically granted, and setting the property to either `true` or `false` has no effect. - + permission at the assembly level is ignored. If an assembly has the right to execute, permission is automatically granted, and setting the property to either `true` or `false` has no effect. + ]]> @@ -997,13 +997,13 @@ if permission to bypass code verification is declared; otherwise, . - [!CAUTION] -> This is a powerful permission that should be granted only to highly trusted code. - +> This is a powerful permission that should be granted only to highly trusted code. + ]]> diff --git a/xml/System.Security.Permissions/StorePermission.xml b/xml/System.Security.Permissions/StorePermission.xml index 6f01627614c..ede523526b0 100644 --- a/xml/System.Security.Permissions/StorePermission.xml +++ b/xml/System.Security.Permissions/StorePermission.xml @@ -48,14 +48,14 @@ Controls access to stores containing X.509 certificates. This class cannot be inherited. - controls the access that code is granted to X.509 stores. The permission is based on flags representing the access levels that apply to every store. - + controls the access that code is granted to X.509 stores. The permission is based on flags representing the access levels that apply to every store. + ]]> @@ -103,11 +103,11 @@ One of the values. Initializes a new instance of the class with either fully restricted or unrestricted permission state. - property can then be set to specify the type of access allowed. - + property can then be set to specify the type of access allowed. + ]]> @@ -146,11 +146,11 @@ A bitwise combination of the values. Initializes a new instance of the class with the specified access. - @@ -190,11 +190,11 @@ Creates and returns an identical copy of the current permission. A copy of the current permission. - @@ -237,11 +237,11 @@ Gets or sets the type of access allowed by the current permission. A bitwise combination of the values. - property specifies the permitted access to X.509 stores. X.509 stores are physical stores used to persist and manage X.509 certificates. - + property specifies the permitted access to X.509 stores. X.509 stores are physical stores used to persist and manage X.509 certificates. + ]]> An attempt is made to set this property to an invalid value. See for the valid values. @@ -282,20 +282,20 @@ A that contains the XML encoding to use to reconstruct the permission. Reconstructs a permission with a specified state from an XML encoding. - method reconstructs a object from an XML encoding defined by the class. Use the method to XML-encode the , including state information. - + method reconstructs a object from an XML encoding defined by the class. Use the method to XML-encode the , including state information. + ]]> is . - is not a valid permission element. - - -or- - + is not a valid permission element. + + -or- + The version number in is not valid. @@ -335,11 +335,11 @@ Creates and returns a permission that is the intersection of the current permission and the specified permission. A new permission that represents the intersection of the current permission and the specified permission. This new permission is if the intersection is empty. - @@ -383,11 +383,11 @@ if the current permission is a subset of the specified permission; otherwise, . - @@ -431,11 +431,11 @@ if the current permission is unrestricted; otherwise, . - @@ -473,11 +473,11 @@ Creates an XML encoding of the permission and its current state. A that contains an XML encoding of the permission, including any state information. - method to restore the state information from a . - + method to restore the state information from a . + ]]> @@ -518,11 +518,11 @@ 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. - is a permission that represents all operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. - + is a permission that represents all operations represented by both the current permission and the specified permission. Any demand that passes either permission passes their union. + ]]> diff --git a/xml/System.Security.Permissions/StrongNameIdentityPermission.xml b/xml/System.Security.Permissions/StrongNameIdentityPermission.xml index b34190dcf77..d73e0fb3145 100644 --- a/xml/System.Security.Permissions/StrongNameIdentityPermission.xml +++ b/xml/System.Security.Permissions/StrongNameIdentityPermission.xml @@ -383,7 +383,7 @@ property containing the wildcard expression MyCompany.MyDepartment.* is identified as a subset of an identity with the property MyCompany.MyDepartment.MyFile. + The current permission is a subset of the specified permission if the current permission specifies a set of operations that is wholly contained by the specified permission. For example, the other properties being equal, an identity with the property containing the wildcard expression MyCompany.MyDepartment.* is identified as a subset of an identity with the property MyCompany.MyDepartment.MyFile. ]]> @@ -427,7 +427,7 @@ property can be an exact name or can be modified by a wildcard character in the final position; for example, both MyCompany.MyDepartment.MyFile and MyCompany.MyDepartment.* are valid names. If you attempt to set the property to an empty string (""), an is thrown. + The value of the property can be an exact name or can be modified by a wildcard character in the final position; for example, both MyCompany.MyDepartment.MyFile and MyCompany.MyDepartment.* are valid names. If you attempt to set the property to an empty string (""), an is thrown. ]]> diff --git a/xml/System.Security.Permissions/StrongNameIdentityPermissionAttribute.xml b/xml/System.Security.Permissions/StrongNameIdentityPermissionAttribute.xml index dcdc8d39103..9b6e46903a4 100644 --- a/xml/System.Security.Permissions/StrongNameIdentityPermissionAttribute.xml +++ b/xml/System.Security.Permissions/StrongNameIdentityPermissionAttribute.xml @@ -54,21 +54,21 @@ Allows security actions for to be applied to code using declarative security. This class cannot be inherited. - [!IMPORTANT] > Starting with .NET Framework 4, identity permissions are not used. - - The scope of the declaration that is allowed depends on the that is used. You can obtain the key string for this attribute by running the Strong Name tool (Sn.exe) with the token and public key options (**Sn** **-tp** *keyfile*`)` against a file that has an Authenticode signature. For more information, see [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool). - - 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. - - The attribute can be used to define strong-name requirements for access to public members at the assembly level. In the .NET Framework version 2.0 and later, you can also use the attribute to specify that all nonpublic types in that assembly are visible to another assembly. For more information, see [Friend assemblies](/dotnet/standard/assembly/friend). - + + The scope of the declaration that is allowed depends on the that is used. You can obtain the key string for this attribute by running the Strong Name tool (Sn.exe) with the token and public key options (**Sn** **-tp** *keyfile*`)` against a file that has an Authenticode signature. For more information, see [Sn.exe (Strong Name Tool)](/dotnet/framework/tools/sn-exe-strong-name-tool). + + 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. + + The attribute can be used to define strong-name requirements for access to public members at the assembly level. In the .NET Framework version 2.0 and later, you can also use the attribute to specify that all nonpublic types in that assembly are visible to another assembly. For more information, see [Friend assemblies](/dotnet/standard/assembly/friend). + ]]> @@ -150,13 +150,13 @@ Creates and returns a new . A that corresponds to this attribute. - The method failed because the key is . @@ -196,11 +196,11 @@ Gets or sets the name of the strong name identity. A name to compare against the name specified by the security provider. - property to "mylibrary". - + property to "mylibrary". + ]]> diff --git a/xml/System.Security.Permissions/UIPermissionWindow.xml b/xml/System.Security.Permissions/UIPermissionWindow.xml index 1e8c3cf580b..1a2d416b388 100644 --- a/xml/System.Security.Permissions/UIPermissionWindow.xml +++ b/xml/System.Security.Permissions/UIPermissionWindow.xml @@ -49,50 +49,50 @@ Specifies the type of windows that code is allowed to use. - . - -When an application runs under the `SafeTopLevelWindows` permission, it: - -- Shows the DNS name or IP address of the Web site from which the application was loaded in its title bar. - -- Displays Balloon tooltip when it first displays, informing the user that it is running under a restricted trust level. - -- Must display its title bar at all times. - -- Must display window controls on its forms. - -- Cannot minimize its main window on startup. - -- Cannot move its windows off-screen. - -- Cannot use the property to make its windows less than 50% transparent. - -- Must use only rectangular windows, and must include the window frame. Windows Forms will not honor setting to . - -- Cannot make windows invisible. Any attempt by the application to set the property to `False` will be ignored. - -- Must have an entry in the Task Bar. - -- Has its controls prohibited from accessing the property. By implication, controls will also be barred from accessing siblings - that is, other controls at the same level of nesting. - -- Cannot control focus using the method. - -- Has restricted keyboard input access, so that a form or control can only access keyboard events for itself and its children. - -- Has restricted mouse coordinate access, so that a form or control can only read mouse coordinates if the mouse is over its visible area. - -- Cannot set the property. - -- Cannot control the z-order of controls on the form using the and methods. - - These restrictions help prevent potentially harmful code from spoofing attacks, such as imitating trusted system dialogs. - +This enumeration is used by . + +When an application runs under the `SafeTopLevelWindows` permission, it: + +- Shows the DNS name or IP address of the Web site from which the application was loaded in its title bar. + +- Displays Balloon tooltip when it first displays, informing the user that it is running under a restricted trust level. + +- Must display its title bar at all times. + +- Must display window controls on its forms. + +- Cannot minimize its main window on startup. + +- Cannot move its windows off-screen. + +- Cannot use the property to make its windows less than 50% transparent. + +- Must use only rectangular windows, and must include the window frame. Windows Forms will not honor setting to . + +- Cannot make windows invisible. Any attempt by the application to set the property to `False` will be ignored. + +- Must have an entry in the Task Bar. + +- Has its controls prohibited from accessing the property. By implication, controls will also be barred from accessing siblings - that is, other controls at the same level of nesting. + +- Cannot control focus using the method. + +- Has restricted keyboard input access, so that a form or control can only access keyboard events for itself and its children. + +- Has restricted mouse coordinate access, so that a form or control can only read mouse coordinates if the mouse is over its visible area. + +- Cannot set the property. + +- Cannot control the z-order of controls on the form using the and methods. + + These restrictions help prevent potentially harmful code from spoofing attacks, such as imitating trusted system dialogs. + ]]> @@ -239,9 +239,9 @@ When an application runs under the `SafeTopLevelWindows` permission, it: Users can only use and for drawing, and can only use user input events for the user interface within those top-level windows and subwindows. See the Remarks section for more information. - diff --git a/xml/System.Security.Permissions/WebBrowserPermission.xml b/xml/System.Security.Permissions/WebBrowserPermission.xml index d25dfd98f61..b6bdaebac64 100644 --- a/xml/System.Security.Permissions/WebBrowserPermission.xml +++ b/xml/System.Security.Permissions/WebBrowserPermission.xml @@ -106,7 +106,7 @@ This class is not typically used in XAML. property is set to . + By default, the value of the property is set to . ]]> @@ -147,7 +147,7 @@ This class is not typically used in XAML. , the value of the property is set to . If `state` is set to , the value of the property is set to . + If `state` is set to , the value of the property is set to . If `state` is set to , the value of the property is set to . ]]> diff --git a/xml/System.Security.Permissions/WebBrowserPermissionLevel.xml b/xml/System.Security.Permissions/WebBrowserPermissionLevel.xml index b065adf69e0..d797d1ec163 100644 --- a/xml/System.Security.Permissions/WebBrowserPermissionLevel.xml +++ b/xml/System.Security.Permissions/WebBrowserPermissionLevel.xml @@ -52,7 +52,7 @@ [!INCLUDE[cas-deprecated](~/includes/cas-deprecated.md)] - Use this enumeration to set the property of the class. + Use this enumeration to set the property of the class. The Safe permission level restricts the following Web browser operations. diff --git a/xml/System.Security.Policy/ApplicationDirectoryMembershipCondition.xml b/xml/System.Security.Policy/ApplicationDirectoryMembershipCondition.xml index cc5e17d4ae2..32679098d30 100644 --- a/xml/System.Security.Policy/ApplicationDirectoryMembershipCondition.xml +++ b/xml/System.Security.Policy/ApplicationDirectoryMembershipCondition.xml @@ -63,16 +63,16 @@ Determines whether an assembly belongs to a code group by testing its application directory. This class cannot be inherited. - determines whether an property contains the assembly URL evidence path. For example, if the is C:\app1, assemblies with URL evidence such as C:\app1, C:\app1\main.aspx, C:\app1\folder1, or C:\app1\folder1\main1.aspx match this membership condition. Code that is not in the C:\app1 directory or in one of its subdirectories fails this membership condition test. - - Code without either or evidence always fails this membership condition test. - + determines whether an property contains the assembly URL evidence path. For example, if the is C:\app1, assemblies with URL evidence such as C:\app1, C:\app1\main.aspx, C:\app1\folder1, or C:\app1\folder1\main1.aspx match this membership condition. Code that is not in the C:\app1 directory or in one of its subdirectories fails this membership condition test. + + Code without either or evidence always fails this membership condition test. + > [!NOTE] -> The membership condition is determined by the URL evidence for the application. You cannot configure the object; it is predetermined by the location of the application. - +> The membership condition is determined by the URL evidence for the application. You cannot configure the object; it is predetermined by the location of the application. + ]]> @@ -107,11 +107,11 @@ Initializes a new instance of the class. - . - + . + ]]> @@ -158,11 +158,11 @@ if the specified evidence satisfies the membership condition; otherwise, . - evidence that specifies the application directory of the running application and evidence that specifies the code base of the assembly. The code base specified by the evidence must represent a path in the directory tree of the application directory specified by the evidence for this method to return `true`. - + evidence that specifies the application directory of the running application and evidence that specifies the code base of the assembly. The code base specified by the evidence must represent a path in the directory tree of the application directory specified by the evidence for this method to return `true`. + ]]> diff --git a/xml/System.Security.Policy/ApplicationSecurityManager.xml b/xml/System.Security.Policy/ApplicationSecurityManager.xml index aa0d873a6bf..5df45c87904 100644 --- a/xml/System.Security.Policy/ApplicationSecurityManager.xml +++ b/xml/System.Security.Policy/ApplicationSecurityManager.xml @@ -25,11 +25,11 @@ Manages trust decisions for manifest-activated applications. - class provides essential information for the execution of a manifest-based application. The property identifies the trust manager responsible for determining whether an application is trusted. The method calls the application trust manager to determine whether an application is trusted. The property contains the cached trust decisions for the user. - + class provides essential information for the execution of a manifest-based application. The property identifies the trust manager responsible for determining whether an application is trusted. The method calls the application trust manager to determine whether an application is trusted. The property contains the cached trust decisions for the user. + ]]> @@ -60,11 +60,11 @@ Gets the current application trust manager. An that represents the current trust manager. - interface. The default trust manager implementation prompts the user for permission to install the application and elevate the permissions granted to the application. Other trust manager implementations might have different user experiences. For example, an implementation might check an enterprise list for trusted applications, rather than prompting the user for that information. - + interface. The default trust manager implementation prompts the user for permission to install the application and elevate the permissions granted to the application. Other trust manager implementations might have different user experiences. For example, an implementation might check an enterprise list for trusted applications, rather than prompting the user for that information. + ]]> The policy on this application does not have a trust manager. @@ -103,11 +103,11 @@ to execute the specified application; otherwise, . - uses the configured property to determine whether to allow execution of the specified application with the permission set requested in the application manifest. The trust manager's behavior is dependent on the trust manager implementation and the information passed in the `context` parameter. The default behavior of the trust manager is to establish a user interface (UI) dialog box to determine the user's approval. However, a trust manager can also determine an application's trust status based on other criteria, such as decisions provided by a corporate database. The trust decision can be persisted, depending upon the `context` parameters properties and the trust manager implementation. If the trust for the application is persisted for a decision based on a user dialog box, future calls to the will not present the UI dialog box for every request for that application. is called after the manifest, but before the application has been downloaded to the local system. - + uses the configured property to determine whether to allow execution of the specified application with the permission set requested in the application manifest. The trust manager's behavior is dependent on the trust manager implementation and the information passed in the `context` parameter. The default behavior of the trust manager is to establish a user interface (UI) dialog box to determine the user's approval. However, a trust manager can also determine an application's trust status based on other criteria, such as decisions provided by a corporate database. The trust decision can be persisted, depending upon the `context` parameters properties and the trust manager implementation. If the trust for the application is persisted for a decision based on a user dialog box, future calls to the will not present the UI dialog box for every request for that application. is called after the manifest, but before the application has been downloaded to the local system. + ]]> The parameter is . @@ -139,11 +139,11 @@ Gets an application trust collection that contains the cached trust decisions for the user. An that contains the cached trust decisions for the user. - method or the method. - + method or the method. + ]]> diff --git a/xml/System.Security.Policy/ApplicationTrust.xml b/xml/System.Security.Policy/ApplicationTrust.xml index e74fcca6271..eefee171a7d 100644 --- a/xml/System.Security.Policy/ApplicationTrust.xml +++ b/xml/System.Security.Policy/ApplicationTrust.xml @@ -55,11 +55,11 @@ Encapsulates security decisions about an application. This class cannot be inherited. - object is returned by a trust manager's method. - + object is returned by a trust manager's method. + ]]> @@ -103,11 +103,11 @@ Initializes a new instance of the class. - object. - + object. + ]]> @@ -152,11 +152,11 @@ An that uniquely identifies an application. Initializes a new instance of the class with an . - @@ -201,14 +201,14 @@ An array of strong names that represent assemblies that should be considered fully trusted in an application domain. Initializes a new instance of the class using the provided grant set and collection of full-trust assemblies. - that are to be granted full trust. This constructor is called by the method to create an that will be used as a sandbox. For more information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). - + `fullTrustAssemblies` identifies strong-named assemblies within the that are to be granted full trust. This constructor is called by the method to create an that will be used as a sandbox. For more information about running an application in a sandbox, see [How to: Run Partially Trusted Code in a Sandbox](/dotnet/framework/misc/how-to-run-partially-trusted-code-in-a-sandbox). + ]]> @@ -250,11 +250,11 @@ Gets or sets the application identity for the application trust object. An for the application trust object. - property uniquely identifies a manifest-based application to be activated in a new domain. - + property uniquely identifies a manifest-based application to be activated in a new domain. + ]]> @@ -325,13 +325,13 @@ Gets or sets the policy statement defining the default grant set. A describing the default grants. - property represents the permissions that are granted to the application. - - The representing the default grants is initialized using a and optional attributes. - + property represents the permissions that are granted to the application. + + The representing the default grants is initialized using a and optional attributes. + ]]> @@ -416,14 +416,14 @@ The XML encoding to use to reconstruct the object. Reconstructs an object with a given state from an XML encoding. - and methods are implemented to make objects XML-encodable for security policy use. - +The and methods are implemented to make objects XML-encodable for security policy use. + ]]> @@ -469,14 +469,14 @@ The and Gets the list of full-trust assemblies for this application trust. A list of full-trust assemblies. - that is associated with this instance. The assemblies are identified by their strong names. - + The list identifies assemblies that are to be granted full trust within the that is associated with this instance. The assemblies are identified by their strong names. + ]]> @@ -515,11 +515,11 @@ The and if the application is trusted to run; otherwise, . The default is . - property to `true` when an application has been approved to execute. - + property to `true` when an application has been approved to execute. + ]]> @@ -558,11 +558,11 @@ The and if application trust information is persisted; otherwise, . The default is . - property is `true`, application trust information is saved to the ClickOnce application store. - + property is `true`, application trust information is saved to the ClickOnce application store. + ]]> @@ -604,11 +604,11 @@ The and Creates an XML encoding of the object and its current state. An XML encoding of the security object, including any state information. - and methods are implemented to make objects XML-encodable for security policy use. - + and methods are implemented to make objects XML-encodable for security policy use. + ]]> diff --git a/xml/System.Security.Policy/ApplicationTrustCollection.xml b/xml/System.Security.Policy/ApplicationTrustCollection.xml index b9c79f6c3eb..fa9125331e7 100644 --- a/xml/System.Security.Policy/ApplicationTrustCollection.xml +++ b/xml/System.Security.Policy/ApplicationTrustCollection.xml @@ -281,7 +281,7 @@ in the collection is identified by its property. If the value of the property for any object in the collection is `null`, an is thrown. + Each in the collection is identified by its property. If the value of the property for any object in the collection is `null`, an is thrown. ]]> @@ -484,14 +484,14 @@ ## Remarks The implements the interface that allows you to move within a collection. - Use the property to get the item currently pointed to in the collection. + Use the property to get the item currently pointed to in the collection. Use the method to move to the next item in the collection. Use the method to move the enumerator to its initial position. > [!NOTE] -> After you create the enumerator, or use the method to reposition the enumerator to the start of the collection, you must then call the method to position the enumerator to the first item. Otherwise, the item represented by the property is undefined. +> After you create the enumerator, or use the method to reposition the enumerator to the start of the collection, you must then call the method to position the enumerator to the first item. Otherwise, the item represented by the property is undefined. ]]> @@ -654,7 +654,7 @@ property of each object in the collection is examined for a property value that matches the application specified by the `appFullName` parameter. + The property of each object in the collection is examined for a property value that matches the application specified by the `appFullName` parameter. ]]> diff --git a/xml/System.Security.Policy/ApplicationTrustEnumerator.xml b/xml/System.Security.Policy/ApplicationTrustEnumerator.xml index 30b74bc3878..93c673b6583 100644 --- a/xml/System.Security.Policy/ApplicationTrustEnumerator.xml +++ b/xml/System.Security.Policy/ApplicationTrustEnumerator.xml @@ -44,21 +44,21 @@ Represents the enumerator for objects in the collection. - method also brings the enumerator back to this position. At this position, calling the property throws an exception. 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. - - After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling returns `false`. If the last call to returned `false`, calling throws an exception. To reset to the first element of the collection, call followed by a call to . - - 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 exception. If the collection is modified between calling and , returns the element to which it is currently set, even if the enumerator is already invalidated. - - The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. - + method also brings the enumerator back to this position. At this position, calling the property throws an exception. 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. + + After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling returns `false`. If the last call to returned `false`, calling throws an exception. To reset to the first element of the collection, call followed by a call to . + + 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 exception. If the collection is modified between calling and , returns the element to which it is currently set, even if the enumerator is already invalidated. + + The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads. + ]]> @@ -102,13 +102,13 @@ Gets the current object in the collection. The current in the . - property is not valid and will throw an exception if it is accessed. You must first call the method to position the cursor at the first object in the collection. - - Multiple calls to with no intervening calls to will return the same object. - + property is not valid and will throw an exception if it is accessed. You must first call the method to position the cursor at the first object in the collection. + + Multiple calls to with no intervening calls to will return the same object. + ]]> @@ -157,15 +157,15 @@ if the enumerator was successfully advanced to the next element; if the enumerator has passed the end of the collection. - method immediately returns `false` if there are no objects in the collection. - - will return `true` until it has reached the end of the collection. It will then return `false` for each successive call. However, after has returned `false`, accessing the property will throw an exception. - - Upon creation, an enumerator is positioned before the first object in the collection, and the first call to positions the enumerator at the first object in the collection. - + method immediately returns `false` if there are no objects in the collection. + + will return `true` until it has reached the end of the collection. It will then return `false` for each successive call. However, after has returned `false`, accessing the property will throw an exception. + + Upon creation, an enumerator is positioned before the first object in the collection, and the first call to positions the enumerator at the first object in the collection. + ]]> @@ -206,13 +206,13 @@ Resets the enumerator to the beginning of the collection. - objects. - - The method positions the cursor at the first object in the collection. After calling , you do not need to call the method to move the cursor forward to the first object. - + objects. + + The method positions the cursor at the first object in the collection. After calling , you do not need to call the method to move the cursor forward to the first object. + ]]> @@ -259,11 +259,11 @@ Gets the current in the collection. The current in the . - property instead. - + property instead. + ]]> diff --git a/xml/System.Security.Policy/CodeConnectAccess.xml b/xml/System.Security.Policy/CodeConnectAccess.xml index 4e53aa88aae..96e150af40a 100644 --- a/xml/System.Security.Policy/CodeConnectAccess.xml +++ b/xml/System.Security.Policy/CodeConnectAccess.xml @@ -104,9 +104,9 @@ property is set using the `allowScheme` parameter. The scheme is converted to lowercase. The value of controls the scheme that executing code can use to connect to a network resource. + The property is set using the `allowScheme` parameter. The scheme is converted to lowercase. The value of controls the scheme that executing code can use to connect to a network resource. - The property is set using the `allowPort` parameter. The value of controls the port that executing code can use to connect to a network resource. + The property is set using the `allowPort` parameter. The value of controls the port that executing code can use to connect to a network resource. @@ -401,7 +401,7 @@ objects are equal if their and property values are equal. + Two objects are equal if their and property values are equal. ]]> diff --git a/xml/System.Security.Policy/Evidence.xml b/xml/System.Security.Policy/Evidence.xml index b61b7b15f04..43ac404f185 100644 --- a/xml/System.Security.Policy/Evidence.xml +++ b/xml/System.Security.Policy/Evidence.xml @@ -1398,7 +1398,7 @@ Console::WriteLine( "HashCode = {0}", myEvidence->GetHashCode() ); property. This example is part of a larger example provided for the class. + The following code example shows the use of the property. This example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Policy.Evidence/CPP/evidence_evidence.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/Evidence/Overview/evidence_evidence.cs" id="Snippet7"::: diff --git a/xml/System.Security.Policy/Hash.xml b/xml/System.Security.Policy/Hash.xml index d504ce295a9..dc32e465a77 100644 --- a/xml/System.Security.Policy/Hash.xml +++ b/xml/System.Security.Policy/Hash.xml @@ -180,7 +180,7 @@ object contains only the property. + The returned object contains only the property. Due to collision problems with MD5, Microsoft recommends a security model based on SHA-256 or better. @@ -229,7 +229,7 @@ object contains only the property. + The returned object contains only the property. Due to collision problems with SHA-1, Microsoft recommends a security model based on SHA-256 or better. @@ -276,7 +276,7 @@ object contains only the property. + The returned object contains only the property. ]]> diff --git a/xml/System.Security.Policy/IApplicationTrustManager.xml b/xml/System.Security.Policy/IApplicationTrustManager.xml index f27553cd33e..bf9a48063bb 100644 --- a/xml/System.Security.Policy/IApplicationTrustManager.xml +++ b/xml/System.Security.Policy/IApplicationTrustManager.xml @@ -25,21 +25,21 @@ Determines whether an application should be executed and which set of permissions should be granted to it. - interface. The host calls the method to determine whether an application should be executed and which permissions should be granted to the application. - - In the .NET Framework 4 and later, there is only one trust manager, which can be a custom implementation of the interface. The default trust manager implementation prompts the user for permission to install the application and to elevate the permissions granted to the application. Other trust manager implementations might provide different user experiences. For example, an implementation might check an enterprise list for trusted applications instead of prompting the user for that information. - - - -## Examples - The following example shows a simple implementation of . - + interface. The host calls the method to determine whether an application should be executed and which permissions should be granted to the application. + + In the .NET Framework 4 and later, there is only one trust manager, which can be a custom implementation of the interface. The default trust manager implementation prompts the user for permission to install the application and to elevate the permissions granted to the application. Other trust manager implementations might provide different user experiences. For example, an implementation might check an enterprise list for trusted applications instead of prompting the user for that information. + + + +## Examples + The following example shows a simple implementation of . + :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/IApplicationTrustManager/Overview/customTrustManager.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/IApplicationTrustManager/Overview/customtrustmanager.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/IApplicationTrustManager/Overview/customtrustmanager.vb" id="Snippet1"::: + ]]> @@ -70,19 +70,19 @@ Determines whether an application should be executed and which set of permissions should be granted to it. An object that contains security decisions about the application. - method is called by the host to determine whether an application should be executed and which set of permissions it should be granted. returns an object with a property that contains a permission set representing the permissions to be granted to each assembly executing within the context of the application. The granted permissions do not apply to assemblies in the global assembly cache. The object also has an property that the trust manager sets to indicate whether the application should be trusted. If the trust manager indicates that the application can be trusted, the host activates the application and grants its assemblies the set of permissions provided in the collection. - - - -## Examples - The following example shows an implementation of the method for a custom trust manager. This code example is part of a larger example provided for the interface. - + method is called by the host to determine whether an application should be executed and which set of permissions it should be granted. returns an object with a property that contains a permission set representing the permissions to be granted to each assembly executing within the context of the application. The granted permissions do not apply to assemblies in the global assembly cache. The object also has an property that the trust manager sets to indicate whether the application should be trusted. If the trust manager indicates that the application can be trusted, the host activates the application and grants its assemblies the set of permissions provided in the collection. + + + +## Examples + The following example shows an implementation of the method for a custom trust manager. This code example is part of a larger example provided for the interface. + :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/IApplicationTrustManager/Overview/customTrustManager.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/IApplicationTrustManager/Overview/customtrustmanager.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/IApplicationTrustManager/Overview/customtrustmanager.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.Security.Policy/NetCodeGroup.xml b/xml/System.Security.Policy/NetCodeGroup.xml index 3d57081ae45..a47e03d6fdf 100644 --- a/xml/System.Security.Policy/NetCodeGroup.xml +++ b/xml/System.Security.Policy/NetCodeGroup.xml @@ -61,7 +61,7 @@ |http|HTTP and HTTPS access is permitted using the origin port.| |https|HTTPS access is permitted using the origin port.| - You can control the scheme and port that code is permitted to use when connecting back to its site of origin by passing a object with the appropriate and property values to the method. You can create a connection access rule that applies when the origin scheme is not present in the evidence or is not recognized by specifying ("") as the scheme. You can also create a connection access rule that applies when there is no connection access rule with a matching scheme by specifying ("*") as the scheme. + You can control the scheme and port that code is permitted to use when connecting back to its site of origin by passing a object with the appropriate and property values to the method. You can create a connection access rule that applies when the origin scheme is not present in the evidence or is not recognized by specifying ("") as the scheme. You can also create a connection access rule that applies when there is no connection access rule with a matching scheme by specifying ("*") as the scheme. > [!NOTE] > If code does not submit the URI scheme as evidence, access is permitted using any scheme back to the origin site. @@ -475,7 +475,7 @@ - The and properties. -- The property. +- The property. - The set of origin schemes and the associated objects. @@ -520,7 +520,7 @@ property value is the origin scheme, and the property value is the array of associated objects. If there are no associated objects, returns an empty array. + In each dictionary entry, the property value is the origin scheme, and the property value is the array of associated objects. If there are no associated objects, returns an empty array. diff --git a/xml/System.Security.Policy/PolicyException.xml b/xml/System.Security.Policy/PolicyException.xml index 3273421975d..3d535d83049 100644 --- a/xml/System.Security.Policy/PolicyException.xml +++ b/xml/System.Security.Policy/PolicyException.xml @@ -51,15 +51,15 @@ The exception that is thrown when policy forbids code to run. - uses the HRESULT CORSEC_E_POLICY_EXCEPTION. - - For a list of initial property values for an instance of , see the constructor. - + uses the HRESULT CORSEC_E_POLICY_EXCEPTION. + + For a list of initial property values for an instance of , see the constructor. + ]]> @@ -106,16 +106,16 @@ Initializes a new instance of the class with default properties. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The localized error message string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The localized error message string.| + ]]> @@ -154,16 +154,16 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string.| + ]]> @@ -218,11 +218,11 @@ The contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -263,18 +263,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 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.Security.Policy/PolicyLevel.xml b/xml/System.Security.Policy/PolicyLevel.xml index 8795a7c2bc8..11b83de8a92 100644 --- a/xml/System.Security.Policy/PolicyLevel.xml +++ b/xml/System.Security.Policy/PolicyLevel.xml @@ -47,27 +47,27 @@ Represents the security policy levels for the common language runtime. This class cannot be inherited. - [!IMPORTANT] -> Starting with the .NET Framework 4, the common language runtime (CLR) is moving away from providing security policy for computers. We recommend that you use [Windows Software Restriction Policies (SRP)](https://go.microsoft.com/fwlink/?LinkId=178101) or [AppLocker](https://go.microsoft.com/fwlink/?LinkId=178102) as a replacement for CLR security policy. The information in this topic applies to the .NET Framework version 3.5 and earlier; it does not apply to the .NET Framework 4 and later. For more information about this and other changes, see [Security Changes](/dotnet/framework/security/security-changes). - - The highest level of security policy is enterprise-wide. Successive lower levels of hierarchy represent further policy restrictions, but can never grant more permissions than allowed by higher levels. The following policy levels are implemented: - -1. Enterprise: Security policy for all managed code in an enterprise. - -2. Machine: Security policy for all managed code run on the computer. - -3. User: Security policy for all managed code run by the user. - -4. Application domain: Security policy for all managed code in an application. - - A policy level consists of a set of code groups organized into a single rooted tree (see ), a set of named permission sets that are referenced by the code groups to specify permissions to be granted to code belonging to the code group, and a list of fully-trusted assemblies. - - Use to enumerate the policy levels. - +> Starting with the .NET Framework 4, the common language runtime (CLR) is moving away from providing security policy for computers. We recommend that you use [Windows Software Restriction Policies (SRP)](https://go.microsoft.com/fwlink/?LinkId=178101) or [AppLocker](https://go.microsoft.com/fwlink/?LinkId=178102) as a replacement for CLR security policy. The information in this topic applies to the .NET Framework version 3.5 and earlier; it does not apply to the .NET Framework 4 and later. For more information about this and other changes, see [Security Changes](/dotnet/framework/security/security-changes). + + The highest level of security policy is enterprise-wide. Successive lower levels of hierarchy represent further policy restrictions, but can never grant more permissions than allowed by higher levels. The following policy levels are implemented: + +1. Enterprise: Security policy for all managed code in an enterprise. + +2. Machine: Security policy for all managed code run on the computer. + +3. User: Security policy for all managed code run by the user. + +4. Application domain: Security policy for all managed code in an application. + + A policy level consists of a set of code groups organized into a single rooted tree (see ), a set of named permission sets that are referenced by the code groups to specify permissions to be granted to code belonging to the code group, and a list of fully-trusted assemblies. + + Use to enumerate the policy levels. + ]]> @@ -133,11 +133,11 @@ The used to create the to add to the list of objects used to determine whether an assembly is a member of the group of assemblies that should not be evaluated. Adds a corresponding to the specified to the list of objects used to determine whether an assembly is a member of the group of assemblies that should not be evaluated. - method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. - + method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. + ]]> The parameter is . @@ -196,11 +196,11 @@ The to add to the list of objects used to determine whether an assembly is a member of the group of assemblies that should not be evaluated. Adds the specified to the list of objects used to determine whether an assembly is a member of the group of assemblies that should not be evaluated. - method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. - + method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. + ]]> The parameter is . @@ -255,14 +255,14 @@ The to add to the current policy level. Adds a to the current policy level. - The parameter is . @@ -327,15 +327,15 @@ ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . - The parameter is equal to the name of a reserved permission set. - - -or- - + The parameter is equal to the name of a reserved permission set. + + -or- + The specified by the parameter cannot be found. @@ -388,14 +388,14 @@ Creates a new policy level for use at the application domain policy level. The newly created . - with the "AppDomain". The new will initially contain the same objects as in the default computer policy, and will have a single root code group that grants `FullTrust` to all code. - + This method creates a new with the "AppDomain". The new will initially contain the same objects as in the default computer policy, and will have a single root code group that grants `FullTrust` to all code. + ]]> @@ -496,13 +496,13 @@ Gets a list of objects used to determine whether an assembly is a member of the group of assemblies used to evaluate security policy. A list of objects used to determine whether an assembly is a member of the group of assemblies used to evaluate security policy. These assemblies are granted full trust during security policy evaluation of assemblies not in the list. - are granted full trust during security policy evaluation of assemblies not in the list, but are not automatically granted full trust when directly evaluated by the security policy system. - - The property is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. - + are granted full trust during security policy evaluation of assemblies not in the list, but are not automatically granted full trust when directly evaluated by the security policy system. + + The property is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. + ]]> @@ -601,11 +601,11 @@ Gets a descriptive label for the policy level. The label associated with the policy level. - @@ -692,13 +692,13 @@ Replaces the configuration file for this with the last backup (reflecting the state of policy prior to the last time it was saved) and returns it to the state of the last save. - . Instead, it updates the object's file and the that the security system uses to evaluate policy. - - This method is used by the caspol -recover option (see [Caspol.exe (Code Access Security Policy Tool)](/dotnet/framework/tools/caspol-exe-code-access-security-policy-tool)). - + . Instead, it updates the object's file and the that the security system uses to evaluate policy. + + This method is used by the caspol -recover option (see [Caspol.exe (Code Access Security Policy Tool)](/dotnet/framework/tools/caspol-exe-code-access-security-policy-tool)). + ]]> The policy level does not have a valid configuration file. @@ -765,11 +765,11 @@ The of the assembly to remove from the list of assemblies used to evaluate policy. Removes an assembly with the specified from the list of assemblies the policy level uses to evaluate policy. - method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. - + method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. + ]]> The parameter is . @@ -827,11 +827,11 @@ The of the assembly to remove from the list of assemblies used to evaluate policy. Removes an assembly with the specified from the list of assemblies the policy level uses to evaluate policy. - method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. - + method is not supported in version 2.0 or later of the .NET Framework because the list of full trust assemblies is not used in those versions. + ]]> The parameter is . @@ -964,10 +964,10 @@ ]]> - The parameter is equal to the name of a reserved permission set. - - -or- - + The parameter is equal to the name of a reserved permission set. + + -or- + A with the specified name cannot be found. The parameter is . @@ -1013,11 +1013,11 @@ Returns the current policy level to the default state. - @@ -1066,22 +1066,22 @@ Resolves policy based on evidence for the policy level, and returns the resulting . The resulting . - is the basic policy evaluation operation for policy levels. Given a set of evidence as input, this method tests membership conditions of code groups starting at the root and working down as matched. The combination of permissions resulting from the matching code groups produces a that is returned. - - In granting permissions to code, security policy uses the resolved policy statements for all applicable policy levels, together with the code request for permissions. - - - -## Examples - The following code shows the use of the method. This code example is part of a larger example provided for the class. - + is the basic policy evaluation operation for policy levels. Given a set of evidence as input, this method tests membership conditions of code groups starting at the root and working down as matched. The combination of permissions resulting from the matching code groups produces a that is returned. + + In granting permissions to code, security policy uses the resolved policy statements for all applicable policy levels, together with the code request for permissions. + + + +## Examples + The following code shows the use of the method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.policy.policylevel/CPP/policylevel.cpp" id="Snippet13"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/PolicyLevel/Resolve/policylevel.cs" id="Snippet13"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/PolicyLevel/Resolve/policylevel.vb" id="Snippet13"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/PolicyLevel/Resolve/policylevel.vb" id="Snippet13"::: + ]]> The policy level contains multiple matching code groups marked as exclusive. @@ -1132,13 +1132,13 @@ Resolves policy at the policy level and returns the root of a code group tree that matches the evidence. A representing the root of a tree of code groups matching the specified evidence. - The policy level contains multiple matching code groups marked as exclusive. @@ -1189,11 +1189,11 @@ Gets or sets the root code group for the policy level. The that is the root of the tree of policy level code groups. - . - + . + ]]> The value for is . @@ -1239,15 +1239,15 @@ Gets the path where the policy file is stored. The path where the policy file is stored, or if the does not have a storage location. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.policy.policylevel/CPP/policylevel.cpp" id="Snippet15"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Policy/PolicyLevel/Resolve/policylevel.cs" id="Snippet15"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/PolicyLevel/Resolve/policylevel.vb" id="Snippet15"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Policy/PolicyLevel/Resolve/policylevel.vb" id="Snippet15"::: + ]]> @@ -1334,21 +1334,21 @@ Gets the type of the policy level. One of the values. - . - + . + ]]> diff --git a/xml/System.Security.Policy/StrongNameMembershipCondition.xml b/xml/System.Security.Policy/StrongNameMembershipCondition.xml index 73fb9bde257..1acc0b244af 100644 --- a/xml/System.Security.Policy/StrongNameMembershipCondition.xml +++ b/xml/System.Security.Policy/StrongNameMembershipCondition.xml @@ -67,14 +67,14 @@ Determines whether an assembly belongs to a code group by testing its strong name. This class cannot be inherited. - @@ -117,20 +117,20 @@ The version number of the strong name. Initializes a new instance of the class with the strong name public key blob, name, and version number that determine membership. - that checks for and (but not ) by passing `null` into the `version` parameter. If `name` is an empty string (""), an is thrown. - + that checks for and (but not ) by passing `null` into the `version` parameter. If `name` is an empty string (""), an is thrown. + ]]> The parameter is . - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is an empty string (""). @@ -176,13 +176,13 @@ if the specified evidence satisfies the membership condition; otherwise, . - evidence object. - - The membership condition is satisfied if the specified evidence contains a with the same (public key, name, and version) as specified by the . - + evidence object. + + The membership condition is satisfied if the specified evidence contains a with the same (public key, name, and version) as specified by the . + ]]> @@ -269,11 +269,11 @@ if the from the specified object is equivalent to the contained in the current ; otherwise, . - classes to be equal, their name, version, and public key blob must match exactly. - + classes to be equal, their name, version, and public key blob must match exactly. + ]]> The property of the current object or the specified object is . @@ -449,17 +449,17 @@ Gets or sets the simple name of the for which the membership condition tests. The simple name of the for which the membership condition tests. - property to an empty string (""), an is thrown. - + property to an empty string (""), an is thrown. + ]]> - The value is . - - -or- - + The value is . + + -or- + The value is an empty string (""). @@ -497,13 +497,13 @@ Gets or sets the of the for which the membership condition tests. The of the for which the membership condition tests. - An attempt is made to set the to . diff --git a/xml/System.Security.Policy/TrustManagerContext.xml b/xml/System.Security.Policy/TrustManagerContext.xml index aeddf533f69..e3e1d092ffb 100644 --- a/xml/System.Security.Policy/TrustManagerContext.xml +++ b/xml/System.Security.Policy/TrustManagerContext.xml @@ -40,11 +40,11 @@ Represents the context for the trust manager to consider when making the decision to run an application, and when setting up the security on a new in which to run an application. - class, see the constructor. - + class, see the constructor. + ]]> @@ -88,20 +88,20 @@ Initializes a new instance of the class. - class. - -|Property|Initial value| -|--------------|-------------------| -||`false`| -||`false`| -||`false`| -||`true`| -||`null`| -||| - + class. + +|Property|Initial value| +|--------------|-------------------| +||`false`| +||`false`| +||`false`| +||`true`| +||`null`| +||| + ]]> @@ -139,11 +139,11 @@ One of the values that specifies the type of trust manager user interface to use. Initializes a new instance of the class using the specified object. - property, which is set to the value that is passed in. - + property, which is set to the value that is passed in. + ]]> @@ -182,11 +182,11 @@ to call the trust manager; otherwise, . - ignores persisted decisions for the application and calls the trust manager. If `false`, the uses cached decisions, if available. - + ignores persisted decisions for the application and calls the trust manager. If `false`, the uses cached decisions, if available. + ]]> @@ -225,11 +225,11 @@ to cache state data; otherwise, . The default is . - method. This property is set to `false` if the host does not expect to call the trust manager again for the current . - + method. This property is set to `false` if the host does not expect to call the trust manager again for the current . + ]]> @@ -268,11 +268,11 @@ to not prompt the user; to prompt the user. The default is . - @@ -311,11 +311,11 @@ to cache state data; otherwise, . The default is . - @@ -388,11 +388,11 @@ Gets or sets the type of user interface the trust manager should display. One of the values. The default is . - property is intended to recommend the user interface the trust manager should provide for the trust decision. A trust manager can decide to use a different interface. - + property is intended to recommend the user interface the trust manager should provide for the trust decision. A trust manager can decide to use a different interface. + ]]> diff --git a/xml/System.Security.Principal/GenericIdentity.xml b/xml/System.Security.Principal/GenericIdentity.xml index 8d2c0697c9b..543aaad2597 100644 --- a/xml/System.Security.Principal/GenericIdentity.xml +++ b/xml/System.Security.Principal/GenericIdentity.xml @@ -73,20 +73,20 @@ Represents a generic user. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericIdentity2/CPP/genericidentitymembers.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.vb" id="Snippet1"::: + ]]> @@ -191,15 +191,15 @@ The name of the user on whose behalf the code is running. Initializes a new instance of the class representing the user with the specified name. - constructor. This code example is part of a larger example provided for the class. - + constructor. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericIdentity2/CPP/genericidentitymembers.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.vb" id="Snippet2"::: + ]]> The parameter is . @@ -255,21 +255,21 @@ The type of authentication used to identify the user. Initializes a new instance of the class representing the user with the specified name and authentication type. - constructor. This code example is part of a larger example provided for the class. - + constructor. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericIdentity2/CPP/genericidentitymembers.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.vb" id="Snippet3"::: + ]]> - The parameter is . - - -or- - + The parameter is . + + -or- + The parameter is . @@ -320,15 +320,15 @@ Gets the type of authentication used to identify the user. The type of authentication used to identify the user. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericIdentity2/CPP/genericidentitymembers.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.vb" id="Snippet5"::: + ]]> @@ -515,15 +515,15 @@ Gets the user's name. The name of the user on whose behalf the code is being run. - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericIdentity2/CPP/genericidentitymembers.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericIdentity/Overview/genericidentitymembers.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.Security.Principal/GenericPrincipal.xml b/xml/System.Security.Principal/GenericPrincipal.xml index 060a8b7f951..dd13f9f569a 100644 --- a/xml/System.Security.Principal/GenericPrincipal.xml +++ b/xml/System.Security.Principal/GenericPrincipal.xml @@ -73,20 +73,20 @@ Represents a generic principal. - class. - + class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericPrincipal2/CPP/genericprincipalmembers.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.vb" id="Snippet1"::: + ]]> @@ -143,15 +143,15 @@ An array of role names to which the user represented by the parameter belongs. Initializes a new instance of the class from a user identity and an array of role names to which the user represented by that identity belongs. - constructor. This code example is part of a larger example provided for the class. - + constructor. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericPrincipal2/CPP/genericprincipalmembers.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.vb" id="Snippet2"::: + ]]> The parameter is . @@ -204,15 +204,15 @@ Gets the of the user represented by the current . The of the user represented by the . - property. This code example is part of a larger example provided for the class. - + property. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericPrincipal2/CPP/genericprincipalmembers.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.vb" id="Snippet3"::: + ]]> @@ -280,15 +280,15 @@ if the current is a member of the specified role; otherwise, . - method. This code example is part of a larger example provided for the class. - + method. This code example is part of a larger example provided for the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.GenericPrincipal2/CPP/genericprincipalmembers.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/GenericPrincipal/Overview/genericprincipalmembers.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.Security.Principal/WindowsIdentity.xml b/xml/System.Security.Principal/WindowsIdentity.xml index 733a2583160..cb52580748c 100644 --- a/xml/System.Security.Principal/WindowsIdentity.xml +++ b/xml/System.Security.Principal/WindowsIdentity.xml @@ -1118,7 +1118,7 @@ Application code does not call this method; it is automatically invoked during g ## Remarks This property returns an empty object that enables you to treat operations as anonymous. The property value does not correspond to a Windows anonymous user and cannot be used for impersonation. Also, note that the identity returned by this property is not static; each call to returns a different anonymous identity. - You can use the property to detect the return value from . However, detects both the Windows anonymous identity and the anonymous identity returned by this method. To use the latter identity, cache the return value instead of relying on the property. + You can use the property to detect the return value from . However, detects both the Windows anonymous identity and the anonymous identity returned by this method. To use the latter identity, cache the return value instead of relying on the property. @@ -1350,7 +1350,7 @@ Application code does not call this method; it is automatically invoked during g property to display the identity references for the groups the current user belongs to. This code example is part of a larger example provided for the class. + The following code example shows the use of the property to display the identity references for the groups the current user belongs to. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet20"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsAccountType/Overview/Form1.vb" id="Snippet20"::: @@ -1542,7 +1542,7 @@ Application code does not call this method; it is automatically invoked during g ## Examples - The following code example shows the use of the property to display the impersonation level for the current user. This code example is part of a larger example provided for the class. + The following code example shows the use of the property to display the impersonation level for the current user. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet21"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsAccountType/Overview/Form1.vb" id="Snippet21"::: @@ -1595,14 +1595,14 @@ Application code does not call this method; it is automatically invoked during g property detects both the Windows anonymous identity and the anonymous identity that is returned by the method. + The property detects both the Windows anonymous identity and the anonymous identity that is returned by the method. Anonymous accounts are typically only encountered only from within ASP.NET-based applications when anonymous access is allowed by Internet Information Services (IIS). ## Examples - The following code shows the use of the property to detect whether the user account is identified as an anonymous account by the system. This code example is part of a larger example provided for the class. + The following code shows the use of the property to detect whether the user account is identified as an anonymous account by the system. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet9"::: @@ -1698,7 +1698,7 @@ Application code does not call this method; it is automatically invoked during g property to return a value indicating whether the user account is identified as a account by the system. This code example is part of a larger example provided for the class. + The following code shows the use of the property to return a value indicating whether the user account is identified as a account by the system. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet12"::: @@ -1752,7 +1752,7 @@ Application code does not call this method; it is automatically invoked during g property to return a value indicating whether the user account is identified as a account by the system. This code example is part of a larger example provided for the class. + The following code shows the use of the property to return a value indicating whether the user account is identified as a account by the system. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet11"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet11"::: @@ -1815,7 +1815,7 @@ Application code does not call this method; it is automatically invoked during g ## Examples - The following code shows the use of the property to get the user's Windows logon name. This code example is part of a larger example provided for the class. + The following code shows the use of the property to get the user's Windows logon name. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet8"::: @@ -1881,7 +1881,7 @@ Application code does not call this method; it is automatically invoked during g ## Examples - The following code example shows the use of the property to display the security identifier for the token owner. This code example is part of a larger example provided for the class + The following code example shows the use of the property to display the security identifier for the token owner. This code example is part of a larger example provided for the class :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet19"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsAccountType/Overview/Form1.vb" id="Snippet19"::: @@ -2386,15 +2386,15 @@ public class ImpersonationDemo property. The token is released by the method, which you can call in code. is also automatically called by the garbage collector. + Do not explicitly release the account token that is returned by the property. The token is released by the method, which you can call in code. is also automatically called by the garbage collector. > [!NOTE] -> The account token that is returned by the property is a duplicate of the Windows token that is used to create the object and is automatically released by the .NET Framework. This is different from the account token (the `userToken` parameter for the constructor), which is used to create the object. `userToken` is a Windows account token that is created by a call to `LogonUser` and must be closed to avoid a memory leak. +> The account token that is returned by the property is a duplicate of the Windows token that is used to create the object and is automatically released by the .NET Framework. This is different from the account token (the `userToken` parameter for the constructor), which is used to create the object. `userToken` is a Windows account token that is created by a call to `LogonUser` and must be closed to avoid a memory leak. ## Examples - The following code shows the use of the property to get the Windows account token for the user. This code example is part of a larger example provided for the class. + The following code shows the use of the property to get the Windows account token for the user. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsIdentity_AllMembers/CPP/windowsidentitymembers.cpp" id="Snippet14"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsAccountType/Overview/windowsidentitymembers.cs" id="Snippet14"::: diff --git a/xml/System.Security.Principal/WindowsPrincipal.xml b/xml/System.Security.Principal/WindowsPrincipal.xml index 0312b2ab88b..04637ce18e9 100644 --- a/xml/System.Security.Principal/WindowsPrincipal.xml +++ b/xml/System.Security.Principal/WindowsPrincipal.xml @@ -56,20 +56,20 @@ Enables code to check the Windows group membership of a Windows user. - class is primarily used to check the role of a Windows user. The method overloads let you check the user role by using different role contexts. - - - -## Examples - The following example demonstrates how to use the method overloads. The enumeration is used as the source for the relative identifiers (RIDs) that identify the built-in roles. The RIDs are used to determine the roles of the current principal. - + class is primarily used to check the role of a Windows user. The method overloads let you check the user role by using different role contexts. + + + +## Examples + The following example demonstrates how to use the method overloads. The enumeration is used as the source for the relative identifiers (RIDs) that identify the built-in roles. The RIDs are used to determine the roles of the current principal. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet1"::: + ]]> @@ -108,15 +108,15 @@ The object from which to construct the new instance of . Initializes a new instance of the class by using the specified object. - object from the current object. - + object from the current object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic WindowsPrincipal.WindowsPrincipal Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsPrincipal/.ctor/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsPrincipal/.ctor/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsPrincipal/.ctor/source.vb" id="Snippet1"::: + ]]> @@ -204,15 +204,15 @@ Gets the identity of the current principal. The object of the current principal. - property of the object. - + property of the object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic WindowsPrincipal.Identity Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsPrincipal/Identity/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsPrincipal/Identity/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsPrincipal/Identity/source.vb" id="Snippet1"::: + ]]> @@ -225,11 +225,11 @@ Determines whether the current principal belongs to a specified Windows user group. - overload is strongly recommended. - + ]]> @@ -274,53 +274,53 @@ if the current principal is a member of the specified Windows user group, that is, in a particular role; otherwise, . - test to return `false`. - - For performance reasons, the overload is recommended as the preferable overload for determining the user's role. - + + For performance reasons, the overload is recommended as the preferable overload for determining the user's role. + > [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. - - Relative identifiers (RIDs) are components of a Windows user group's security identifier (SID) and are supported to help prevent cross-platform localization issues. Many user accounts, local groups, and global groups have a default RID value that is constant across all versions of Windows. - - For example, the RID for the BUILTIN\Administrators role is 0x220. Using 0x220 as the input parameter for the method results in `true` being returned if the current principal is an administrator. - - The following tables list the default RID values. - -|Built-in users|RID| -|---------------------|---------| -|DOMAINNAME\Administrator|0x1F4| -|DOMAINNAME\Guest|0x1F5| - -|Built-in global groups|RID| -|-----------------------------|---------| -|DOMAINNAME\Domain Admins|0x200| -|DOMAINNAME\Domain Users|0x201| -|DOMAINNAME\Domain Guests|0x202| - -|Built-in local groups|RID| -|----------------------------|---------| -|BUILTIN\Administrators|0x220| -|BUILTIN\Users|0x221| -|BUILTIN\Guests|0x222| -|BUILTIN\Account Operators|0x224| -|BUILTIN\Server Operators|0x225| -|BUILTIN\Print Operators|0x226| -|BUILTIN\Backup Operators|0x227| -|BUILTIN\Replicator|0x228| - - - -## Examples - The following code example demonstrates the use of the methods. The enumeration is used as the source for the RIDs that identify the built-in roles. The RIDs are used to determine the roles of the current principal. - +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. + + Relative identifiers (RIDs) are components of a Windows user group's security identifier (SID) and are supported to help prevent cross-platform localization issues. Many user accounts, local groups, and global groups have a default RID value that is constant across all versions of Windows. + + For example, the RID for the BUILTIN\Administrators role is 0x220. Using 0x220 as the input parameter for the method results in `true` being returned if the current principal is an administrator. + + The following tables list the default RID values. + +|Built-in users|RID| +|---------------------|---------| +|DOMAINNAME\Administrator|0x1F4| +|DOMAINNAME\Guest|0x1F5| + +|Built-in global groups|RID| +|-----------------------------|---------| +|DOMAINNAME\Domain Admins|0x200| +|DOMAINNAME\Domain Users|0x201| +|DOMAINNAME\Domain Guests|0x202| + +|Built-in local groups|RID| +|----------------------------|---------| +|BUILTIN\Administrators|0x220| +|BUILTIN\Users|0x221| +|BUILTIN\Guests|0x222| +|BUILTIN\Account Operators|0x224| +|BUILTIN\Server Operators|0x225| +|BUILTIN\Print Operators|0x226| +|BUILTIN\Backup Operators|0x227| +|BUILTIN\Replicator|0x228| + + + +## Examples + The following code example demonstrates the use of the methods. The enumeration is used as the source for the RIDs that identify the built-in roles. The RIDs are used to determine the roles of the current principal. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet1"::: + ]]> @@ -374,22 +374,22 @@ if the current principal is a member of the specified Windows user group; otherwise, . - uniquely identifies a user or group on Windows. When testing for newly created role information, such as a new user or a new group, it is important to log out and log in to force the propagation of role information within the domain. Not doing so can cause the test to return `false`. - + > [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. - +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. + For performance reasons, this is the preferable overload to determine a user's role. - -## Examples - The following code example demonstrates the use of the method. The enumeration value is used to determine whether the current principal is an administrator. For the full code example, see the method. - + +## Examples + The following code example demonstrates the use of the method. The enumeration value is used to determine whether the current principal is an administrator. For the full code example, see the method. + :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet5"::: + ]]> @@ -437,24 +437,24 @@ if the current principal is a member of the specified Windows user group; otherwise, . - test to return `false`. - - For performance reasons, the overload is recommended as the preferable overload for determining the user's role. - + + For performance reasons, the overload is recommended as the preferable overload for determining the user's role. + > [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. - - - -## Examples - The following example uses the enumeration is used to determine whether the current principal is an . For the full code example, see the method. - +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. + + + +## Examples + The following example uses the enumeration is used to determine whether the current principal is an . For the full code example, see the method. + :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet4"::: + ]]> @@ -514,49 +514,49 @@ if the current principal is a member of the specified Windows user group; otherwise, . - test to return `false`. - - For performance reasons, the overload is recommended as the preferable overload for determining the user's role. - + + For performance reasons, the overload is recommended as the preferable overload for determining the user's role. + > [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. - - For built-in roles, the `role` string should be in the form "BUILTIN\\*RoleNameHere*". For example, to test for membership in the Windows administrator role, the string representing the role should be "BUILTIN\Administrators". Note that the backslash might need to be escaped. The following table lists the built-in roles. - +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. When you attempt to perform a task that requires administrative privileges, you can dynamically elevate your role by using the Consent dialog box. The code that executes the method does not display the Consent dialog box. The code returns false if you are in the standard user role, even if you are in the Built-in Administrators group. You can elevate your privileges before you execute the code by right-clicking the application icon and indicating that you want to run as an administrator. + + For built-in roles, the `role` string should be in the form "BUILTIN\\*RoleNameHere*". For example, to test for membership in the Windows administrator role, the string representing the role should be "BUILTIN\Administrators". Note that the backslash might need to be escaped. The following table lists the built-in roles. + > [!NOTE] -> The spelling for the BUILTIN roles in string format differs from the spelling used in the enumeration. For example, the spelling for an administrator in the enumeration is "Administrator", not "Administrators". When using this overload, use the spelling for the role from the following table. - -|Built-in local groups| -|----------------------------| -|BUILTIN\Administrators| -|BUILTIN\Users| -|BUILTIN\Guests| -|BUILTIN\Account Operators| -|BUILTIN\Server Operators| -|BUILTIN\Print Operators| -|BUILTIN\Backup Operators| -|BUILTIN\Replicator| - - For machine-specific roles, the `role` string should be in the form "MachineName\\*RoleNameHere*". - - For domain-specific roles, the `role` string should be in the form "DomainName\\*RoleNameHere*"; for example, `"SomeDomain\Domain Users`". - +> The spelling for the BUILTIN roles in string format differs from the spelling used in the enumeration. For example, the spelling for an administrator in the enumeration is "Administrator", not "Administrators". When using this overload, use the spelling for the role from the following table. + +|Built-in local groups| +|----------------------------| +|BUILTIN\Administrators| +|BUILTIN\Users| +|BUILTIN\Guests| +|BUILTIN\Account Operators| +|BUILTIN\Server Operators| +|BUILTIN\Print Operators| +|BUILTIN\Backup Operators| +|BUILTIN\Replicator| + + For machine-specific roles, the `role` string should be in the form "MachineName\\*RoleNameHere*". + + For domain-specific roles, the `role` string should be in the form "DomainName\\*RoleNameHere*"; for example, `"SomeDomain\Domain Users`". + > [!NOTE] -> In the .NET Framework version 1.0, the `role` parameter is case-sensitive. In the .NET Framework version 1.1 and later, the `role` parameter is case-insensitive. - - - -## Examples - The following code example demonstrates the use of the method. - - The strings `BUILTIN\Administrators` and `BUILTIN\Users` are used to determine whether the current principal is an administrator or a user. For the full code example, see the method. - +> In the .NET Framework version 1.0, the `role` parameter is case-sensitive. In the .NET Framework version 1.1 and later, the `role` parameter is case-insensitive. + + + +## Examples + The following code example demonstrates the use of the method. + + The strings `BUILTIN\Administrators` and `BUILTIN\Users` are used to determine whether the current principal is an administrator or a user. For the full code example, see the method. + :::code language="csharp" source="~/snippets/csharp/System.Security.Principal/WindowsBuiltInRole/Overview/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Security.Principal/WindowsBuiltInRole/Overview/source.vb" id="Snippet3"::: + ]]> diff --git a/xml/System.Security.RightsManagement/ContentGrant.xml b/xml/System.Security.RightsManagement/ContentGrant.xml index 2f8c6bf8f77..851bb0ae08f 100644 --- a/xml/System.Security.RightsManagement/ContentGrant.xml +++ b/xml/System.Security.RightsManagement/ContentGrant.xml @@ -86,9 +86,9 @@ ## Remarks This constructor initializes the instance with no date or time limitations. -- The property is set to ., which indicates there is no starting limitation. +- The property is set to ., which indicates there is no starting limitation. -- The property is set to ., which indicates there is no ending limitation. +- The property is set to ., which indicates there is no ending limitation. Use the alternate constructor to create an instance with date and time limitations. diff --git a/xml/System.Security.RightsManagement/ContentUser.xml b/xml/System.Security.RightsManagement/ContentUser.xml index 2583f9680ed..9a57ab386ca 100644 --- a/xml/System.Security.RightsManagement/ContentUser.xml +++ b/xml/System.Security.RightsManagement/ContentUser.xml @@ -30,19 +30,19 @@ Represents a user or user-group for granting access to rights managed content. - types, is only usable in full trust applications. - - - -## Examples - The following example shows how to use property to assign a variable of this type. - + types, is only usable in full trust applications. + + + +## Examples + The following example shows how to use property to assign a variable of this type. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubunpublic"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubunpublic"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubunpublic"::: + ]]> @@ -76,19 +76,19 @@ The method for authentication. Initializes a new instance of the class. - @@ -120,13 +120,13 @@ Gets an instance of the "Anyone" persona. An instance of the "Anyone" persona. - has "Internal" and "Anyone". - - If "Internal" with "Anyone" is granted rights during publishing, the authentication server will issue a to any request and will attach the license to the requesting user. - + has "Internal" and "Anyone". + + If "Internal" with "Anyone" is granted rights during publishing, the authentication server will issue a to any request and will attach the license to the requesting user. + ]]> @@ -254,13 +254,13 @@ if the user is currently authenticated; otherwise, . The default is until authenticated. - is authenticated based on the given . - - After a user has been authenticated and is `true`, the user dialog and prompt to confirm authentication is no longer displayed when creating a . - + is authenticated based on the given . + + After a user has been authenticated and is `true`, the user dialog and prompt to confirm authentication is no longer displayed when creating a . + ]]> @@ -321,13 +321,13 @@ Gets an instance of the "Owner" persona. An instance of the "Owner" persona. - has "Internal" and "Owner". - - is used by the server-side templates to give special rights to the content author or publisher when the protected document is created. - + has "Internal" and "Owner". + + is used by the server-side templates to give special rights to the content author or publisher when the protected document is created. + ]]> diff --git a/xml/System.Security.RightsManagement/CryptoProvider.xml b/xml/System.Security.RightsManagement/CryptoProvider.xml index 53437607ecf..4bffa9f0d91 100644 --- a/xml/System.Security.RightsManagement/CryptoProvider.xml +++ b/xml/System.Security.RightsManagement/CryptoProvider.xml @@ -96,7 +96,7 @@ ## Examples - The following example shows how to use the property in converting clear-text data to encrypted-text data. + The following example shows how to use the property in converting clear-text data to encrypted-text data. :::code language="csharp" source="~/snippets/csharp/System.Security.RightsManagement/CryptoProvider/BlockSize/Window1.xaml.cs" id="Snippetrmcontpubencrypt"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.RightsManagement/CryptoProvider/BlockSize/window1.xaml.vb" id="Snippetrmcontpubencrypt"::: @@ -135,7 +135,7 @@ property to obtain a list rights granted through a . + The following example shows how to use the property to obtain a list rights granted through a . :::code language="csharp" source="~/snippets/csharp/System.Security.RightsManagement/CryptoProvider/BoundGrants/Window1.xaml.cs" id="Snippetrmcontviewuselicense"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.RightsManagement/CryptoProvider/BoundGrants/window1.xaml.vb" id="Snippetrmcontviewuselicense"::: @@ -180,7 +180,7 @@ ## Examples - The following example shows how to use the property to determine if decryption is allowed. + The following example shows how to use the property to determine if decryption is allowed. :::code language="csharp" source="~/snippets/csharp/System.Security.RightsManagement/CryptoProvider/BoundGrants/Window1.xaml.cs" id="Snippetrmcontviewuselicense"::: :::code language="vb" source="~/snippets/visualbasic/System.Security.RightsManagement/CryptoProvider/BoundGrants/window1.xaml.vb" id="Snippetrmcontviewuselicense"::: @@ -454,7 +454,7 @@ property. + The byte length of the `clearText` buffer should be a multiple of the cipher property. The digital rights management system uses AES block cipher. With AES, blocks are encrypted independently such that two blocks of identical clear text produce identical cipher text results. To minimize potential decryption threats from independent block encryption, applications should employ methods to modify content, such as compression, to avoid encrypting identical clear text blocks. diff --git a/xml/System.Security.RightsManagement/LocalizedNameDescriptionPair.xml b/xml/System.Security.RightsManagement/LocalizedNameDescriptionPair.xml index b22ead16e20..ed0420d7911 100644 --- a/xml/System.Security.RightsManagement/LocalizedNameDescriptionPair.xml +++ b/xml/System.Security.RightsManagement/LocalizedNameDescriptionPair.xml @@ -30,11 +30,11 @@ Represents an immutable (read-only) pair of "Name" and "Description" strings. - is a basic building block for structures that express locale specific information for an . - + is a basic building block for structures that express locale specific information for an . + ]]> @@ -100,11 +100,11 @@ Gets the locale description. The locale description. - property is set as a parameter to the constructor. - + property is set as a parameter to the constructor. + ]]> @@ -201,11 +201,11 @@ Gets the locale name. The locale name. - property is set as a parameter to the constructor. - + property is set as a parameter to the constructor. + ]]> diff --git a/xml/System.Security.RightsManagement/PublishLicense.xml b/xml/System.Security.RightsManagement/PublishLicense.xml index 2ab16e3d8b4..2998a30d283 100644 --- a/xml/System.Security.RightsManagement/PublishLicense.xml +++ b/xml/System.Security.RightsManagement/PublishLicense.xml @@ -30,23 +30,23 @@ Represents a signed rights managed publish license. - defines security data about rights, users, and other security-related information. The license defines how a specific user on a specific computer can use specified rights managed content. - - The publishing process begins with the document author, who defines rights information in an . Next, the author creates a signed by calling the method of the . The serialized form of the signed can then be provided to end users who can use it to acquire a by calling the method of the . The returned then allows the client application to exercise the rights that were granted to the user. - - As with other types, is only usable in full trust applications. - - - -## Examples - The following example shows how to initialize a by using the method. - + defines security data about rights, users, and other security-related information. The license defines how a specific user on a specific computer can use specified rights managed content. + + The publishing process begins with the document author, who defines rights information in an . Next, the author creates a signed by calling the method of the . The serialized form of the signed can then be provided to end users who can use it to acquire a by calling the method of the . The returned then allows the client application to exercise the rights that were granted to the user. + + As with other types, is only usable in full trust applications. + + + +## Examples + The following example shows how to initialize a by using the method. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgpubencrypt"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgpubencrypt"::: + ]]> @@ -153,11 +153,11 @@ Attempts to acquire a for a user or user group in a specified . The for a user or user group in the specified . - method suppresses the Windows network authentication dialog box. If the license request is denied because the user does not have permission, prevents the network authentication dialog box from displaying. Use silent acquisition when attempting to obtain licenses in a background task or in a non-user interface that might display confusing dialog boxes. - + method suppresses the Windows network authentication dialog box. If the license request is denied because the user does not have permission, prevents the network authentication dialog box from displaying. Use silent acquisition when attempting to obtain licenses in a background task or in a non-user interface that might display confusing dialog boxes. + ]]> @@ -193,11 +193,11 @@ Gets the publisher-created content identifier. The publisher-created content identifier. - to identify the protected content. - + to identify the protected content. + ]]> @@ -233,11 +233,11 @@ Returns a decrypted version of this signed . A decrypted, unsigned version of this license. - method allows the license owner and users who were granted to extract the original information that was encrypted when the was created. - + method allows the license owner and users who were granted to extract the original information that was encrypted when the was created. + ]]> @@ -272,11 +272,11 @@ Gets the contact name for the author or publisher of the content. The contact name for the author or publisher of the content. - property is not encrypted and can be accessed even when the user does not yet have a . The returned string permits users to contact the publisher to request a . - + property is not encrypted and can be accessed even when the user does not yet have a . The returned string permits users to contact the publisher to request a . + ]]> @@ -309,11 +309,11 @@ Gets the contact URI for the author or publisher of the content. The contact uniform resource identifier (URI) for the author or publisher of the content. - property is not encrypted and can be accessed even when the user does not yet have a . The returned string permits users to contact the publisher to request a . - + property is not encrypted and can be accessed even when the user does not yet have a . The returned string permits users to contact the publisher to request a . + ]]> @@ -376,11 +376,11 @@ Gets the URI to use for acquiring a . The URI to use for acquiring a . - property is used by the method when a user acquires a . - + property is used by the method when a user acquires a . + ]]> diff --git a/xml/System.Security.RightsManagement/RightsManagementException.xml b/xml/System.Security.RightsManagement/RightsManagementException.xml index a7992c10aab..59981272310 100644 --- a/xml/System.Security.RightsManagement/RightsManagementException.xml +++ b/xml/System.Security.RightsManagement/RightsManagementException.xml @@ -31,14 +31,14 @@ Represents an error condition when a rights management operation cannot complete successfully. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> @@ -52,14 +52,14 @@ Initializes a new instance of the class. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> @@ -87,14 +87,14 @@ Initializes a new instance of the class. - . - + . + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> @@ -126,14 +126,14 @@ The failure code for the error. Initializes a new instance of the class with a given . - property to create an error message for the user. - + property to create an error message for the user. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> @@ -171,14 +171,14 @@ A message that describes the error. Initializes a new instance of the class with a given message. - property to create an error message for the user. - + property to create an error message for the user. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> @@ -244,14 +244,14 @@ The exception instance that caused the error. Initializes a new instance of the class with a given and . - and properties to create an error message for the user. - + and properties to create an error message for the user. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> @@ -291,14 +291,14 @@ A message that describes the error. Initializes a new instance of the class with a given and . - and properties to create an error message for the user. - + and properties to create an error message for the user. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> @@ -338,14 +338,14 @@ The exception instance that caused this exception. Initializes a new instance of the class with a given and . - property to create an error message for the user. - + property to create an error message for the user. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> @@ -387,14 +387,14 @@ The exception instance that caused the error. Initializes a new instance of the class with a given , and . - and properties to create an error message for the user. - + and properties to create an error message for the user. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> @@ -432,14 +432,14 @@ Gets the for the error. The failure code for the error. - and properties to create an error message for the user. - + and properties to create an error message for the user. + :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/EncryptedPackageEnvelope/Close/Window1.xaml.cs" id="Snippetrmpkgbldsecenv"::: - :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: - + :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/EncryptedPackageEnvelope/Close/window1.xaml.vb" id="Snippetrmpkgbldsecenv"::: + ]]> diff --git a/xml/System.Security.RightsManagement/SecureEnvironment.xml b/xml/System.Security.RightsManagement/SecureEnvironment.xml index bf992d811d5..d584c52a9ea 100644 --- a/xml/System.Security.RightsManagement/SecureEnvironment.xml +++ b/xml/System.Security.RightsManagement/SecureEnvironment.xml @@ -462,7 +462,7 @@ property + The following example shows use of the property :::code language="csharp" source="~/snippets/csharp/System.IO.Packaging/PackageStore/AddPackage/Window1.xaml.cs" id="Snippetrmpkgviewsecenv"::: :::code language="vb" source="~/snippets/visualbasic/System.IO.Packaging/PackageStore/AddPackage/window1.xaml.vb" id="Snippetrmpkgviewsecenv"::: diff --git a/xml/System.Security/AllowPartiallyTrustedCallersAttribute.xml b/xml/System.Security/AllowPartiallyTrustedCallersAttribute.xml index 0511fc8eefd..0262df9fe4c 100644 --- a/xml/System.Security/AllowPartiallyTrustedCallersAttribute.xml +++ b/xml/System.Security/AllowPartiallyTrustedCallersAttribute.xml @@ -214,7 +214,7 @@ [assembly: AllowPartiallyTrustedCallers(PartialTrustVisibilityLevel=NotVisibleByDefault)] ``` - The assembly has been audited for partial trust, but it is not visible to partial-trust code by default. To make the assembly visible to partial-trust code, add it to the property. + The assembly has been audited for partial trust, but it is not visible to partial-trust code by default. To make the assembly visible to partial-trust code, add it to the property. ]]> diff --git a/xml/System.Security/HostProtectionException.xml b/xml/System.Security/HostProtectionException.xml index 4f57b131b54..3e846380d2b 100644 --- a/xml/System.Security/HostProtectionException.xml +++ b/xml/System.Security/HostProtectionException.xml @@ -261,7 +261,7 @@ 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. + An exception that is thrown as a direct result of a previous exception can include a reference to the previous exception in the 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. ]]> @@ -349,7 +349,7 @@ attribute that indicates that the method exposes shared state. When the method is called, the performs a link demand for shared state. If the host has set shared state as a prohibited category, then a is raised, and the value of the property is . + This property returns the demanded host protection categories that caused the exception to be thrown. For example, suppose that a method has a attribute that indicates that the method exposes shared state. When the method is called, the performs a link demand for shared state. If the host has set shared state as a prohibited category, then a is raised, and the value of the property is . ]]> diff --git a/xml/System.Security/HostSecurityManager.xml b/xml/System.Security/HostSecurityManager.xml index 0d078f41625..0ea86b5b70c 100644 --- a/xml/System.Security/HostSecurityManager.xml +++ b/xml/System.Security/HostSecurityManager.xml @@ -280,7 +280,7 @@ ## Examples - The following example shows how to override the property for a custom host security manager. This example is part of a larger example provided for the class. + The following example shows how to override the property for a custom host security manager. This example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/HostSecurityManager/Overview/customsecuritymanager.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/HostSecurityManager/Overview/customsecuritymanager.vb" id="Snippet2"::: @@ -329,9 +329,9 @@ ## Remarks This method can be overridden by a derived class. The base implementation returns `null`. - The common language runtime calls this method when evidence of the specified type is needed for the current . The returned value is used as host-supplied evidence, and is stored in the collection of the property. You can use the method to obtain the generated evidence from the collection. + The common language runtime calls this method when evidence of the specified type is needed for the current . The returned value is used as host-supplied evidence, and is stored in the collection of the property. You can use the method to obtain the generated evidence from the collection. - To get a callback to this method, hosts must specify the flag in the property. + To get a callback to this method, hosts must specify the flag in the property. This method of generating evidence allows hosts to delay evidence generation for an until the evidence is needed. In the .NET Framework version 3.5 and earlier versions, it was necessary to provide evidence at load time by overriding the method. We recommend that you use to provide evidence instead of overriding . @@ -393,9 +393,9 @@ ## Remarks This method can be overridden by a derived class. The base implementation returns `null`. - The common language runtime calls this method when evidence of the specified type is needed for the current assembly. The returned value is used as host-supplied evidence, and is stored in the property. You can use the method to obtain the generated evidence from the property. + The common language runtime calls this method when evidence of the specified type is needed for the current assembly. The returned value is used as host-supplied evidence, and is stored in the property. You can use the method to obtain the generated evidence from the property. - To get a callback to this method, hosts must specify the flag in the property. + To get a callback to this method, hosts must specify the flag in the property. This method of generating evidence allows hosts to delay evidence generation for an until the evidence is needed. In the .NET Framework 3.5 and earlier versions, it was necessary to provide evidence at load time by overriding the method. We recommend that you use to provide evidence instead of overriding . diff --git a/xml/System.Security/PartialTrustVisibilityLevel.xml b/xml/System.Security/PartialTrustVisibilityLevel.xml index d45f281801e..5b73970f3d1 100644 --- a/xml/System.Security/PartialTrustVisibilityLevel.xml +++ b/xml/System.Security/PartialTrustVisibilityLevel.xml @@ -43,15 +43,15 @@ Specifies the default partial-trust visibility for code that is marked with the (APTCA) attribute. - is passed as a property setting parameter to the constructor. If no parameter is passed to the constructor, the default is VisibleToAllHosts. - - You enable partially trusted assemblies that are identified as NotVisibleByDefault by adding them to the property of their application domain. If you enable an assembly that references (directly or indirectly) other partially trusted assemblies that are NotVisibleByDefault, those other assemblies should be enabled as well. - - When an APTCA library that specifies a `PartialTrustVisibilityLevel` and that is eligible for code sharing is loaded for the first time, it is loaded into the shared domain. Whenever that assembly is loaded with the same `PartialTrustVisibilityLevel` into another domain, it will be shared. However, if the assembly is loaded with a different `PartialTrustVisibilityLevel`, it will not be shared. - + is passed as a property setting parameter to the constructor. If no parameter is passed to the constructor, the default is VisibleToAllHosts. + + You enable partially trusted assemblies that are identified as NotVisibleByDefault by adding them to the property of their application domain. If you enable an assembly that references (directly or indirectly) other partially trusted assemblies that are NotVisibleByDefault, those other assemblies should be enabled as well. + + When an APTCA library that specifies a `PartialTrustVisibilityLevel` and that is eligible for code sharing is loaded for the first time, it is loaded into the shared domain. Whenever that assembly is loaded with the same `PartialTrustVisibilityLevel` into another domain, it will be shared. However, if the assembly is loaded with a different `PartialTrustVisibilityLevel`, it will not be shared. + ]]> diff --git a/xml/System.Security/SecureString.xml b/xml/System.Security/SecureString.xml index b575b000683..1c0ce98efa5 100644 --- a/xml/System.Security/SecureString.xml +++ b/xml/System.Security/SecureString.xml @@ -708,7 +708,7 @@ The following example demonstrates how to use a 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 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. diff --git a/xml/System.Security/SecurityElement.xml b/xml/System.Security/SecurityElement.xml index 46931998db9..996fb56d3ab 100644 --- a/xml/System.Security/SecurityElement.xml +++ b/xml/System.Security/SecurityElement.xml @@ -571,7 +571,7 @@ ## Examples - The following code shows the use of the property to get an attribute of an XML element. This code example is part of a larger example provided for the class. + The following code shows the use of the property to get an attribute of an XML element. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet15"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet15"::: @@ -641,7 +641,7 @@ ## Examples - The following code shows the use of the property to get the array of child elements of the XML element. This code example is part of a larger example provided for the class. + The following code shows the use of the property to get the array of child elements of the XML element. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet14"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet14"::: @@ -1526,7 +1526,7 @@ ## Examples - The following code shows the use of the property to get the tag name of an XML element. This code example is part of a larger example provided for the class. + The following code shows the use of the property to get the tag name of an XML element. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet11"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet11"::: @@ -1598,7 +1598,7 @@ ## Examples - The following code shows the use of the property to get the text of an XML element. This code example is part of a larger example provided for the class. + The following code shows the use of the property to get the text of an XML element. This code example is part of a larger example provided for the class. :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityElement/Overview/securityelementmembers.cs" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Security/SecurityElement/Overview/Form1.vb" id="Snippet12"::: diff --git a/xml/System.Security/SecurityException.xml b/xml/System.Security/SecurityException.xml index 8d3851884d2..e291b17841f 100644 --- a/xml/System.Security/SecurityException.xml +++ b/xml/System.Security/SecurityException.xml @@ -377,7 +377,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 the class. @@ -719,17 +719,17 @@ property contains the security action that caused the security check failure. Many of the security actions can cause a security exception to be thrown. For example, a demand on a permission set checks that all callers on the call stack have the necessary permissions in the permission set. If any caller on the call stack lacks a required permission, the security check fails. Alternatively, a method in the call chain can modify the outcome of the stack walk by placing a stack walk modifier, such as or , on the stack to limit the allowed permissions. For example, a method on the call stack might deny all of its callers a set of permissions named PSET1, such that any demand for a permission that is part of PSET1 fails for those callers. The property contains the security action that caused the exception to be thrown. + The property contains the security action that caused the security check failure. Many of the security actions can cause a security exception to be thrown. For example, a demand on a permission set checks that all callers on the call stack have the necessary permissions in the permission set. If any caller on the call stack lacks a required permission, the security check fails. Alternatively, a method in the call chain can modify the outcome of the stack walk by placing a stack walk modifier, such as or , on the stack to limit the allowed permissions. For example, a method on the call stack might deny all of its callers a set of permissions named PSET1, such that any demand for a permission that is part of PSET1 fails for those callers. The property contains the security action that caused the exception to be thrown. - is an enumeration in the namespace that provides the security action value for the property. Typically this property contains one of the values shown in the following table. + is an enumeration in the namespace that provides the security action value for the property. Typically this property contains one of the values shown in the following table. |Security action|Description| |---------------------|-----------------| -||A full stack walk failed due to a demand made against the assembly identified by the property.| -||A link demand against the assembly identified by the property failed.| -||An assembly identified by the property failed to meet an inheritance demand.| -||A demanded permission did not match any permission in the permission set. The method that placed the on the call stack is identified by the property.| -||A demanded permission matched a permission in the deny permission set on the call stack. The method that placed the on the call stack is identified by the property.| +||A full stack walk failed due to a demand made against the assembly identified by the property.| +||A link demand against the assembly identified by the property failed.| +||An assembly identified by the property failed to meet an inheritance demand.| +||A demanded permission did not match any permission in the permission set. The method that placed the on the call stack is identified by the property.| +||A demanded permission matched a permission in the deny permission set on the call stack. The method that placed the on the call stack is identified by the property.| ]]> @@ -797,7 +797,7 @@ ## Examples - The following code example shows the use of the property to display the demanded security permission, permission set, or permission set collection that failed. This code example is part of a larger example provided for the class. + The following code example shows the use of the property to display the demanded security permission, permission set, or permission set collection that failed. This code example is part of a larger example provided for the class. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.SecurityException/CPP/form1.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityException/.ctor/form1.cs" id="Snippet3"::: @@ -931,7 +931,7 @@ ## Examples - The following code example shows the use of the property to display the information about the failed assembly. + The following code example shows the use of the property to display the information about the failed assembly. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Security.SecurityException/CPP/form1.cpp" id="Snippet12"::: :::code language="csharp" source="~/snippets/csharp/System.Security/SecurityException/.ctor/form1.cs" id="Snippet12"::: @@ -1363,7 +1363,7 @@ property represents the permitted permission, permission set, or permission set collection contained in the stack frame that caused the security exception. For instance, when a security exception occurs because of a failure, the permitted permission appears in this property and the demanded is contained in the property. + The property represents the permitted permission, permission set, or permission set collection contained in the stack frame that caused the security exception. For instance, when a security exception occurs because of a failure, the permitted permission appears in this property and the demanded is contained in the property. This property is of type because permissions, permission sets, or permission set collections can all be demanded and is their common base class. To test the run-time type of this property, you can use the method or a specific language operator, such as the [is operator](/dotnet/csharp/language-reference/keywords/is) in C# or the [TypeOf operator](/dotnet/visual-basic/language-reference/operators/typeof-operator) in Visual Basic. diff --git a/xml/System.Security/VerificationException.xml b/xml/System.Security/VerificationException.xml index 17783de6d58..dbf57029972 100644 --- a/xml/System.Security/VerificationException.xml +++ b/xml/System.Security/VerificationException.xml @@ -300,7 +300,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Security/XmlSyntaxException.xml b/xml/System.Security/XmlSyntaxException.xml index df8d2bed2b5..4f86ec4e05d 100644 --- a/xml/System.Security/XmlSyntaxException.xml +++ b/xml/System.Security/XmlSyntaxException.xml @@ -50,13 +50,13 @@ The exception that is thrown when there is a syntax error in XML parsing. This class cannot be inherited. - uses the default implementation, which supports reference equality. - - For a list of initial property values for an instance of , see the constructor. - + uses the default implementation, which supports reference equality. + + For a list of initial property values for an instance of , see the constructor. + ]]> @@ -103,16 +103,16 @@ Initializes a new instance of the class with default properties. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||"Invalid syntax."| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||"Invalid syntax."| + ]]> @@ -151,18 +151,18 @@ The line number of the XML stream where the XML syntax error was detected. Initializes a new instance of the class with the line number where the exception was detected. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||"Invalid syntax on line `lineNumber`."| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||"Invalid syntax on line `lineNumber`."| + ]]> @@ -201,16 +201,16 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||The error message string.| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||The error message string.| + ]]> @@ -251,18 +251,18 @@ The error message that explains the reason for the exception. Initializes a new instance of the class with a specified error message and the line number where the exception was detected. - . - -|Property|Value| -|--------------|-----------| -||`null`.| -||"Invalid syntax on line `lineNumber` - `message` "| - + . + +|Property|Value| +|--------------|-----------| +||`null`.| +||"Invalid syntax on line `lineNumber` - `message` "| + ]]> @@ -303,18 +303,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 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.ServiceProcess.Design/ServiceInstallerDialogResult.xml b/xml/System.ServiceProcess.Design/ServiceInstallerDialogResult.xml index bb1e5019592..3908eb47f78 100644 --- a/xml/System.ServiceProcess.Design/ServiceInstallerDialogResult.xml +++ b/xml/System.ServiceProcess.Design/ServiceInstallerDialogResult.xml @@ -17,19 +17,19 @@ Specifies the return value of a form. - property uses this enumeration to indicate the user response to the dialog box. - - - -## Examples - The following example uses a to prompt the user for a service installation account. - + property uses this enumeration to indicate the user response to the dialog box. + + + +## Examples + The following example uses a to prompt the user for a service installation account. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ServiceInstallConfig/CPP/source.cpp" id="Snippet1"::: - :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess.Design/ServiceInstallerDialog/Overview/source.cs" id="Snippet1"::: - + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess.Design/ServiceInstallerDialog/Overview/source.cs" id="Snippet1"::: + ]]> diff --git a/xml/System.ServiceProcess/ServiceBase.xml b/xml/System.ServiceProcess/ServiceBase.xml index 137ab07b323..4dd5cb4e168 100644 --- a/xml/System.ServiceProcess/ServiceBase.xml +++ b/xml/System.ServiceProcess/ServiceBase.xml @@ -73,12 +73,12 @@ You can use the class to do programmatically what the SCM does using a user interface. You can automate the tasks available in the console. If , , or is `true` but you have not implemented a corresponding command-handling method (such as ) the system throws an exception and ignores the command. - You do not have to implement , , or any other method in . However, the service's behavior is described in , so at minimum, this member should be overridden. The `main()` function of the executable registers the service in the executable with the Service Control Manager by calling the method. The property of the object passed to the method must match the property of the service installer for that service. + You do not have to implement , , or any other method in . However, the service's behavior is described in , so at minimum, this member should be overridden. The `main()` function of the executable registers the service in the executable with the Service Control Manager by calling the method. The property of the object passed to the method must match the property of the service installer for that service. You can use the `sc create` command to install services that target modern .NET, or use `InstallUtil.exe` to install services that target .NET Framework. > [!NOTE] -> You can specify a log other than the Application event log to receive notification of service calls, but neither the nor the property can write to a custom log. Set to `false` if you do not want to use automatic logging. +> You can specify a log other than the Application event log to receive notification of service calls, but neither the nor the property can write to a custom log. Set to `false` if you do not want to use automatic logging. ]]> @@ -314,7 +314,7 @@ property in the constructor for the service. + Set the value of the property in the constructor for the service. When a service is paused, it halts what it is doing. When you continue the service (either through the Service Control Manager or programmatically), runs. @@ -517,9 +517,9 @@ property to an instance with the and properties set. The source is the of the service, and the log is the computer's Application log. These values are set automatically and cannot be changed for automatic logging of service commands. + The constructor initializes the property to an instance with the and properties set. The source is the of the service, and the log is the computer's Application log. These values are set automatically and cannot be changed for automatic logging of service commands. - When is `true`, Start, Stop, Pause, Continue, and custom commands are recorded automatically in the Application event log. You can use the property to write additional messages to that log as well. The component calls using this member. + When is `true`, Start, Stop, Pause, Continue, and custom commands are recorded automatically in the Application event log. You can use the property to write additional messages to that log as well. The component calls using this member. To report information to a custom event log rather than the Application log, set to `false` and write instructions within the command-handling methods , , or to post to the appropriate log. @@ -564,7 +564,7 @@ property to a non-zero value before stopping the service to indicate an error to the Service Control Manager. + Set the property to a non-zero value before stopping the service to indicate an error to the Service Control Manager. ]]> @@ -637,7 +637,7 @@ ## Remarks Implement to mirror your application's response to . When you continue the service (either through the Services console or programmatically), the processing runs, and the service becomes active again. - is expected to be overridden when the property is `true`. + is expected to be overridden when the property is `true`. If is `false`, the SCM will not pass Pause or Continue requests to the service, so the and methods will not be called even if they are implemented. In the SCM, the `Pause` and `Continue` controls are disabled when is `false`. @@ -692,7 +692,7 @@ The only values for a custom command that you can define in your application or use in are those between 128 and 255. Integers below 128 correspond to system-reserved values. - If the property is `true`, custom commands, like all other commands, write entries to the event log to report whether the method execution succeeded or failed. + If the property is `true`, custom commands, like all other commands, write entries to the event log to report whether the method execution succeeded or failed. ]]> @@ -733,7 +733,7 @@ to specify the processing that occurs when the service receives a Pause command. is expected to be overridden when the property is `true`. + Use to specify the processing that occurs when the service receives a Pause command. is expected to be overridden when the property is `true`. When you continue a paused service (either through the Services console or programmatically), the processing is run, and the service becomes active again. @@ -791,7 +791,7 @@ ## Remarks Use to specify the processing that occurs when the system event indicated in the enumeration occurs--for example, when the computer is placed in suspended mode or indicates low battery power. - is expected to be overridden when the property is `true`. + is expected to be overridden when the property is `true`. ]]> @@ -835,7 +835,7 @@ property to `true` to enable the execution of this method. + You must set the property to `true` to enable the execution of this method. ]]> @@ -876,7 +876,7 @@ This event occurs only when the operating system is shut down, not when the computer is turned off. - is expected to be overridden when the property is `true`. + is expected to be overridden when the property is `true`. ]]> @@ -1294,9 +1294,9 @@ identifies the service to the Service Control Manager. The value of this property must be identical to the name recorded for the service in the property of the corresponding installer class. In code, the of the service is usually set in the `main()` function of the executable. + The identifies the service to the Service Control Manager. The value of this property must be identical to the name recorded for the service in the property of the corresponding installer class. In code, the of the service is usually set in the `main()` function of the executable. - The is also used to specify the associated with the property. This is an instance that writes service command information to the Application log. + The is also used to specify the associated with the property. This is an instance that writes service command information to the Application log. The , which supplies the source string for the event log, must be set before the service writes to the event log. Trying to access the event log before the source name is set causes an exception to be thrown. diff --git a/xml/System.ServiceProcess/ServiceController.xml b/xml/System.ServiceProcess/ServiceController.xml index b66c100ff39..b73be4fb11d 100644 --- a/xml/System.ServiceProcess/ServiceController.xml +++ b/xml/System.ServiceProcess/ServiceController.xml @@ -87,7 +87,7 @@ Generally, the service author writes code that customizes the action associated with a specific command. For example, a service can contain code to respond to an command. In that case, the custom processing for the task runs before the system pauses the service. - The set of commands a service can process depends on its properties; for example, you can set the property for a service to `false`. This setting renders the `Stop` command unavailable on that particular service; it prevents you from stopping the service from the SCM by disabling the necessary button. If you try to stop the service from your code, the system raises an error and displays the error message "Failed to stop `servicename`." + The set of commands a service can process depends on its properties; for example, you can set the property for a service to `false`. This setting renders the `Stop` command unavailable on that particular service; it prevents you from stopping the service from the SCM by disabling the necessary button. If you try to stop the service from your code, the system raises an error and displays the error message "Failed to stop `servicename`." @@ -263,7 +263,7 @@ property to determine whether a service can pause and continue. This example is part of a larger example that is provided for the class. + The following example demonstrates the use of the property to determine whether a service can pause and continue. This example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceController/Overview/program.vb" id="Snippet2"::: @@ -315,7 +315,7 @@ property to determine whether a service provides a handler for a shutdown event. This example is part of a larger example that is provided for the class. + The following example demonstrates the use of the property to determine whether a service provides a handler for a shutdown event. This example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceController/Overview/program.vb" id="Snippet2"::: @@ -367,7 +367,7 @@ property to determine whether a service provides a handler for a stop event. This example is part of a larger example that is provided for the class. + The following example demonstrates the use of the property to determine whether a service provides a handler for a stop event. This example is part of a larger example that is provided for the class. :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceController/Overview/program.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceController/Overview/program.vb" id="Snippet2"::: @@ -1173,9 +1173,9 @@ ## Remarks The identifies the service to the Service Control Manager. Changing this property causes the instance to bind to another service, it does not change what the Service Control Manager's Microsoft Management Console snap-in displays. - When you are implementing a custom service, the value of this property must be identical to the name recorded for the service in the property of the corresponding class. In code, the is usually set in the `main()` function of the executable. + When you are implementing a custom service, the value of this property must be identical to the name recorded for the service in the property of the corresponding class. In code, the is usually set in the `main()` function of the executable. - When you reset the property, the method that sets the property sets this instance's to an empty string (""). + When you reset the property, the method that sets the property sets this instance's to an empty string (""). ]]> @@ -1281,7 +1281,7 @@ property represents a set of flags combined using the bitwise OR operator. + The service type indicates how the service is used by the system. The value of the property represents a set of flags combined using the bitwise OR operator. @@ -1532,9 +1532,9 @@ property contains the set of services that depend on this one. + If any services depend on this service for their operation, they will be stopped before this service is stopped. The property contains the set of services that depend on this one. - If you stop a service that this service depends on, call the method on this service within the method of the parent service. The property contains the services that this service depends on. + If you stop a service that this service depends on, call the method on this service within the method of the parent service. The property contains the services that this service depends on. diff --git a/xml/System.ServiceProcess/ServiceInstaller.xml b/xml/System.ServiceProcess/ServiceInstaller.xml index 31dec5dff76..30734dc52af 100644 --- a/xml/System.ServiceProcess/ServiceInstaller.xml +++ b/xml/System.ServiceProcess/ServiceInstaller.xml @@ -18,48 +18,48 @@ Installs a class that extends to implement a service. This class is called by the install utility when installing a service application. - does work specific to the service with which it is associated. It is used by the installation utility to write registry values associated with the service to a subkey within the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services registry key. The service is identified by its ServiceName within this subkey. The subkey also includes the name of the executable or .dll to which the service belongs. - - To install a service, create a project installer class that inherits from the class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. - + does work specific to the service with which it is associated. It is used by the installation utility to write registry values associated with the service to a subkey within the HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services registry key. The service is identified by its ServiceName within this subkey. The subkey also includes the name of the executable or .dll to which the service belongs. + + To install a service, create a project installer class that inherits from the class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. + > [!NOTE] -> It is recommended that you use the constructor for adding installer instances; however, if you need to add to the collection in the method, be sure to perform the same additions to the collection in the method. - - For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor.When the install utility is called, it looks for the attribute. If the attribute is `true`, the utility installs all the services that were added to the collection that were associated with your project installer. If is `false` or does not exist, the install utility ignores the project installer. - - The associated with your project installation class installs information common to all instances in the project. If this service has anything that separates it from the other services in the installation project, that service-specific information is installed by this method. - +> It is recommended that you use the constructor for adding installer instances; however, if you need to add to the collection in the method, be sure to perform the same additions to the collection in the method. + + For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor.When the install utility is called, it looks for the attribute. If the attribute is `true`, the utility installs all the services that were added to the collection that were associated with your project installer. If is `false` or does not exist, the install utility ignores the project installer. + + The associated with your project installation class installs information common to all instances in the project. If this service has anything that separates it from the other services in the installation project, that service-specific information is installed by this method. + > [!NOTE] -> It is crucial that the be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. - - You can modify other properties on the either before or after adding it to the collection of your project installer. For example, a service's may be set to start the service automatically at reboot or require a user to start the service manually. - - Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. - - The installation utility calls to remove the object. - - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance, and each instance is installed by the utility. It is usually unnecessary for your code to modify state information explicitly. - - When the installation is performed, it automatically creates an to install the event log source associated with the derived class. The property for this source is set by the constructor to the computer's Application log. When you set the of the (which should be identical to the of the service), the is automatically set to the same value. In an installation failure, the source's installation is rolled-back along with previously installed services. - - The method tries to stop the service if it is running. Whether this succeeds or not, undoes the changes made by . If a new source was created for event logging, the source is deleted. - - - -## Examples - The following example creates a project installer, called `MyProjectInstaller`, which inherits from . It is assumed there is a service executable that contains two services, "Hello-World Service 1" and "Hello-World Service 2". Within the constructor for `MyProjectInstaller` (which would be called by the install utility), objects are created for each of these services, and a is created for the executable. For the install utility to recognize `MyProjectInstaller` as a valid installer, the attribute is set to `true`. - - Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses `MyProjectInstaller`, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each can be backed out in turn, if an installation failure occurs. - - Normally, you would not create an instance of your project installer class explicitly. You would create it and add the attribute to the syntax, but it is the install utility that actually calls, and therefore instantiates, the class. - +> It is crucial that the be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. + + You can modify other properties on the either before or after adding it to the collection of your project installer. For example, a service's may be set to start the service automatically at reboot or require a user to start the service manually. + + Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. + + The installation utility calls to remove the object. + + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance, and each instance is installed by the utility. It is usually unnecessary for your code to modify state information explicitly. + + When the installation is performed, it automatically creates an to install the event log source associated with the derived class. The property for this source is set by the constructor to the computer's Application log. When you set the of the (which should be identical to the of the service), the is automatically set to the same value. In an installation failure, the source's installation is rolled-back along with previously installed services. + + The method tries to stop the service if it is running. Whether this succeeds or not, undoes the changes made by . If a new source was created for event logging, the source is deleted. + + + +## Examples + The following example creates a project installer, called `MyProjectInstaller`, which inherits from . It is assumed there is a service executable that contains two services, "Hello-World Service 1" and "Hello-World Service 2". Within the constructor for `MyProjectInstaller` (which would be called by the install utility), objects are created for each of these services, and a is created for the executable. For the install utility to recognize `MyProjectInstaller` as a valid installer, the attribute is set to `true`. + + Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses `MyProjectInstaller`, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each can be backed out in turn, if an installation failure occurs. + + Normally, you would not create an instance of your project installer class explicitly. You would create it and add the attribute to the syntax, but it is the install utility that actually calls, and therefore instantiates, the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ServiceInstaller Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceAccount/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceAccount/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceAccount/Overview/source.vb" id="Snippet1"::: + ]]> @@ -85,15 +85,15 @@ Initializes a new instance of the class. - class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. - - The constructor automatically generates an event log source whose property is set to the computer's Application log, and an . When you set the of the , which should be identical to the of the service, the property of the event log is automatically set to the same value. The source is deleted automatically in the case of an installation failure. - - The constructor sets the property to `ServiceStartMode.Manual` to specify that a user start the service. You can reset the property to `ServiceStartMode.Automatic` to specify that the service start when the computer reboots. - + class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. + + The constructor automatically generates an event log source whose property is set to the computer's Application log, and an . When you set the of the , which should be identical to the of the service, the property of the event log is automatically set to the same value. The source is deleted automatically in the case of an installation failure. + + The constructor sets the property to `ServiceStartMode.Manual` to specify that a user start the service. You can reset the property to `ServiceStartMode.Automatic` to specify that the service start when the computer reboots. + ]]> @@ -124,16 +124,16 @@ The from which to copy. Copies properties from an instance of to this installer. - is usually called only by designers. - - saves the service name of the `component` parameter to the of the instance. (Because the parameter must be an instance of a class that derives from , `component` is guaranteed to have a property.) - + is usually called only by designers. + + saves the service name of the `component` parameter to the of the instance. (Because the parameter must be an instance of a class that derives from , `component` is guaranteed to have a property.) + > [!NOTE] -> If you are using the Visual Studio designer, this method is called at design time when the user clicks `Add Installer` on a component that specified this class as its installer. The installer takes all information it can from the live component and stores it for use at install time. - +> If you are using the Visual Studio designer, this method is called at design time when the user clicks `Add Installer` on a component that specified this class as its installer. The installer takes all information it can from the live component and stores it for use at install time. + ]]> The component you are associating with this installer does not inherit from . @@ -170,15 +170,15 @@ to delay automatic start of the service; otherwise, . The default is . - property can be applied to any service, but it is ignored unless the service's start mode is . The setting takes effect the next time the system is restarted. The Service Control Manager does not guarantee a specific start time for the service. - - A delayed automatic start service cannot be a member of a load ordering group, but it can depend on another automatic start service. If an application calls a delayed automatic start service before it is loaded, the call fails. - - On operating systems that do not support delayed automatic start, setting this property has no effect. - + property can be applied to any service, but it is ignored unless the service's start mode is . The setting takes effect the next time the system is restarted. The Service Control Manager does not guarantee a specific start time for the service. + + A delayed automatic start service cannot be a member of a load ordering group, but it can depend on another automatic start service. If an application calls a delayed automatic start service before it is loaded, the call fails. + + On operating systems that do not support delayed automatic start, setting this property has no effect. + ]]> @@ -217,21 +217,21 @@ Gets or sets the description for the service. The description of the service. The default is an empty string (""). - property to describe the purpose of the installed service to the user. The user can view the service description in applications that display details for installed services. - - For example, using Windows XP, you can view the service description with the Service Control command-line utility (Sc.exe) or you can view the service description within the **Services** node of the **Computer Management** console. - - - -## Examples - The following code example sets the installation properties for a new Windows service application. The example sets the service name, along with the display name and description. After assigning the installation properties for the service, the example adds the object to the collection. - + property to describe the purpose of the installed service to the user. The user can view the service description in applications that display details for installed services. + + For example, using Windows XP, you can view the service description with the Service Control command-line utility (Sc.exe) or you can view the service description within the **Services** node of the **Computer Management** console. + + + +## Examples + The following code example sets the installation properties for a new Windows service application. The example sets the service name, along with the display name and description. After assigning the installation properties for the service, the example adds the object to the collection. + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceInstaller/Description/simpleserviceinstaller.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceInstaller/Description/service1.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceInstaller/Description/service1.vb" id="Snippet3"::: + ]]> @@ -269,13 +269,13 @@ Indicates the friendly name that identifies the service to the user. The name associated with the service, used frequently for interactive tools. - is used, for example, in the Service Control Manager to provide a user-readable descriptive name for the service. The is a registry value, but is never used as a registry key. Therefore, restrictions on the property value do not apply. is used as the HKEY_LOCAL_MACHINES\System\CurrentControlSet\Services registry key, so it is restricted. - - The display name is never used by the install utility to identify the service, so there are no restrictions on the choice of name, as there is for the property. - + is used, for example, in the Service Control Manager to provide a user-readable descriptive name for the service. The is a registry value, but is never used as a registry key. Therefore, restrictions on the property value do not apply. is used as the HKEY_LOCAL_MACHINES\System\CurrentControlSet\Services registry key, so it is restricted. + + The display name is never used by the install utility to identify the service, so there are no restrictions on the choice of name, as there is for the property. + ]]> @@ -306,42 +306,42 @@ An that contains the context information associated with the installation. Installs the service by writing service application information to the registry. This method is meant to be used by installation tools, which process the appropriate methods automatically. - within your code; they are generally called only by the install utility. The install utility automatically calls the method during installation. It backs out failures, if necessary, by calling on the object that generated the exception. - - An application's install routine maintains information automatically about the components that were already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. - - The associated with your project installation class installs information common to all instances in the project. If this service has anything that separates it from the other services in the installation project, that service-specific information is installed by this method. - - To install a service, create a project installer class that inherits from the class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. - + within your code; they are generally called only by the install utility. The install utility automatically calls the method during installation. It backs out failures, if necessary, by calling on the object that generated the exception. + + An application's install routine maintains information automatically about the components that were already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + + The associated with your project installation class installs information common to all instances in the project. If this service has anything that separates it from the other services in the installation project, that service-specific information is installed by this method. + + To install a service, create a project installer class that inherits from the class, and set the attribute on the class to `true`. Within your project, create one instance per service application, and one instance for each service in the application. Within your project installer class constructor, set the installation properties for the service using the and instances, and add the instances to the collection. + > [!NOTE] -> It is recommended that you use the constructor for adding installer instances; however, if you need to add to the collection in the method, be sure to perform the same additions to the collection in the method. - - For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor. - +> It is recommended that you use the constructor for adding installer instances; however, if you need to add to the collection in the method, be sure to perform the same additions to the collection in the method. + + For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor. + ]]> - The installation does not contain a for the executable. - - -or- - - The file name for the assembly is or an empty string. - - -or- - - The service name is invalid. - - -or- - + The installation does not contain a for the executable. + + -or- + + The file name for the assembly is or an empty string. + + -or- + + The service name is invalid. + + -or- + The Service Control Manager could not be opened. The display name for the service is more than 255 characters in length. - The system could not generate a handle to the service. - - -or- - + The system could not generate a handle to the service. + + -or- + A service with that name is already installed. @@ -377,11 +377,11 @@ if calling on both of these installers would result in installing the same service; otherwise, . - indicates, for example, whether two installers would install the same service under the same user account. - + indicates, for example, whether two installers would install the same service under the same user account. + ]]> @@ -412,13 +412,13 @@ An that contains the context information associated with the installation. Rolls back service application information written to the registry by the installation procedure. This method is meant to be used by installation tools, which process the appropriate methods automatically. - within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. - - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. - + within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. + + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + ]]> @@ -470,18 +470,18 @@ Indicates the name used by the system to identify this service. This property must be identical to the of the service you want to install. The name of the service to be installed. This value must be set before the install utility attempts to install the service. - be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. - - When you set the of the service installer, the of the associated event log is set to the same value. This allows the service to automatically log service commands (such as Start and Stop) calls to the Application log on the computer. - + be identical to the of the class you derived from . Normally, the value of the property for the service is set within the Main() function of the service application's executable. The Service Control Manager uses the property to locate the service within this executable. + + When you set the of the service installer, the of the associated event log is set to the same value. This allows the service to automatically log service commands (such as Start and Stop) calls to the Application log on the computer. + > [!NOTE] -> If a source by the same name already exists on the computer, but in a log other than the Application log, an exception will be thrown. If the source exists and is associated with the Application log, that source is used to report command calls to the service, and no exception is thrown. - - The cannot be `null` or have zero length. Its maximum size is 256 characters. It also cannot contain forward or backward slashes, '/' or '\\', or characters from the ASCII character set with value less than decimal value 32. - +> If a source by the same name already exists on the computer, but in a log other than the Application log, an exception will be thrown. If the source exists and is associated with the Application log, that source is used to report command calls to the service, and no exception is thrown. + + The cannot be `null` or have zero length. Its maximum size is 256 characters. It also cannot contain forward or backward slashes, '/' or '\\', or characters from the ASCII character set with value less than decimal value 32. + ]]> The property is invalid. @@ -516,19 +516,19 @@ Indicates the services that must be running for this service to run. An array of services that must be running before the service associated with this installer can run. - . - - If any service upon which this service depends fails to start, this service will not start. An exception is not thrown if the system is not started because there is no exception handling at the system level to detect this. Decide how to handle service start failures and implement this in your code. Typically, a dialog appears to the user at startup if a service fails to start. - - If the service does not start, an entry is written to the Application event log. - - The services upon which this service depends do not need to be in the same executable. - + . + + If any service upon which this service depends fails to start, this service will not start. An exception is not thrown if the system is not started because there is no exception handling at the system level to detect this. Decide how to handle service start failures and implement this in your code. Typically, a dialog appears to the user at startup if a service fails to start. + + If the service does not start, an entry is written to the Application event log. + + The services upon which this service depends do not need to be in the same executable. + ]]> @@ -565,13 +565,13 @@ Indicates how and when this service is started. A that represents the way the service is started. The default is , which specifies that the service will not automatically start after reboot. - to specify either that the service be started automatically after reboot or that a user must manually start the service. A service can also be disabled, specifying that it cannot be started, either manually or programmatically, until it is enabled. - - You cannot change property values after installation. To change the , you either have to uninstall and reinstall your service, or manually change the setting using the Service Control Manager. - + to specify either that the service be started automatically after reboot or that a user must manually start the service. A service can also be disabled, specifying that it cannot be started, either manually or programmatically, until it is enabled. + + You cannot change property values after installation. To change the , you either have to uninstall and reinstall your service, or manually change the setting using the Service Control Manager. + ]]> The start mode is not a value of the enumeration. @@ -602,25 +602,25 @@ An that contains the context information associated with the installation. Uninstalls the service by removing information about it from the registry. - within your code; they are generally called only by the install utility. InstallUtil is used to uninstall services as well as install them; uninstalling takes a switch in the command line call. - - An application's uninstall routine maintains information automatically about the components being uninstalled, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. - - For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor. - - There is no rollback mechanism for uninstalling, so if one service fails to uninstall, this does not affect the other services (usually within the same installation project) being uninstalled. - + within your code; they are generally called only by the install utility. InstallUtil is used to uninstall services as well as install them; uninstalling takes a switch in the command line call. + + An application's uninstall routine maintains information automatically about the components being uninstalled, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + + For all classes deriving from the class, the state of the collection must be the same in the and methods. However, you can avoid the maintenance of the collection across the and methods if you add installer instances to the collection in your custom installer class constructor. + + There is no rollback mechanism for uninstalling, so if one service fails to uninstall, this does not affect the other services (usually within the same installation project) being uninstalled. + ]]> - The Service Control Manager could not be opened. - - -or- - + The Service Control Manager could not be opened. + + -or- + The system could not get a handle to the service. diff --git a/xml/System.ServiceProcess/ServiceProcessDescriptionAttribute.xml b/xml/System.ServiceProcess/ServiceProcessDescriptionAttribute.xml index 94c5600a20b..ccb383792ee 100644 --- a/xml/System.ServiceProcess/ServiceProcessDescriptionAttribute.xml +++ b/xml/System.ServiceProcess/ServiceProcessDescriptionAttribute.xml @@ -50,11 +50,11 @@ Specifies a description for a property or event. - property to get or set the text associated with this attribute. - + property to get or set the text associated with this attribute. + ]]> @@ -87,11 +87,11 @@ The application-defined description text. Initializes a new instance of the class, using the specified description. - constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies. - + constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies. + ]]> diff --git a/xml/System.ServiceProcess/ServiceProcessInstaller.xml b/xml/System.ServiceProcess/ServiceProcessInstaller.xml index bad63f298bd..5999a659138 100644 --- a/xml/System.ServiceProcess/ServiceProcessInstaller.xml +++ b/xml/System.ServiceProcess/ServiceProcessInstaller.xml @@ -18,39 +18,39 @@ Installs an executable containing classes that extend . This class is called by installation utilities, such as InstallUtil.exe, when installing a service application. - does work common to all services in an executable. It is used by the installation utility to write registry values associated with services you want to install. - - To install a service, create a project installer class that inherits from , and set the on the class to `true`. Within your project, instantiate one instance per service application, and one instance for each service in the application. Finally, add the instance and the instances to your project installer class. - - When InstallUtil.exe runs, the utility looks for classes in the service assembly with the set to `true`. Add classes to the service assembly by adding them to the collection associated with your project installer. If is `false`, the install utility ignores the project installer. - - For an instance of , properties you can modify include specifying that a service application run under an account other than the logged-on user. You can specify a particular and pair under which the service should run, or you can use to specify that the service run under the computer's System account, a local or network service account, or a user account. - + does work common to all services in an executable. It is used by the installation utility to write registry values associated with services you want to install. + + To install a service, create a project installer class that inherits from , and set the on the class to `true`. Within your project, instantiate one instance per service application, and one instance for each service in the application. Finally, add the instance and the instances to your project installer class. + + When InstallUtil.exe runs, the utility looks for classes in the service assembly with the set to `true`. Add classes to the service assembly by adding them to the collection associated with your project installer. If is `false`, the install utility ignores the project installer. + + For an instance of , properties you can modify include specifying that a service application run under an account other than the logged-on user. You can specify a particular and pair under which the service should run, or you can use to specify that the service run under the computer's System account, a local or network service account, or a user account. + > [!NOTE] -> The computer's System account is not the same as the Administrator account. - - Normally, you do not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. - - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. - - Instantiating a causes the base class constructor, , to be called. - - - -## Examples - The following example creates a project installer called MyProjectInstaller, which inherits from . It is assumed there is a service executable that contains two services, "Hello-World Service 1" and "Hello-World Service 2". Within the constructor for MyProjectInstaller (which would be called by the install utility), objects are created for each service, and a is created for the executable. For the install utility to recognize MyProjectInstaller as a valid installer, the attribute is set to `true`. - - Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses MyProjectInstaller, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each object can be backed out in turn in case of an installation failure. - - Normally, you would not instantiate your project installer class explicitly. You would create it and add the , but the install utility actually calls, and therefore instantiates, the class. - +> The computer's System account is not the same as the Administrator account. + + Normally, you do not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components. + + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + + Instantiating a causes the base class constructor, , to be called. + + + +## Examples + The following example creates a project installer called MyProjectInstaller, which inherits from . It is assumed there is a service executable that contains two services, "Hello-World Service 1" and "Hello-World Service 2". Within the constructor for MyProjectInstaller (which would be called by the install utility), objects are created for each service, and a is created for the executable. For the install utility to recognize MyProjectInstaller as a valid installer, the attribute is set to `true`. + + Optional properties are set on the process installer and the service installers before the installers are added to the collection. When the install utility accesses MyProjectInstaller, the objects added to the collection through a call to will be installed in turn. During the process, the installer maintains state information indicating which objects have been installed, so each object can be backed out in turn in case of an installation failure. + + Normally, you would not instantiate your project installer class explicitly. You would create it and add the , but the install utility actually calls, and therefore instantiates, the class. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_Classic/classic ServiceInstaller Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/ServiceAccount/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceAccount/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/ServiceAccount/Overview/source.vb" id="Snippet1"::: + ]]> @@ -111,15 +111,15 @@ Gets or sets the type of account under which to run this service application. A that defines the type of account under which the system runs this service. The default is . - property is `User`, the and properties are used to define an account under which the service application runs. - - The and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. - - You can also specify that the service run under the local system account, or as a local or network service. See the enumeration for details on types of accounts. - + property is `User`, the and properties are used to define an account under which the service application runs. + + The and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. + + You can also specify that the service run under the local system account, or as a local or network service. See the enumeration for details on types of accounts. + ]]> @@ -152,11 +152,11 @@ The that represents the service process. Implements the base class method with no class-specific behavior. - is `abstract`, so it is implemented here on the derived class. However, there is no class-specific processing in the method's implementation. - + is `abstract`, so it is implemented here on the derived class. However, there is no class-specific processing in the method's implementation. + ]]> @@ -184,11 +184,11 @@ Gets help text displayed for service installation options. Help text that provides a description of the steps for setting the user name and password in order to run the service under a particular account. - @@ -219,17 +219,17 @@ An that contains the context information associated with the installation. Writes service application information to the registry. This method is meant to be used by installation tools, which call the appropriate methods automatically. - within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on all previously installed components. This method passes the installation to the base class method. - - Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components - - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. - - passes to the calling method any exceptions thrown by base class methods or / event handlers. - + within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on all previously installed components. This method passes the installation to the base class method. + + Normally, you will not call the methods on within your code; they are generally called only by the install utility. The install utility automatically calls the and methods during the installation process. It backs out failures, if necessary, by calling (or ) on all previously installed components + + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `stateSaver` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + + passes to the calling method any exceptions thrown by base class methods or / event handlers. + ]]> The is . @@ -265,19 +265,19 @@ Gets or sets the password associated with the user account under which the service application runs. The password associated with the account under which the service should run. The default is an empty string (""). The property is not public, and is never serialized. - and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. - - and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. - - Setting the and allows an account to be associated automatically with the service at install time. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. - - Another option for running a service under a separate account is to use the computer's System account. That account, which is distinct from the Administrator account, requires no password. The System account's privileges may exceed those of the user currently logged in. Running under the System account rather than a user account avoids problems resulting from the user lacking a permission the service requires - - If is any value other than `User`, the specified account (local or network service, or local system) is used, even if the and properties are populated. - + and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. + + and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. + + Setting the and allows an account to be associated automatically with the service at install time. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. + + Another option for running a service under a separate account is to use the computer's System account. That account, which is distinct from the Administrator account, requires no password. The System account's privileges may exceed those of the user currently logged in. Running under the System account rather than a user account avoids problems resulting from the user lacking a permission the service requires + + If is any value other than `User`, the specified account (local or network service, or local system) is used, even if the and properties are populated. + ]]> @@ -309,21 +309,21 @@ An that contains the context information associated with the installation. Rolls back service application information written to the registry by the installation procedure. This method is meant to be used by installation tools, which process the appropriate methods automatically. - within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. - - An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. - - passes to the calling method any exceptions thrown by base class methods or / event handlers. - + within your code; they are generally called only by the install utility. The install utility automatically calls the method during the installation process. It backs out failures, if necessary, by calling on the object that generated the exception. + + An application's install routine maintains information automatically about the components already installed, using the project installer's . This state information, passed into as the `savedState` parameter, is continuously updated as the instance and each instance is installed by the utility. It is usually unnecessary for your code to modify this state information explicitly. + + passes to the calling method any exceptions thrown by base class methods or / event handlers. + ]]> - The is . - - -or- - + The is . + + -or- + The is corrupted or non-existent. @@ -368,19 +368,19 @@ Gets or sets the user account under which the service application will run. The account under which the service should run. The default is an empty string (""). - and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. - - and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. - - Setting the and allows an account to be associated automatically with the service at install time. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. - - Another option for running a service under a separate account is to use the computer's System account. That account, which is distinct from the Administrator account, requires no password. The System account's privileges may exceed those of the user currently logged in. Running under the System account rather than a user account avoids problems resulting from the user lacking a permission the service requires - - If is any value other than `User`, the specified account (local or network service, or local system) is used, even if the and properties are populated. - + and pair allows the service to run under an account other than the system account. This can, for example, allow the service to start automatically at reboot, when no user is logged on. + + and are handled in a secure manner in that they are never serialized or saved to the install state (the project installer's ) or other location with public access. + + Setting the and allows an account to be associated automatically with the service at install time. If you leave either the or empty and set to `User`, you will be prompted for a valid user name and password at installation. + + Another option for running a service under a separate account is to use the computer's System account. That account, which is distinct from the Administrator account, requires no password. The System account's privileges may exceed those of the user currently logged in. Running under the System account rather than a user account avoids problems resulting from the user lacking a permission the service requires + + If is any value other than `User`, the specified account (local or network service, or local system) is used, even if the and properties are populated. + ]]> diff --git a/xml/System.ServiceProcess/ServiceStartMode.xml b/xml/System.ServiceProcess/ServiceStartMode.xml index 220ffa29521..eeb147dbf3a 100644 --- a/xml/System.ServiceProcess/ServiceStartMode.xml +++ b/xml/System.ServiceProcess/ServiceStartMode.xml @@ -40,11 +40,11 @@ Indicates the start mode of the service. - is used by the service installer to indicate whether the new service should be disabled at system startup, whether the system should start the service automatically at system startup, or whether the service should be started manually by a user or application. It is also used by the property to indicate how a particular service starts. - + is used by the service installer to indicate whether the new service should be disabled at system startup, whether the system should start the service automatically at system startup, or whether the service should be started manually by a user or application. It is also used by the property to indicate how a particular service starts. + ]]> diff --git a/xml/System.ServiceProcess/SessionChangeDescription.xml b/xml/System.ServiceProcess/SessionChangeDescription.xml index 462be58791b..853ecd42226 100644 --- a/xml/System.ServiceProcess/SessionChangeDescription.xml +++ b/xml/System.ServiceProcess/SessionChangeDescription.xml @@ -54,14 +54,14 @@ Identifies the reason for a Terminal Services session change. - class in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. - + class in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet9"::: + ]]> @@ -113,11 +113,11 @@ if is equal to the current structure; otherwise, . - or if it is `null`. Equality is determined by comparing the and properties of the specified structure to the and properties of the current structure. The two structures are considered equal if their properties are equal. - + or if it is `null`. Equality is determined by comparing the and properties of the specified structure to the and properties of the current structure. The two structures are considered equal if their properties are equal. + ]]> @@ -157,11 +157,11 @@ if is equal to the current structure; otherwise, . - and properties of the specified structure to the and properties of the current structure. The two structures are considered equal if their properties are equal. - + and properties of the specified structure to the and properties of the current structure. The two structures are considered equal if their properties are equal. + ]]> @@ -192,11 +192,11 @@ Gets a hash code for the current session change description. A hash code for the current session change description. - and properties. The hash code should not be used to compare instances. - + and properties. The hash code should not be used to compare instances. + ]]> @@ -233,11 +233,11 @@ if and are equal; otherwise, . - method. - + method. + The equivalent method for this operator is ]]> @@ -274,11 +274,11 @@ if and are not equal; otherwise, . - method. - + method. + The equivalent method for this operator is ]]> @@ -308,14 +308,14 @@ Gets the reason for the session change. One of the values. - property in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. - + property in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet10"::: + ]]> @@ -345,14 +345,14 @@ Gets the session ID for the associated session. The session ID for the associated session. - property in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. - + property in an implementation of the method in a class derived from . This code example is part of a larger example provided for the class. + :::code language="csharp" source="~/snippets/csharp/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/System.ServiceProcess/SessionChangeDescription/Overview/simpleservice.vb" id="Snippet10"::: + ]]> diff --git a/xml/System.ServiceProcess/TimeoutException.xml b/xml/System.ServiceProcess/TimeoutException.xml index 5bd9f5f4898..fc79434aa93 100644 --- a/xml/System.ServiceProcess/TimeoutException.xml +++ b/xml/System.ServiceProcess/TimeoutException.xml @@ -58,13 +58,13 @@ The exception that is thrown when a specified timeout has expired. - class can specify a message to describe the source of the exception. When a method throws this exception, the message is usually "The timeout provided has expired and the operation has not been completed." - - This class is used, for example, by the class's member. The operation that can throw the exception is a change of the service's property (for example, from `Paused` to `ContinuePending`). - + class can specify a message to describe the source of the exception. When a method throws this exception, the message is usually "The timeout provided has expired and the operation has not been completed." + + This class is used, for example, by the class's member. The operation that can throw the exception is a change of the service's property (for example, from `Paused` to `ContinuePending`). + ]]> diff --git a/xml/System.Speech.AudioFormat/AudioBitsPerSample.xml b/xml/System.Speech.AudioFormat/AudioBitsPerSample.xml index 02d79d634dc..3cfdb8eda9d 100644 --- a/xml/System.Speech.AudioFormat/AudioBitsPerSample.xml +++ b/xml/System.Speech.AudioFormat/AudioBitsPerSample.xml @@ -24,11 +24,11 @@ Enumerates values that describe the bits-per-sample characteristic of an audio format. - property gets a member of that indicates the bits-per-sample of an audio format. - + property gets a member of that indicates the bits-per-sample of an audio format. + ]]> diff --git a/xml/System.Speech.AudioFormat/AudioChannel.xml b/xml/System.Speech.AudioFormat/AudioChannel.xml index cd4b5772892..be4fb85f2a5 100644 --- a/xml/System.Speech.AudioFormat/AudioChannel.xml +++ b/xml/System.Speech.AudioFormat/AudioChannel.xml @@ -24,11 +24,11 @@ Enumerates values that indicate the number of channels in the audio format. - property gets a member of that indicates the number of channels for the audio format. - + property gets a member of that indicates the number of channels for the audio format. + ]]> diff --git a/xml/System.Speech.AudioFormat/EncodingFormat.xml b/xml/System.Speech.AudioFormat/EncodingFormat.xml index 541ec863e6a..57d4379e4cc 100644 --- a/xml/System.Speech.AudioFormat/EncodingFormat.xml +++ b/xml/System.Speech.AudioFormat/EncodingFormat.xml @@ -24,11 +24,11 @@ Enumerates values that describe the encoding format of audio. - property gets a member of that indicates the encoding format of audio. - + property gets a member of that indicates the encoding format of audio. + ]]> diff --git a/xml/System.Speech.AudioFormat/SpeechAudioFormatInfo.xml b/xml/System.Speech.AudioFormat/SpeechAudioFormatInfo.xml index 067a414156e..929dd87c159 100644 --- a/xml/System.Speech.AudioFormat/SpeechAudioFormatInfo.xml +++ b/xml/System.Speech.AudioFormat/SpeechAudioFormatInfo.xml @@ -264,7 +264,7 @@ namespace SampleSynthesis property. Block alignment value is the number of bytes in an atomic unit (that is, a block) of audio for a particular format. For Pulse Code Modulation (PCM) formats, the formula for calculating block alignment is as follows: + Software for playback and recording of audio handles audio data in blocks. The sizes of these blocks are multiples of the value of the property. Block alignment value is the number of bytes in an atomic unit (that is, a block) of audio for a particular format. For Pulse Code Modulation (PCM) formats, the formula for calculating block alignment is as follows: - Block Alignment = Bytes per Sample x Number of Channels diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml index 58081f8b848..b3a2c436efb 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsDocument.xml @@ -92,7 +92,7 @@ ## Examples - The following example creates an object and then creates a public rule named `winnerRule`. It then creates an that consists of the string "A nation that has won the World Cup is:", and adds this item to the property of the rule. The example then creates two more rules (`ruleEurope` and `ruleSAmerica`), each of which is an object that contains three objects. After that, another object is created that contains objects that refer to `ruleEurope` and `ruleSAmerica`. The new object is then added to the property of `winnerRule`. After this, all three rules (`winnerRule`, `ruleEurope`, and `ruleSAmerica`) are added to the property of . Finally, the three rules are compiled into a binary representation of the grammar. + The following example creates an object and then creates a public rule named `winnerRule`. It then creates an that consists of the string "A nation that has won the World Cup is:", and adds this item to the property of the rule. The example then creates two more rules (`ruleEurope` and `ruleSAmerica`), each of which is an object that contains three objects. After that, another object is created that contains objects that refer to `ruleEurope` and `ruleSAmerica`. The new object is then added to the property of `winnerRule`. After this, all three rules (`winnerRule`, `ruleEurope`, and `ruleSAmerica`) are added to the property of . Finally, the three rules are compiled into a binary representation of the grammar. ```csharp public void WorldSoccerWinners () @@ -426,7 +426,7 @@ if (File.Exists(srgsDocumentFile)) property, a speech recognition engine that supports that language-country code must be installed. The speech recognition engines that shipped with Microsoft Windows 7 work with the following language-country codes. + Microsoft Windows and the System.Speech API accept all valid language-country codes. To perform speech recognition using the language specified in the property, a speech recognition engine that supports that language-country code must be installed. The speech recognition engines that shipped with Microsoft Windows 7 work with the following language-country codes. - en-GB. English (United Kingdom) @@ -545,7 +545,7 @@ if (File.Exists(srgsDocumentFile)) property returns a member of the that determines the type of input that the expects. The two possible values are `Voice` for speech input, and `Dtmf` for input of dual-tone multi-frequency (DTMF) tones that are commonly associated with a telephone. + The property returns a member of the that determines the type of input that the expects. The two possible values are `Voice` for speech input, and `Dtmf` for input of dual-tone multi-frequency (DTMF) tones that are commonly associated with a telephone. ]]> @@ -640,7 +640,7 @@ if (File.Exists(srgsDocumentFile)) ## Examples - The following example creates a rule named `winnerRule`, and then creates an object named `document`. The example then calls the method to add the rule to the document. Finally, the example sets the document's property to `winnerRule`, thereby making it the `root rule` for the grammar defined by the object. + The following example creates a rule named `winnerRule`, and then creates an object named `document`. The example then calls the method to add the rule to the document. Finally, the example sets the document's property to `winnerRule`, thereby making it the `root rule` for the grammar defined by the object. ```csharp SrgsRule winnerRule = new SrgsRule("WorldCupWinner"); @@ -681,12 +681,12 @@ document.Root = winnerRule; objects to the by using the method on the property. If you initialize an object and specify an object as the argument, the is automatically added to the for the . + You can add objects to the by using the method on the property. If you initialize an object and specify an object as the argument, the is automatically added to the for the . ## Examples - The following example creates a grammar that recognizes the phrase "A nation that has won the World Cup is" followed by the name of a country/region that has won the World Cup. The example creates an object, and then creates a public rule named `winnerRule`. After adding a string to the rule `winnerRule`, the example creates two more rules (`ruleEurope` and `ruleSAmerica`), each containing a list of countries/regions. Using the method, the example adds all three rules (`winnerRule`, `ruleEurope`, and `ruleSAmerica`) to the property of the . + The following example creates a grammar that recognizes the phrase "A nation that has won the World Cup is" followed by the name of a country/region that has won the World Cup. The example creates an object, and then creates a public rule named `winnerRule`. After adding a string to the rule `winnerRule`, the example creates two more rules (`ruleEurope` and `ruleSAmerica`), each containing a list of countries/regions. Using the method, the example adds all three rules (`winnerRule`, `ruleEurope`, and `ruleSAmerica`) to the property of the . ```csharp public void WorldSoccerWinners () @@ -788,7 +788,7 @@ public void WorldSoccerWinners () object, and then creates a public rule named `winnerRule`. It then creates an that consists of the string "A nation that has won the World Cup is:", and adds this item to the property of the rule. The example then creates two more rules (`ruleEurope` and `ruleSAmerica`), each of which is an object that contains three objects. After that, another object is created that contains objects that refer to `ruleEurope` and `ruleSAmerica`. The new object is then added to the property of `winnerRule`. After this, all three rules (`winnerRule`, `ruleEurope`, and `ruleSAmerica`) are added to the property of the . Finally, the example creates an empty XML file and an instance of . The method uses the instance to write the contents of the to the XML file. + The following example creates an object, and then creates a public rule named `winnerRule`. It then creates an that consists of the string "A nation that has won the World Cup is:", and adds this item to the property of the rule. The example then creates two more rules (`ruleEurope` and `ruleSAmerica`), each of which is an object that contains three objects. After that, another object is created that contains objects that refer to `ruleEurope` and `ruleSAmerica`. The new object is then added to the property of `winnerRule`. After this, all three rules (`winnerRule`, `ruleEurope`, and `ruleSAmerica`) are added to the property of the . Finally, the example creates an empty XML file and an instance of . The method uses the instance to write the contents of the to the XML file. ```csharp public void WorldSoccerWinners () @@ -864,7 +864,7 @@ public void WorldSoccerWinners () property gets a value that is used to resolve relative URIs in a object. Suppose the value for is `http://www.contoso.com/` and the contains a relative rule reference to another document, for example `SrgsRuleRef("ExternalGrammar.grxml")`. This creates the following absolute path to the external document: `http://www.contoso.com/ExternalGrammar.grxml`. + property gets a value that is used to resolve relative URIs in a object. Suppose the value for is `http://www.contoso.com/` and the contains a relative rule reference to another document, for example `SrgsRuleRef("ExternalGrammar.grxml")`. This creates the following absolute path to the external document: `http://www.contoso.com/ExternalGrammar.grxml`. [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsGrammarMode.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsGrammarMode.xml index a6bdd8a7d83..8aa635175bf 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsGrammarMode.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsGrammarMode.xml @@ -24,38 +24,38 @@ Indicates the type of input that the grammar, defined by the , will match. - is determined by its property. The default input mode is Voice, which indicates that the grammar defined by the will match speech input. - - The Dtmf mode indicates that a grammar will match Dual-Tone Multi-Frequency (DTMF) tones instead of speech. There are 16 DTMF tones, 12 of which are commonly found on most telephones. - - When you create a object from an , the object will match the type of input specified by the property, which gets an instance of . - - - -## Examples - -```csharp -string srgsDocumentFile = Path.Combine(Path.GetTempPath(), "srgsDocumentFile.xml"); -SrgsDocument document = null; -GrammarBuilder builder = null; -Grammar grammar = null; - -Choices firstThree = new Choices(new string[] {"1", "2", "3"}); -Choices nextThree = new Choices(new string[] {"4", "5", "6"}); -Choices lastThree = new Choices(new string[] {"7", "8", "9"}); - -Choices keyPadChoices = new Choices(new GrammarBuilder[] {firstThree, nextThree, lastThree, new Choices("0")}); - -builder = new GrammarBuilder(keyPadChoices); -document = new SrgsDocument(builder); - -document.Mode = SrgsGrammarMode.Dtmf; -grammar = new Grammar(document); -``` - + is determined by its property. The default input mode is Voice, which indicates that the grammar defined by the will match speech input. + + The Dtmf mode indicates that a grammar will match Dual-Tone Multi-Frequency (DTMF) tones instead of speech. There are 16 DTMF tones, 12 of which are commonly found on most telephones. + + When you create a object from an , the object will match the type of input specified by the property, which gets an instance of . + + + +## Examples + +```csharp +string srgsDocumentFile = Path.Combine(Path.GetTempPath(), "srgsDocumentFile.xml"); +SrgsDocument document = null; +GrammarBuilder builder = null; +Grammar grammar = null; + +Choices firstThree = new Choices(new string[] {"1", "2", "3"}); +Choices nextThree = new Choices(new string[] {"4", "5", "6"}); +Choices lastThree = new Choices(new string[] {"7", "8", "9"}); + +Choices keyPadChoices = new Choices(new GrammarBuilder[] {firstThree, nextThree, lastThree, new Choices("0")}); + +builder = new GrammarBuilder(keyPadChoices); +document = new SrgsDocument(builder); + +document.Mode = SrgsGrammarMode.Dtmf; +grammar = new Grammar(document); +``` + ]]> diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml index f9fd4059849..ffd59cf0332 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsItem.xml @@ -43,13 +43,13 @@ object can consist of phrases, entities such as objects, logical combinations of phrases and objects, and so on. You can use the property on the class to gain access to the constituents of an object. + An object can consist of phrases, entities such as objects, logical combinations of phrases and objects, and so on. You can use the property on the class to gain access to the constituents of an object. - The order in which objects appear in a given object specifies the order in which a user must speak them. By default, the contents of an must be spoken exactly once. To specify that the contents of an must be spoken repeatedly, use the constructor and set the `repeatCount` parameter. Similarly, to specify a range for the number of times that an can be spoken, create the with one of the constructors that set the property and the property. If the already exists, you can use one of the or the methods to specify repeats. + The order in which objects appear in a given object specifies the order in which a user must speak them. By default, the contents of an must be spoken exactly once. To specify that the contents of an must be spoken repeatedly, use the constructor and set the `repeatCount` parameter. Similarly, to specify a range for the number of times that an can be spoken, create the with one of the constructors that set the property and the property. If the already exists, you can use one of the or the methods to specify repeats. - You can also specify the probability that an item will be repeatedly spoken by setting the value of the property. + You can also specify the probability that an item will be repeatedly spoken by setting the value of the property. - objects within an object comprise a list of alternatives from which the user can speak one. You can use the property to specify the likelihood that a given item in the list will be spoken. + objects within an object comprise a list of alternatives from which the user can speak one. You can use the property to specify the likelihood that a given item in the list will be spoken. The class represents the `item` element that is defined in the World Wide Web Consortium (W3C) [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761). For information about the SRGS `item` element and details about its support by System.Speech, see [item Element](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/ms870124(v=msdn.10)). @@ -314,7 +314,7 @@ method appends an element to the property. + The method appends an element to the property. ]]> diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsNameValueTag.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsNameValueTag.xml index 9ae1d2d4841..1c29dc7b038 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsNameValueTag.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsNameValueTag.xml @@ -36,96 +36,96 @@ Represents an element for associating a semantic value with a phrase in a grammar. - property of this object cannot be script. The contents of can be of the type , , , or . String values must be enclosed in double quotes. - - To add semantics as script, use . - - - -## Examples - The following example creates a grammar for choosing the cities for a flight. The example uses to assign a semantic value to each city, which is the code for the city's airport. - - The example constructs two instances, each of which specifies a semantic key. Both rule references target the same object, named `cities`, but tag the recognition result from the rule reference with a different semantic key. The semantic key identifies a recognized city as the departure city or the arrival city for the flight. The handler for the event uses the keys to retrieve the semantics values created using from the recognition result. - -``` -using System; -using System.Speech.Recognition; -using System.Speech.Recognition.SrgsGrammar; - -namespace SampleRecognition -{ - class Program - { - static void Main(string[] args) - - // Initialize a SpeechRecognitionEngine object. - { - using (SpeechRecognitionEngine recognizer = - new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US"))) - { - - // Build a rule with a list of cities, assign a semantic value to each city. - SrgsItem chi = new SrgsItem("Chicago"); - chi.Add(new SrgsNameValueTag("ORD")); - SrgsItem bos = new SrgsItem("Boston"); - bos.Add(new SrgsNameValueTag("BOS")); - SrgsItem mia = new SrgsItem("Miami"); - mia.Add(new SrgsNameValueTag("MIA")); - SrgsItem dal = new SrgsItem("Dallas"); - dal.Add(new SrgsNameValueTag("DFW")); - - SrgsOneOf cities = new SrgsOneOf(new SrgsItem[] { chi, bos, mia, dal }); - SrgsRule citiesRule = new SrgsRule("flightCities"); - citiesRule.Add(cities); - - // Build the root rule, add rule references to the cities rule. - SrgsRule flightBooker = new SrgsRule("bookFlight"); - flightBooker.Add(new SrgsItem("I want to fly from")); - flightBooker.Add(new SrgsRuleRef(citiesRule, "departureCity")); - flightBooker.Add(new SrgsItem("to")); - flightBooker.Add(new SrgsRuleRef(citiesRule, "arrivalCity")); - - // Build an SrgsDocument object from the flightBooker rule and add the cities rule. - SrgsDocument cityChooser = new SrgsDocument(flightBooker); - cityChooser.Rules.Add(citiesRule); - - // Create a Grammar object from the SrgsDocument and load it to the recognizer. - Grammar departArrive = new Grammar(cityChooser); - departArrive.Name = ("Cities Grammar"); - recognizer.LoadGrammarAsync(departArrive); - - // Configure recognizer input. - recognizer.SetInputToDefaultAudioDevice(); - - // Attach a handler for the SpeechRecognized event. - recognizer.SpeechRecognized += - new EventHandler(recognizer_SpeechRecognized); - - // Start asynchronous recognition. - recognizer.RecognizeAsync(); - Console.WriteLine("Starting asynchronous recognition..."); - - // Keep the console window open. - Console.ReadLine(); - } - } - - // Handle the SpeechRecognized event. - static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine("Speech recognized: " + e.Result.Text); - Console.WriteLine(); - Console.WriteLine("Semantic results:"); - Console.WriteLine(" The departure city is: " + e.Result.Semantics["departureCity"].Value); - Console.WriteLine(" The destination city is: " + e.Result.Semantics["arrivalCity"].Value); - } - } -} -``` - + property of this object cannot be script. The contents of can be of the type , , , or . String values must be enclosed in double quotes. + + To add semantics as script, use . + + + +## Examples + The following example creates a grammar for choosing the cities for a flight. The example uses to assign a semantic value to each city, which is the code for the city's airport. + + The example constructs two instances, each of which specifies a semantic key. Both rule references target the same object, named `cities`, but tag the recognition result from the rule reference with a different semantic key. The semantic key identifies a recognized city as the departure city or the arrival city for the flight. The handler for the event uses the keys to retrieve the semantics values created using from the recognition result. + +``` +using System; +using System.Speech.Recognition; +using System.Speech.Recognition.SrgsGrammar; + +namespace SampleRecognition +{ + class Program + { + static void Main(string[] args) + + // Initialize a SpeechRecognitionEngine object. + { + using (SpeechRecognitionEngine recognizer = + new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US"))) + { + + // Build a rule with a list of cities, assign a semantic value to each city. + SrgsItem chi = new SrgsItem("Chicago"); + chi.Add(new SrgsNameValueTag("ORD")); + SrgsItem bos = new SrgsItem("Boston"); + bos.Add(new SrgsNameValueTag("BOS")); + SrgsItem mia = new SrgsItem("Miami"); + mia.Add(new SrgsNameValueTag("MIA")); + SrgsItem dal = new SrgsItem("Dallas"); + dal.Add(new SrgsNameValueTag("DFW")); + + SrgsOneOf cities = new SrgsOneOf(new SrgsItem[] { chi, bos, mia, dal }); + SrgsRule citiesRule = new SrgsRule("flightCities"); + citiesRule.Add(cities); + + // Build the root rule, add rule references to the cities rule. + SrgsRule flightBooker = new SrgsRule("bookFlight"); + flightBooker.Add(new SrgsItem("I want to fly from")); + flightBooker.Add(new SrgsRuleRef(citiesRule, "departureCity")); + flightBooker.Add(new SrgsItem("to")); + flightBooker.Add(new SrgsRuleRef(citiesRule, "arrivalCity")); + + // Build an SrgsDocument object from the flightBooker rule and add the cities rule. + SrgsDocument cityChooser = new SrgsDocument(flightBooker); + cityChooser.Rules.Add(citiesRule); + + // Create a Grammar object from the SrgsDocument and load it to the recognizer. + Grammar departArrive = new Grammar(cityChooser); + departArrive.Name = ("Cities Grammar"); + recognizer.LoadGrammarAsync(departArrive); + + // Configure recognizer input. + recognizer.SetInputToDefaultAudioDevice(); + + // Attach a handler for the SpeechRecognized event. + recognizer.SpeechRecognized += + new EventHandler(recognizer_SpeechRecognized); + + // Start asynchronous recognition. + recognizer.RecognizeAsync(); + Console.WriteLine("Starting asynchronous recognition..."); + + // Keep the console window open. + Console.ReadLine(); + } + } + + // Handle the SpeechRecognized event. + static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine("Speech recognized: " + e.Result.Text); + Console.WriteLine(); + Console.WriteLine("Semantic results:"); + Console.WriteLine(" The departure city is: " + e.Result.Semantics["departureCity"].Value); + Console.WriteLine(" The destination city is: " + e.Result.Semantics["arrivalCity"].Value); + } + } +} +``` + ]]> @@ -186,89 +186,89 @@ namespace SampleRecognition The value used to set the property. Initializes a new instance of the class, specifying a value for the instance. - to assign a semantic value to each city, which is the code for the city's airport. - - The example constructs two instances, each of which specifies a semantic key. Both rule references target the same object, named `cities`, but tag the recognition result from the rule reference with a different semantic key. The semantic key identifies a recognized city as the departure city or the arrival city for the flight. The handler for the event uses the keys to retrieve the semantics values created using from the recognition result. - -``` -using System; -using System.Speech.Recognition; -using System.Speech.Recognition.SrgsGrammar; - -namespace SampleRecognition -{ - class Program - { - static void Main(string[] args) - - // Initialize a SpeechRecognitionEngine object. - { - using (SpeechRecognitionEngine recognizer = - new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US"))) - { - - // Build a rule with a list of cities, assign a semantic value to each city. - SrgsItem chi = new SrgsItem("Chicago"); - chi.Add(new SrgsNameValueTag("ORD")); - SrgsItem bos = new SrgsItem("Boston"); - bos.Add(new SrgsNameValueTag("BOS")); - SrgsItem mia = new SrgsItem("Miami"); - mia.Add(new SrgsNameValueTag("MIA")); - SrgsItem dal = new SrgsItem("Dallas"); - dal.Add(new SrgsNameValueTag("DFW")); - - SrgsOneOf cities = new SrgsOneOf(new SrgsItem[] { chi, bos, mia, dal }); - SrgsRule citiesRule = new SrgsRule("flightCities"); - citiesRule.Add(cities); - - // Build the root rule, add rule references to the cities rule. - SrgsRule flightBooker = new SrgsRule("bookFlight"); - flightBooker.Add(new SrgsItem("I want to fly from")); - flightBooker.Add(new SrgsRuleRef(citiesRule, "departureCity")); - flightBooker.Add(new SrgsItem("to")); - flightBooker.Add(new SrgsRuleRef(citiesRule, "arrivalCity")); - - // Build an SrgsDocument object from the flightBooker rule and add the cities rule. - SrgsDocument cityChooser = new SrgsDocument(flightBooker); - cityChooser.Rules.Add(citiesRule); - - // Create a Grammar object from the SrgsDocument and load it to the recognizer. - Grammar departArrive = new Grammar(cityChooser); - departArrive.Name = ("Cities Grammar"); - recognizer.LoadGrammarAsync(departArrive); - - // Configure recognizer input. - recognizer.SetInputToDefaultAudioDevice(); - - // Attach a handler for the SpeechRecognized event. - recognizer.SpeechRecognized += - new EventHandler(recognizer_SpeechRecognized); - - // Start asynchronous recognition. - recognizer.RecognizeAsync(); - Console.WriteLine("Starting asynchronous recognition..."); - - // Keep the console window open. - Console.ReadLine(); - } - } - - // Handle the SpeechRecognized event. - static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine("Speech recognized: " + e.Result.Text); - Console.WriteLine(); - Console.WriteLine("Semantic results:"); - Console.WriteLine(" The departure city is: " + e.Result.Semantics["departureCity"].Value); - Console.WriteLine(" The destination city is: " + e.Result.Semantics["arrivalCity"].Value); - } - } -} -``` - + to assign a semantic value to each city, which is the code for the city's airport. + + The example constructs two instances, each of which specifies a semantic key. Both rule references target the same object, named `cities`, but tag the recognition result from the rule reference with a different semantic key. The semantic key identifies a recognized city as the departure city or the arrival city for the flight. The handler for the event uses the keys to retrieve the semantics values created using from the recognition result. + +``` +using System; +using System.Speech.Recognition; +using System.Speech.Recognition.SrgsGrammar; + +namespace SampleRecognition +{ + class Program + { + static void Main(string[] args) + + // Initialize a SpeechRecognitionEngine object. + { + using (SpeechRecognitionEngine recognizer = + new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US"))) + { + + // Build a rule with a list of cities, assign a semantic value to each city. + SrgsItem chi = new SrgsItem("Chicago"); + chi.Add(new SrgsNameValueTag("ORD")); + SrgsItem bos = new SrgsItem("Boston"); + bos.Add(new SrgsNameValueTag("BOS")); + SrgsItem mia = new SrgsItem("Miami"); + mia.Add(new SrgsNameValueTag("MIA")); + SrgsItem dal = new SrgsItem("Dallas"); + dal.Add(new SrgsNameValueTag("DFW")); + + SrgsOneOf cities = new SrgsOneOf(new SrgsItem[] { chi, bos, mia, dal }); + SrgsRule citiesRule = new SrgsRule("flightCities"); + citiesRule.Add(cities); + + // Build the root rule, add rule references to the cities rule. + SrgsRule flightBooker = new SrgsRule("bookFlight"); + flightBooker.Add(new SrgsItem("I want to fly from")); + flightBooker.Add(new SrgsRuleRef(citiesRule, "departureCity")); + flightBooker.Add(new SrgsItem("to")); + flightBooker.Add(new SrgsRuleRef(citiesRule, "arrivalCity")); + + // Build an SrgsDocument object from the flightBooker rule and add the cities rule. + SrgsDocument cityChooser = new SrgsDocument(flightBooker); + cityChooser.Rules.Add(citiesRule); + + // Create a Grammar object from the SrgsDocument and load it to the recognizer. + Grammar departArrive = new Grammar(cityChooser); + departArrive.Name = ("Cities Grammar"); + recognizer.LoadGrammarAsync(departArrive); + + // Configure recognizer input. + recognizer.SetInputToDefaultAudioDevice(); + + // Attach a handler for the SpeechRecognized event. + recognizer.SpeechRecognized += + new EventHandler(recognizer_SpeechRecognized); + + // Start asynchronous recognition. + recognizer.RecognizeAsync(); + Console.WriteLine("Starting asynchronous recognition..."); + + // Keep the console window open. + Console.ReadLine(); + } + } + + // Handle the SpeechRecognized event. + static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine("Speech recognized: " + e.Result.Text); + Console.WriteLine(); + Console.WriteLine("Semantic results:"); + Console.WriteLine(" The departure city is: " + e.Result.Semantics["departureCity"].Value); + Console.WriteLine(" The destination city is: " + e.Result.Semantics["arrivalCity"].Value); + } + } +} +``` + ]]> @@ -299,8 +299,8 @@ namespace SampleRecognition Initializes a new instance of the class, specifying a name and a value for the instance. To be added. - is . - + is . + is . is an empty string. @@ -364,19 +364,19 @@ namespace SampleRecognition Gets or sets the value contained in the instance. The value contained in the instance. - property are: - -- - -- - -- - -- - + property are: + +- + +- + +- + +- + ]]> An attempt is made to set to . diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsOneOf.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsOneOf.xml index 2073177e97c..1fabcd5c444 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsOneOf.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsOneOf.xml @@ -43,7 +43,7 @@ object contains a list of alternative words or phrases, any one of which may be recognized when spoken. You can build lists of alternatives from arrays of objects or arrays of objects. Use the property to access the alternative items in the list. + A object contains a list of alternative words or phrases, any one of which may be recognized when spoken. You can build lists of alternatives from arrays of objects or arrays of objects. Use the property to access the alternative items in the list. The class represents the `one-of` element from the World Wide Web Consortium (W3C) [Speech Recognition Grammar Specification (SRGS) Version 1.0](https://go.microsoft.com/fwlink/?LinkId=201761). For information about the SRGS `one-of` element and details about its support by System.Speech, see [one-of Element](https://msdn.microsoft.com/library/643cee6b-5082-46ea-9fc1-9f3646a95801). diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml index e05c768aa26..b95ae633d63 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRule.xml @@ -47,9 +47,9 @@ The words and phrases specified by objects in grammars defined by instances limit the spoken input that the recognizer must be able to identify. - An object specifies the sequence in which words and phrases must be spoken by ordering the objects that contain them. Words and phrases within a rule are represented by objects such as , , , and elements. Use the property to access the collection of child objects that an object contains. + An object specifies the sequence in which words and phrases must be spoken by ordering the objects that contain them. Words and phrases within a rule are represented by objects such as , , , and elements. Use the property to access the collection of child objects that an object contains. - You can determine whether an can be specified in a rule reference from a rule in an external grammar by setting its property. + You can determine whether an can be specified in a rule reference from a rule in an external grammar by setting its property. It is not legal to define an that is empty or that contains only white space. @@ -93,7 +93,7 @@ constructor initializes the property. The identifier must be unique within a given grammar. + The constructor initializes the property. The identifier must be unique within a given grammar. The constructor throws a in the following circumstances: @@ -184,7 +184,7 @@ public void WorldSoccerWinners () constructor initializes the property. The identifier must be unique within a given grammar. + The constructor initializes the property. The identifier must be unique within a given grammar. The constructor throws a in the following circumstances: diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRuleRef.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRuleRef.xml index fb927831613..e791d300a34 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsRuleRef.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsRuleRef.xml @@ -47,7 +47,7 @@ You can use one of the constructors of the class to reference an object or a `rule` element if the following is true: -- The object is in the containing grammar and the value of its property is or . +- The object is in the containing grammar and the value of its property is or . - The `rule` element is in an external grammar and the value of its `scope` attribute is `public`. diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsSemanticInterpretationTag.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsSemanticInterpretationTag.xml index cdde73443c2..ae1661f6918 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsSemanticInterpretationTag.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsSemanticInterpretationTag.xml @@ -198,7 +198,7 @@ version="1.0" xmlns="http://www.w3.org/2001/06/grammar"> property contains an empty string. + This constructor creates a semantic interpretation tag whose property contains an empty string. ]]> @@ -228,7 +228,7 @@ version="1.0" xmlns="http://www.w3.org/2001/06/grammar"> property is set to the value in `script`. + This constructor creates a semantic interpretation tag whose property is set to the value in `script`. ]]> diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsText.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsText.xml index e80a4dd165c..0ca9eaf9823 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsText.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsText.xml @@ -36,79 +36,79 @@ Represents the textual content of grammar elements defined by the World Wide Web Consortium (W3C) Speech Recognition Grammar Specification (SRGS) Version 1.0. - class represents the text found within a set of SRGS element tags. When an object is constructed with a parameter, a object is created with its property initialized to the value of that parameter. The object is then added to the collection on the object. - - - -## Examples - The following C# code example demonstrates how to use the class to modify the textual contents of objects. The example changes the initial text values of the objects (`Large`, `Larger`, and `Largest`) to `Small`, `Medium`, and `Large`, respectively. - -```csharp - -// Create SrgsItem objects and specify their text. -SrgsItem smallItem = new SrgsItem("Large"); -SrgsItem mediumItem = new SrgsItem("Larger"); -SrgsItem largeItem = new SrgsItem("Largest"); - -SrgsText textOfItem = null; - -// Change the text of smallItem. -if (smallItem.Elements[0] is SrgsText) -{ - textOfItem = smallItem.Elements[0] as SrgsText; - textOfItem.Text = "Small"; -} - -// Change the text of mediumItem. -if (mediumItem.Elements[0] is SrgsText) -{ - textOfItem = mediumItem.Elements[0] as SrgsText; - textOfItem.Text = "Medium"; -} - -// Change the text of largeItem. -if (largeItem.Elements[0] is SrgsText) -{ - textOfItem = largeItem.Elements[0] as SrgsText; - textOfItem.Text = "Large"; -} - -// Create an SrgsOneOf object and add smallItem, mediumItem, -// and largeItem as alternatives. -SrgsOneOf itemSize = new SrgsOneOf(new SrgsItem[] - { smallItem, mediumItem, largeItem }); - -// Create a new SrgsRule from the SrgsOneOf object, and specify its identifier. -SrgsRule size = new SrgsRule("Sizes", itemSize); - -// Create an SrgsDocument object. -// Add the SrgsRule object to the collection of rules and make it the root rule. -SrgsDocument document = new SrgsDocument(); -document.Rules.Add(size); -document.Root = size; - -// Write the SrgsDocument to an XML grammar file. -string srgsDocumentFile = Path.Combine(Path.GetTempPath(), "srgsDocumentFile.xml"); -XmlWriter writer = XmlWriter.Create(srgsDocumentFile); -document.WriteSrgs(writer); -writer.Close(); -``` - - The following shows how the modified text of the objects would appear as `item` elements in the output XML grammar file. - -```xml - - - Small - Medium - Large - - -``` - + class represents the text found within a set of SRGS element tags. When an object is constructed with a parameter, a object is created with its property initialized to the value of that parameter. The object is then added to the collection on the object. + + + +## Examples + The following C# code example demonstrates how to use the class to modify the textual contents of objects. The example changes the initial text values of the objects (`Large`, `Larger`, and `Largest`) to `Small`, `Medium`, and `Large`, respectively. + +```csharp + +// Create SrgsItem objects and specify their text. +SrgsItem smallItem = new SrgsItem("Large"); +SrgsItem mediumItem = new SrgsItem("Larger"); +SrgsItem largeItem = new SrgsItem("Largest"); + +SrgsText textOfItem = null; + +// Change the text of smallItem. +if (smallItem.Elements[0] is SrgsText) +{ + textOfItem = smallItem.Elements[0] as SrgsText; + textOfItem.Text = "Small"; +} + +// Change the text of mediumItem. +if (mediumItem.Elements[0] is SrgsText) +{ + textOfItem = mediumItem.Elements[0] as SrgsText; + textOfItem.Text = "Medium"; +} + +// Change the text of largeItem. +if (largeItem.Elements[0] is SrgsText) +{ + textOfItem = largeItem.Elements[0] as SrgsText; + textOfItem.Text = "Large"; +} + +// Create an SrgsOneOf object and add smallItem, mediumItem, +// and largeItem as alternatives. +SrgsOneOf itemSize = new SrgsOneOf(new SrgsItem[] + { smallItem, mediumItem, largeItem }); + +// Create a new SrgsRule from the SrgsOneOf object, and specify its identifier. +SrgsRule size = new SrgsRule("Sizes", itemSize); + +// Create an SrgsDocument object. +// Add the SrgsRule object to the collection of rules and make it the root rule. +SrgsDocument document = new SrgsDocument(); +document.Rules.Add(size); +document.Root = size; + +// Write the SrgsDocument to an XML grammar file. +string srgsDocumentFile = Path.Combine(Path.GetTempPath(), "srgsDocumentFile.xml"); +XmlWriter writer = XmlWriter.Create(srgsDocumentFile); +document.WriteSrgs(writer); +writer.Close(); +``` + + The following shows how the modified text of the objects would appear as `item` elements in the output XML grammar file. + +```xml + + + Small + Medium + Large + + +``` + ]]> @@ -140,11 +140,11 @@ writer.Close(); Initializes a new instance of the class. - class. - + class. + ]]> diff --git a/xml/System.Speech.Recognition.SrgsGrammar/SrgsToken.xml b/xml/System.Speech.Recognition.SrgsGrammar/SrgsToken.xml index 4f34e6b3554..2dcfe18ed43 100644 --- a/xml/System.Speech.Recognition.SrgsGrammar/SrgsToken.xml +++ b/xml/System.Speech.Recognition.SrgsGrammar/SrgsToken.xml @@ -73,7 +73,7 @@ object whose property is set initially to the value of the `text` parameter. + Creates a object whose property is set initially to the value of the `text` parameter. ]]> @@ -157,12 +157,12 @@ If the phones are not space-delimited or the specified string contains an unrecognized phone, the recognition engine does not recognize the specified pronunciation as a valid pronunciation of the word contained by . - Pronunciations specified in take precedence over pronunciations specified in lexicons associated with a grammar or a recognition engine. Also, the pronunciation in the property applies only to the single occurrence of the word or phrase contained by . + Pronunciations specified in take precedence over pronunciations specified in lexicons associated with a grammar or a recognition engine. Also, the pronunciation in the property applies only to the single occurrence of the word or phrase contained by . ## Examples - The grammar in the following example contains slang words and also has an uncommon word: "whatchamacallit". Adding a custom, inline pronunciation using the property of the class can improve the accuracy of recognition for the word "whatchamacallit" as well as for the entire phrase that contains it. The example uses phones from the Microsoft Universal Phone Set (UPS) to define the custom pronunciations. + The grammar in the following example contains slang words and also has an uncommon word: "whatchamacallit". Adding a custom, inline pronunciation using the property of the class can improve the accuracy of recognition for the word "whatchamacallit" as well as for the entire phrase that contains it. The example uses phones from the Microsoft Universal Phone Set (UPS) to define the custom pronunciations. ```csharp using System; @@ -280,7 +280,7 @@ namespace SampleRecognition ## Remarks Although they typically represent the same value, the form may be different than the form for a word or phrase in a . For example, the form may be an acronym, such as "USA", while the text that will be spoken, and to which the applies, is "United States of America". - The default value for the property is an empty string - "". + The default value for the property is an empty string - "". ]]> diff --git a/xml/System.Speech.Recognition/AudioLevelUpdatedEventArgs.xml b/xml/System.Speech.Recognition/AudioLevelUpdatedEventArgs.xml index 3c769340b20..51069ef2c86 100644 --- a/xml/System.Speech.Recognition/AudioLevelUpdatedEventArgs.xml +++ b/xml/System.Speech.Recognition/AudioLevelUpdatedEventArgs.xml @@ -25,45 +25,45 @@ Provides data for the event of the or the class. - and events pass an instance of to the handler for the associated event. - - The property gets the new level of audio input when the or event is raised. - - The `AudioLevel` property of the and classes provides the current level of the audio input to the speech recognition engine. - - - -## Examples - The following example adds an event handler to a object. The handler outputs the new audio level to the console. - - derives from . - -```csharp - -private SpeechRecognitionEngine sre; - -// Initialize the SpeechRecognitionEngine object. -private void Initialize() -{ - sre = new SpeechRecognitionEngine(); - - // Add an event handler for the AudioLevelUpdated event. - sre.AudioLevelUpdated += new EventHandler(sre_AudioLevelUpdated); - - // Add other initialization code here. -} - -// Write the audio level to the console when the AudioLevelUpdated event is raised. -void sre_AudioLevelUpdated(object sender, AudioLevelUpdatedEventArgs e) -{ - Console.WriteLine("The audio level is now: {0}.", e.AudioLevel); -} - -``` - + and events pass an instance of to the handler for the associated event. + + The property gets the new level of audio input when the or event is raised. + + The `AudioLevel` property of the and classes provides the current level of the audio input to the speech recognition engine. + + + +## Examples + The following example adds an event handler to a object. The handler outputs the new audio level to the console. + + derives from . + +```csharp + +private SpeechRecognitionEngine sre; + +// Initialize the SpeechRecognitionEngine object. +private void Initialize() +{ + sre = new SpeechRecognitionEngine(); + + // Add an event handler for the AudioLevelUpdated event. + sre.AudioLevelUpdated += new EventHandler(sre_AudioLevelUpdated); + + // Add other initialization code here. +} + +// Write the audio level to the console when the AudioLevelUpdated event is raised. +void sre_AudioLevelUpdated(object sender, AudioLevelUpdatedEventArgs e) +{ + Console.WriteLine("The audio level is now: {0}.", e.AudioLevel); +} + +``` + ]]> diff --git a/xml/System.Speech.Recognition/AudioSignalProblemOccurredEventArgs.xml b/xml/System.Speech.Recognition/AudioSignalProblemOccurredEventArgs.xml index 9ef919085a8..32b991ebe42 100644 --- a/xml/System.Speech.Recognition/AudioSignalProblemOccurredEventArgs.xml +++ b/xml/System.Speech.Recognition/AudioSignalProblemOccurredEventArgs.xml @@ -25,62 +25,62 @@ Provides data for the AudioSignalProblemOccurred event of a or a . - is created when the or object raises an `AudioSignalProblemOccurred` event. To obtain information related to an `AudioSignalProblemOccurred` event, access the following properties in the handler for the event: - -- - -- - -- - -- - - The property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position within its audio input. These positions can be different. For more information, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). - - The property indicates which problem occurred. - - derives from . - - - -## Examples - The following example defines an event handler that gathers information about an event. - -```csharp - -private SpeechRecognitionEngine sre; - -// Initialize the speech recognition engine. -private void Initialize() -{ - sre = new SpeechRecognitionEngine(); - - // Add a handler for the AudioSignalProblemOccurred event. - sre.AudioSignalProblemOccurred += new EventHandler(sre_AudioSignalProblemOccurred); -} - -// Gather information when the AudioSignalProblemOccurred event is raised. -void sre_AudioSignalProblemOccurred(object sender, AudioSignalProblemOccurredEventArgs e) -{ - StringBuilder details = new StringBuilder(); - - details.AppendLine("Audio signal problem information:"); - details.AppendFormat( - " Audio level: {0}" + Environment.NewLine + - " Audio position: {1}" + Environment.NewLine + - " Audio signal problem: {2}" + Environment.NewLine + - " Recognition engine audio position: {3}" + Environment.NewLine, - e.AudioLevel, e.AudioPosition, e.AudioSignalProblem, - e.RecognizerAudioPosition); - - // Insert additional event handler code here. -} - -``` - + is created when the or object raises an `AudioSignalProblemOccurred` event. To obtain information related to an `AudioSignalProblemOccurred` event, access the following properties in the handler for the event: + +- + +- + +- + +- + + The property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position within its audio input. These positions can be different. For more information, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). + + The property indicates which problem occurred. + + derives from . + + + +## Examples + The following example defines an event handler that gathers information about an event. + +```csharp + +private SpeechRecognitionEngine sre; + +// Initialize the speech recognition engine. +private void Initialize() +{ + sre = new SpeechRecognitionEngine(); + + // Add a handler for the AudioSignalProblemOccurred event. + sre.AudioSignalProblemOccurred += new EventHandler(sre_AudioSignalProblemOccurred); +} + +// Gather information when the AudioSignalProblemOccurred event is raised. +void sre_AudioSignalProblemOccurred(object sender, AudioSignalProblemOccurredEventArgs e) +{ + StringBuilder details = new StringBuilder(); + + details.AppendLine("Audio signal problem information:"); + details.AppendFormat( + " Audio level: {0}" + Environment.NewLine + + " Audio position: {1}" + Environment.NewLine + + " Audio signal problem: {2}" + Environment.NewLine + + " Recognition engine audio position: {3}" + Environment.NewLine, + e.AudioLevel, e.AudioPosition, e.AudioSignalProblem, + e.RecognizerAudioPosition); + + // Insert additional event handler code here. +} + +``` + ]]> @@ -144,11 +144,11 @@ void sre_AudioSignalProblemOccurred(object sender, AudioSignalProblemOccurredEve Gets the position in the input device's audio stream that indicates where the problem occurred. The position in the input device's audio stream when the AudioSignalProblemOccurred event was raised. - property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position within its audio input. These positions can be different. For more information, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). - + property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position within its audio input. These positions can be different. For more information, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). + ]]> @@ -209,11 +209,11 @@ void sre_AudioSignalProblemOccurred(object sender, AudioSignalProblemOccurredEve Gets the position in the audio input that the recognizer has received that indicates where the problem occurred. The position in the audio input that the recognizer has received when the AudioSignalProblemOccurred event was raised. - property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position within its audio input. These positions can be different. For more information, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). - + property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position within its audio input. These positions can be different. For more information, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). + ]]> diff --git a/xml/System.Speech.Recognition/AudioStateChangedEventArgs.xml b/xml/System.Speech.Recognition/AudioStateChangedEventArgs.xml index 7181f435247..e0456c2227b 100644 --- a/xml/System.Speech.Recognition/AudioStateChangedEventArgs.xml +++ b/xml/System.Speech.Recognition/AudioStateChangedEventArgs.xml @@ -25,43 +25,43 @@ Provides data for the event of the or the class. - property gets a new instance of the enumeration when a or a event is raised. - - You can obtain the current state of the audio input using the `AudioState` property of the or classes. - - - -## Examples - The following example demonstrates an event handler for handling the changing audio state of a speech recognition engine. - -```csharp - -private SpeechRecognitionEngine sre; - -// Initialize the SpeechRecognitionEngine object. -private void Initialize() -{ - sre = new SpeechRecognitionEngine(); - - // Add a handler for the AudioStateChanged event. - sre.AudioStateChanged += new EventHandler(sre_AudioStateChanged); - - // Add other initialization code here. -} - -// Handle the AudioStateChanged event. -void sre_AudioStateChanged(object sender, AudioStateChangedEventArgs e) -{ - AudioState newState = e.AudioState; - - // Handle event here. -} - -``` - + property gets a new instance of the enumeration when a or a event is raised. + + You can obtain the current state of the audio input using the `AudioState` property of the or classes. + + + +## Examples + The following example demonstrates an event handler for handling the changing audio state of a speech recognition engine. + +```csharp + +private SpeechRecognitionEngine sre; + +// Initialize the SpeechRecognitionEngine object. +private void Initialize() +{ + sre = new SpeechRecognitionEngine(); + + // Add a handler for the AudioStateChanged event. + sre.AudioStateChanged += new EventHandler(sre_AudioStateChanged); + + // Add other initialization code here. +} + +// Handle the AudioStateChanged event. +void sre_AudioStateChanged(object sender, AudioStateChangedEventArgs e) +{ + AudioState newState = e.AudioState; + + // Handle event here. +} + +``` + ]]> @@ -98,11 +98,11 @@ void sre_AudioStateChanged(object sender, AudioStateChangedEventArgs e) Gets the new state of audio input to the recognizer. The state of audio input after a or a event is raised. - property contains one of three values from the enumeration. - + property contains one of three values from the enumeration. + ]]> diff --git a/xml/System.Speech.Recognition/DictationGrammar.xml b/xml/System.Speech.Recognition/DictationGrammar.xml index 52ec5dd3fb2..eb2c3f7b0f7 100644 --- a/xml/System.Speech.Recognition/DictationGrammar.xml +++ b/xml/System.Speech.Recognition/DictationGrammar.xml @@ -25,57 +25,57 @@ Represents a speech recognition grammar used for free text dictation. - objects. For information about selecting a dictation grammar, see the constructor. - - By default, the language model is context free. It does not make use of specific words or word order to identify and interpret audio input. To add context to the dictation grammar, use the method. - + objects. For information about selecting a dictation grammar, see the constructor. + + By default, the language model is context free. It does not make use of specific words or word order to identify and interpret audio input. To add context to the dictation grammar, use the method. + > [!NOTE] -> objects do not support the property. throws a if is set. - - - -## Examples - The following example creates three dictation grammars, adds them to a new object, and returns the new object. The first grammar is the default dictation grammar. The second grammar is the spelling dictation grammar. The third grammar is the default dictation grammar that includes a context phrase. The method is used to associate the context phrase with the dictation grammar after it is loaded to the object. - -```csharp - -private SpeechRecognitionEngine LoadDictationGrammars() -{ - - // Create a default dictation grammar. - DictationGrammar defaultDictationGrammar = new DictationGrammar(); - defaultDictationGrammar.Name = "default dictation"; - defaultDictationGrammar.Enabled = true; - - // Create the spelling dictation grammar. - DictationGrammar spellingDictationGrammar = - new DictationGrammar("grammar:dictation#spelling"); - spellingDictationGrammar.Name = "spelling dictation"; - spellingDictationGrammar.Enabled = true; - - // Create the question dictation grammar. - DictationGrammar customDictationGrammar = - new DictationGrammar("grammar:dictation"); - customDictationGrammar.Name = "question dictation"; - customDictationGrammar.Enabled = true; - - // Create a SpeechRecognitionEngine object and add the grammars to it. - SpeechRecognitionEngine recoEngine = new SpeechRecognitionEngine(); - recoEngine.LoadGrammar(defaultDictationGrammar); - recoEngine.LoadGrammar(spellingDictationGrammar); - recoEngine.LoadGrammar(customDictationGrammar); - - // Add a context to customDictationGrammar. - customDictationGrammar.SetDictationContext("How do you", null); - - return recoEngine; -} - -``` - +> objects do not support the property. throws a if is set. + + + +## Examples + The following example creates three dictation grammars, adds them to a new object, and returns the new object. The first grammar is the default dictation grammar. The second grammar is the spelling dictation grammar. The third grammar is the default dictation grammar that includes a context phrase. The method is used to associate the context phrase with the dictation grammar after it is loaded to the object. + +```csharp + +private SpeechRecognitionEngine LoadDictationGrammars() +{ + + // Create a default dictation grammar. + DictationGrammar defaultDictationGrammar = new DictationGrammar(); + defaultDictationGrammar.Name = "default dictation"; + defaultDictationGrammar.Enabled = true; + + // Create the spelling dictation grammar. + DictationGrammar spellingDictationGrammar = + new DictationGrammar("grammar:dictation#spelling"); + spellingDictationGrammar.Name = "spelling dictation"; + spellingDictationGrammar.Enabled = true; + + // Create the question dictation grammar. + DictationGrammar customDictationGrammar = + new DictationGrammar("grammar:dictation"); + customDictationGrammar.Name = "question dictation"; + customDictationGrammar.Enabled = true; + + // Create a SpeechRecognitionEngine object and add the grammars to it. + SpeechRecognitionEngine recoEngine = new SpeechRecognitionEngine(); + recoEngine.LoadGrammar(defaultDictationGrammar); + recoEngine.LoadGrammar(spellingDictationGrammar); + recoEngine.LoadGrammar(customDictationGrammar); + + // Add a context to customDictationGrammar. + customDictationGrammar.SetDictationContext("How do you", null); + + return recoEngine; +} + +``` + ]]> @@ -107,11 +107,11 @@ private SpeechRecognitionEngine LoadDictationGrammars() Initializes a new instance of the class for the default dictation grammar provided by Windows Desktop Speech Technology. - @@ -137,11 +137,11 @@ private SpeechRecognitionEngine LoadDictationGrammars() An XML-compliant Universal Resource Identifier (URI) that specifies the dictation grammar, either grammar:dictation or grammar:dictation#spelling. Initializes a new instance of the class with a specific dictation grammar. - @@ -172,23 +172,23 @@ private SpeechRecognitionEngine LoadDictationGrammars() Text that indicates the end of a dictation context. Adds a context to a dictation grammar that has been loaded by a or a object. - [!NOTE] -> A dictation grammar must be loaded by a or object before you can use to add a context. - - The following table describes how the recognition engine uses the two parameters to determine when to use the dictation grammar. - -|`precedingText`|`subsequentText`|Description| -|---------------------|----------------------|-----------------| -|not `null`|not `null`|The recognition engine uses the terms to bracket possible candidate phrases.| -|`null`|not `null`|The recognition engine uses the `subsequentText` to finish dictation.| -|not `null`|`null`|The recognition engine uses the `precedingText` to start dictation.| -|`null`|`null`|The recognition engine does not use a context when using the dictation grammar.| - +> A dictation grammar must be loaded by a or object before you can use to add a context. + + The following table describes how the recognition engine uses the two parameters to determine when to use the dictation grammar. + +|`precedingText`|`subsequentText`|Description| +|---------------------|----------------------|-----------------| +|not `null`|not `null`|The recognition engine uses the terms to bracket possible candidate phrases.| +|`null`|not `null`|The recognition engine uses the `subsequentText` to finish dictation.| +|not `null`|`null`|The recognition engine uses the `precedingText` to start dictation.| +|`null`|`null`|The recognition engine does not use a context when using the dictation grammar.| + ]]> diff --git a/xml/System.Speech.Recognition/DisplayAttributes.xml b/xml/System.Speech.Recognition/DisplayAttributes.xml index 51b6028940d..4253068d8bb 100644 --- a/xml/System.Speech.Recognition/DisplayAttributes.xml +++ b/xml/System.Speech.Recognition/DisplayAttributes.xml @@ -30,71 +30,71 @@ Lists the options that the object can use to specify white space for the display of a word or punctuation mark. - or objects. Each object corresponds to a single word or punctuation mark. The `DisplayAttributes` property of a or uses a member of the enumeration to describe how print spacing is handled around a given word or punctuation mark. - - Two or more members of the `DisplayAttributes` enumeration may be combined by a bit-wise `OR` to specify how a particular word should be displayed. - + or objects. Each object corresponds to a single word or punctuation mark. The `DisplayAttributes` property of a or uses a member of the enumeration to describe how print spacing is handled around a given word or punctuation mark. + + Two or more members of the `DisplayAttributes` enumeration may be combined by a bit-wise `OR` to specify how a particular word should be displayed. + > [!NOTE] -> The display formatting that the speech recognizer uses is language specific. - - For example, suppose the input phrase to a recognition engine using the default system grammar provided by is "Hello comma he said period". Then the recognition engine returns a containing five objects containing the following strings with the following `DisplayAttributes` values. - -|Item|`DisplayAttributes`| -|----------|-------------------------| -|Hello|OneTrailingSpace| -|,|OneTrailingSpace | ConsumeLeadingSpaces| -|he|OneTrailingSpace| -|said|OneTrailingSpace| -|.|OneTrailingSpace | ConsumeLeadingSpaces| - - The text returned for this recognized phrase is printed as: "Hello, he said." - - - -## Examples - The following example uses the property of a list of objects to format the words as a phrase. - -```csharp - -// Use the DisplayAttributes property to format speech as text. - -static string GetDisplayText(List words) -{ - StringBuilder sb = new StringBuilder(); - - // Concatenate the word units together. Use the DisplayAttributes - // property of each word unit to add or remove white space around - // the word unit. - foreach (RecognizedWordUnit word in words) - { - if ((word.DisplayAttributes - & DisplayAttributes.ConsumeLeadingSpaces) != 0)) - { - sb = new StringBuilder(sb.ToString().TrimEnd()); - } - - sb.Append(word.Text); - - if ((word.DisplayAttributes - & DisplayAttributes.OneTrailingSpace) != 0) - { - sb.Append(" "); - } - else if ((word.DisplayAttributes - & DisplayAttributes.TwoTrailingSpaces) != 0) - { - sb.Append(" "); - } - } - - return sb.ToString(); -} - -``` - +> The display formatting that the speech recognizer uses is language specific. + + For example, suppose the input phrase to a recognition engine using the default system grammar provided by is "Hello comma he said period". Then the recognition engine returns a containing five objects containing the following strings with the following `DisplayAttributes` values. + +|Item|`DisplayAttributes`| +|----------|-------------------------| +|Hello|OneTrailingSpace| +|,|OneTrailingSpace | ConsumeLeadingSpaces| +|he|OneTrailingSpace| +|said|OneTrailingSpace| +|.|OneTrailingSpace | ConsumeLeadingSpaces| + + The text returned for this recognized phrase is printed as: "Hello, he said." + + + +## Examples + The following example uses the property of a list of objects to format the words as a phrase. + +```csharp + +// Use the DisplayAttributes property to format speech as text. + +static string GetDisplayText(List words) +{ + StringBuilder sb = new StringBuilder(); + + // Concatenate the word units together. Use the DisplayAttributes + // property of each word unit to add or remove white space around + // the word unit. + foreach (RecognizedWordUnit word in words) + { + if ((word.DisplayAttributes + & DisplayAttributes.ConsumeLeadingSpaces) != 0)) + { + sb = new StringBuilder(sb.ToString().TrimEnd()); + } + + sb.Append(word.Text); + + if ((word.DisplayAttributes + & DisplayAttributes.OneTrailingSpace) != 0) + { + sb.Append(" "); + } + else if ((word.DisplayAttributes + & DisplayAttributes.TwoTrailingSpaces) != 0) + { + sb.Append(" "); + } + } + + return sb.ToString(); +} + +``` + ]]> diff --git a/xml/System.Speech.Recognition/EmulateRecognizeCompletedEventArgs.xml b/xml/System.Speech.Recognition/EmulateRecognizeCompletedEventArgs.xml index 946d6f96fcb..2e5da491f7a 100644 --- a/xml/System.Speech.Recognition/EmulateRecognizeCompletedEventArgs.xml +++ b/xml/System.Speech.Recognition/EmulateRecognizeCompletedEventArgs.xml @@ -25,49 +25,49 @@ Provides data for the event of the and classes. - is created when the object raises the event. To obtain information about the result of recognition, access the property in the handler for the event. - - Emulation is the process by which text, instead of audio, is the input to a speech recognition engine. To bypass the audio inputs for a object during emulation, use the method. - - If the speech recognition engine encounters an exception during the recognition operation, the property is set to the exception and the property is set to `null`. - - derives from . - - - -## Examples - The following example adds an event handler for the event to a . The handler gets the recognized text from the property. - -```csharp - -private SpeechRecognitionEngine sre; - -// Initialize the speech recognition engine. -private void Initialize() -{ - sre = new SpeechRecognitionEngine(); - - // Add a handler for the EmulateRecognizeCompleted event. - sre.EmulateRecognizeCompleted += new EventHandler(sre_EmulateRecognizeCompleted); - - // Add other initialization code here. -} - -// Handle the EmulateRecognizeCompleted event. -void sre_EmulateRecognizeCompleted(object sender, EmulateRecognizeCompletedEventArgs e) -{ - if (e.Result == null) return; - - string phrase = e.Result.Text; - - // Add event handler code here. -} - -``` - + is created when the object raises the event. To obtain information about the result of recognition, access the property in the handler for the event. + + Emulation is the process by which text, instead of audio, is the input to a speech recognition engine. To bypass the audio inputs for a object during emulation, use the method. + + If the speech recognition engine encounters an exception during the recognition operation, the property is set to the exception and the property is set to `null`. + + derives from . + + + +## Examples + The following example adds an event handler for the event to a . The handler gets the recognized text from the property. + +```csharp + +private SpeechRecognitionEngine sre; + +// Initialize the speech recognition engine. +private void Initialize() +{ + sre = new SpeechRecognitionEngine(); + + // Add a handler for the EmulateRecognizeCompleted event. + sre.EmulateRecognizeCompleted += new EventHandler(sre_EmulateRecognizeCompleted); + + // Add other initialization code here. +} + +// Handle the EmulateRecognizeCompleted event. +void sre_EmulateRecognizeCompleted(object sender, EmulateRecognizeCompletedEventArgs e) +{ + if (e.Result == null) return; + + string phrase = e.Result.Text; + + // Add event handler code here. +} + +``` + ]]> @@ -102,13 +102,13 @@ void sre_EmulateRecognizeCompleted(object sender, EmulateRecognizeCompletedEvent Gets the results of emulated recognition. Detailed information about the results of recognition, or if an error occurred. - object derives from and contains full information about a phrase returned by a recognition operation. You can obtain a list off all the recognition candidates from the property. - - If recognizer encounters an exception during the recognition operation, the property is set to the exception and the property is set to `null`. - + object derives from and contains full information about a phrase returned by a recognition operation. You can obtain a list off all the recognition candidates from the property. + + If recognizer encounters an exception during the recognition operation, the property is set to the exception and the property is set to `null`. + ]]> diff --git a/xml/System.Speech.Recognition/Grammar.xml b/xml/System.Speech.Recognition/Grammar.xml index 323ab209da9..0bdc9a7088b 100644 --- a/xml/System.Speech.Recognition/Grammar.xml +++ b/xml/System.Speech.Recognition/Grammar.xml @@ -44,7 +44,7 @@ Grammar constructors that accept XML-format grammar files in their arguments compile the XML grammars to a binary format to optimize them for loading and consumption by a speech recognition engine. You can reduce the amount of time required to construct a object from an XML-format grammar by compiling the grammar in advance, using one of the methods. - An application's speech recognition engine, as managed by a or object, can load multiple speech recognition grammars. The application can independently enable or disable individual grammars by setting the property, and modify recognition behavior through properties, such as the and properties. + An application's speech recognition engine, as managed by a or object, can load multiple speech recognition grammars. The application can independently enable or disable individual grammars by setting the property, and modify recognition behavior through properties, such as the and properties. The grammar's event is raised when input matches a path through the grammar. @@ -52,7 +52,7 @@ > [!NOTE] > It is a best practice to verify the safety of any URI or DLL used to build a object, which helps prevent security vulnerabilities when loading external resources. -> +> > Windows and the Speech platform provide security for applications constructing a instance from a DLL or from a grammar that supports scripting. > > Scripts in objects are always run as if downloaded from a web page in the `Internet Zone`. The Common Language Runtime (CLR) isolates any DLL loaded to obtain a grammar definition. @@ -1950,7 +1950,7 @@ public partial class Form1 : Form Speech recognition is a weighted system. It evaluates all possible recognition paths based on a combination of the weight of the grammar, the weights defined for alternatives within the grammar, and the probabilities defined by speech models. The speech recognition engine uses the combination of these weights and probabilities to rank potential alternative recognitions. Grammars with higher weights will contribute more to the ranking of recognition alternatives than grammars with lower weights. - The effect of the property on a speech recognizer is dependent on the implementation of the recognizer. Although the property can be used to tune the accuracy of speech recognition for an application, it should be used only after controlled diagnostic study of a particular recognition environment and with full information about the recognition engine under use. + The effect of the property on a speech recognizer is dependent on the implementation of the recognizer. Although the property can be used to tune the accuracy of speech recognition for an application, it should be used only after controlled diagnostic study of a particular recognition environment and with full information about the recognition engine under use. diff --git a/xml/System.Speech.Recognition/GrammarBuilder.xml b/xml/System.Speech.Recognition/GrammarBuilder.xml index d87dcd4d231..31868c84607 100644 --- a/xml/System.Speech.Recognition/GrammarBuilder.xml +++ b/xml/System.Speech.Recognition/GrammarBuilder.xml @@ -55,7 +55,7 @@ > [!IMPORTANT] > The speech recognizer can throw an exception when using a speech recognition grammar that contains duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the value of the same semantic element. - To help with debugging, the property returns the current status of the as a string. + To help with debugging, the property returns the current status of the as a string. ## Examples The following example uses and objects to construct a grammar that can recognize either of the two phrases, "Make background *colorChoice*" or "Set background to *colorChoice*". @@ -280,10 +280,10 @@ private Grammar CreateColorGrammar() instance from a object, you add semantic information to the grammar that can be returned in the recognition result. You can access the semantic information in the recognition result using the property of , which is available in the handler for the `SpeechRecognized` event. If the defines a , this can be used to retrieve the semantic information in a recognition result that is associated with the key. See the example for , and also see and . + When you create a instance from a object, you add semantic information to the grammar that can be returned in the recognition result. You can access the semantic information in the recognition result using the property of , which is available in the handler for the `SpeechRecognized` event. If the defines a , this can be used to retrieve the semantic information in a recognition result that is associated with the key. See the example for , and also see and . > [!IMPORTANT] -> When you construct objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you construct objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -371,10 +371,10 @@ private Grammar CreateColorGrammar() instance from a object, you add semantic information to the grammar that can be returned in the recognition result. You can access the semantic information in the recognition result using the property of , which is available in the handler for the `SpeechRecognized` event. If the defines a , this can be used to retrieve the semantic information in a recognition result that is associated with the key. See the example for , and also see and . + When you create a instance from a object, you add semantic information to the grammar that can be returned in the recognition result. You can access the semantic information in the recognition result using the property of , which is available in the handler for the `SpeechRecognized` event. If the defines a , this can be used to retrieve the semantic information in a recognition result that is associated with the key. See the example for , and also see and . > [!IMPORTANT] -> When you construct objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you construct objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -629,7 +629,7 @@ private static string BreakAtCaps(string item) The value of `minRepeat` must be greater than or equal to 0 and less than or equal to the value of `maxRepeat`. > [!IMPORTANT] -> When you specify repeats for objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you specify repeats for objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -808,7 +808,7 @@ private static Grammar CreatePizzaGrammar() For more information, see the and operators. > [!IMPORTANT] -> When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. For more information about building a speech recognition grammar that contains semantic information, see [Add Semantics to a GrammarBuilder Grammar](https://msdn.microsoft.com/library/hh361581.aspx). +> When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. For more information about building a speech recognition grammar that contains semantic information, see [Add Semantics to a GrammarBuilder Grammar](https://msdn.microsoft.com/library/hh361581.aspx). ]]> @@ -862,7 +862,7 @@ private static Grammar CreatePizzaGrammar() For more information, see the and operators. > [!IMPORTANT] -> When you combine and objects that contain or instances with other grammar elements, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you combine and objects that contain or instances with other grammar elements, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -945,7 +945,7 @@ private Grammar CreateColorGrammar() For more information, see the and operators. > [!IMPORTANT] -> When you combine and objects that contain or instances with other grammar elements, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you combine and objects that contain or instances with other grammar elements, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -1197,7 +1197,7 @@ private Grammar CreateColorGrammar() `alternateChoices` is added to the end of the current sequence of elements. > [!IMPORTANT] -> When you append objects that contain or instances to a object, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you append objects that contain or instances to a object, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -1274,7 +1274,7 @@ public static Grammar CreatePhonePhrase() `builder` is added to the end of the current sequence of grammar elements. > [!NOTE] -> When you append objects that contain or instances to a object, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you append objects that contain or instances to a object, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -1354,7 +1354,7 @@ public static Grammar CreatePhonePhrase() `key` is added to the end of the current sequence of elements. > [!IMPORTANT] -> When you append or instances to a object, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you append or instances to a object, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -1473,7 +1473,7 @@ namespace SampleRecognition `value` is added to the end of the current sequence of elements. > [!IMPORTANT] -> When you append or instances to a object, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you append or instances to a object, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -1709,7 +1709,7 @@ private Grammar[] CreateSubsetMatchTest() The value of `minRepeat` must be greater than or equal to 0 and less than or equal to the value of `maxRepeat`. > [!IMPORTANT] -> When you append objects that contain or instances to a object, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you append objects that contain or instances to a object, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. @@ -2289,7 +2289,7 @@ private bool IsValidPassword(RecognizedAudio passwordAudio) constructor creates a object that can be used by a speech recognizer of the corresponding culture. Only the property of the that is provided as the parameter to the Grammar constructor is used to set the culture of the resulting speech recognition grammar. + The constructor creates a object that can be used by a speech recognizer of the corresponding culture. Only the property of the that is provided as the parameter to the Grammar constructor is used to set the culture of the resulting speech recognition grammar. Microsoft Windows and the System.Speech API accept all valid language-country codes. To perform speech recognition using the language specified in the `Culture` property, a speech recognition engine that supports that language-country code must be installed. The speech recognition engines that shipped with Microsoft Windows 7 work with the following language-country codes. @@ -2491,7 +2491,7 @@ private static Grammar CreatePizzaGrammar() This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. > [!IMPORTANT] -> When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. The equivalent method for this operator is ]]> @@ -2548,7 +2548,7 @@ private static Grammar CreatePizzaGrammar() This method accepts the objects listed above for the `builder` parameter. For more information, see the operators. > [!IMPORTANT] -> When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you combine and objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. The equivalent method for this operator is @@ -2634,7 +2634,7 @@ private Grammar CreateColorGrammar() This method accepts the objects listed above for the `builder1` and `builder2` parameters. For more information, see the operators. > [!IMPORTANT] -> When you combine objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. +> When you combine objects that contain or instances, make sure you avoid creating duplicate semantic elements with the same key name or multiple semantic elements that could repeatedly modify the property of a object. The speech recognizer can throw an exception if it encounters these circumstances. The equivalent method for this operator is ]]> diff --git a/xml/System.Speech.Recognition/LoadGrammarCompletedEventArgs.xml b/xml/System.Speech.Recognition/LoadGrammarCompletedEventArgs.xml index c703065b62f..301a452efdc 100644 --- a/xml/System.Speech.Recognition/LoadGrammarCompletedEventArgs.xml +++ b/xml/System.Speech.Recognition/LoadGrammarCompletedEventArgs.xml @@ -25,117 +25,117 @@ Provides data for the event of a or object. - object raises its or the object raises its event. The events are raised when calls to the `LoadGrammarAsync` methods complete. - - To obtain information about the object that was loaded, access the property in the handler for the event. - - If the recognizer encounters an exception during the operation, the property is set to the exception and the property of the associated may be `false`. - - - -## Examples - The following example creates a shared speech recognizer, and then creates two types of grammars for recognizing specific words and for accepting free dictation. The example asynchronously loads all the created grammars to the recognizer. Handlers for the recognizer's and events report the results of recognition and which grammar was used to perform the recognition. - -```csharp -using System; -using System.Speech.Recognition; - -namespace SampleRecognition -{ - class Program - { - private static SpeechRecognizer recognizer; - public static void Main(string[] args) - { - - // Initialize a shared speech recognition engine. - recognizer = new SpeechRecognizer(); - - // Add a handler for the LoadGrammarCompleted event. - recognizer.LoadGrammarCompleted += - new EventHandler(recognizer_LoadGrammarCompleted); - - // Add a handler for the SpeechRecognized event. - recognizer.SpeechRecognized += - new EventHandler(recognizer_SpeechRecognized); - - // Add a handler for the StateChanged event. - recognizer.StateChanged += - new EventHandler(recognizer_StateChanged); - - // Create the "yesno" grammar and build it into a Grammar object. - Choices yesChoices = new Choices(new string[] { "yes", "yup", "yah}" }); - SemanticResultValue yesValue = - new SemanticResultValue(yesChoices, (bool)true); - Choices noChoices = new Choices(new string[] { "no", "nope", "nah" }); - SemanticResultValue noValue = - new SemanticResultValue(noChoices, (bool)false); - SemanticResultKey yesNoKey = - new SemanticResultKey("yesno", new Choices(new GrammarBuilder[] { yesValue, noValue })); - Grammar yesnoGrammar = new Grammar(yesNoKey); - yesnoGrammar.Name = "yesNo"; - - // Create the "done" grammar within the constructor of a Grammar object. - Grammar doneGrammar = - new Grammar(new GrammarBuilder(new Choices(new string[] { "done", "exit", "quit", "stop" }))); - doneGrammar.Name = "Done"; - - // Create a dictation grammar. - Grammar dictation = new DictationGrammar(); - dictation.Name = "Dictation"; - - // Load grammars to the recognizer. - recognizer.LoadGrammarAsync(yesnoGrammar); - recognizer.LoadGrammarAsync(doneGrammar); - recognizer.LoadGrammarAsync(dictation); - - // Keep the console window open. - Console.ReadLine(); - } - - // Handle the SpeechRecognized event. - static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine("Grammar({0}): {1}", e.Result.Grammar.Name, e.Result.Text); - - // Add event handler code here. - } - - // Handle the LoadGrammarCompleted event. - static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) - { - string grammarName = e.Grammar.Name; - bool grammarLoaded = e.Grammar.Loaded; - - if (e.Error != null) - { - - Console.WriteLine("LoadGrammar for {0} failed with a {1}.", - grammarName, e.Error.GetType().Name); - - // Add exception handling code here. - } - - Console.WriteLine("Grammar {0} {1} loaded.", - grammarName, (grammarLoaded) ? "is" : "is not"); - } - - // Put the shared speech recognizer into "listening" mode. - static void recognizer_StateChanged(object sender, StateChangedEventArgs e) - { - if (e.RecognizerState != RecognizerState.Stopped) - { - recognizer.EmulateRecognizeAsync("Start listening"); - } - } - } -} - -``` - + object raises its or the object raises its event. The events are raised when calls to the `LoadGrammarAsync` methods complete. + + To obtain information about the object that was loaded, access the property in the handler for the event. + + If the recognizer encounters an exception during the operation, the property is set to the exception and the property of the associated may be `false`. + + + +## Examples + The following example creates a shared speech recognizer, and then creates two types of grammars for recognizing specific words and for accepting free dictation. The example asynchronously loads all the created grammars to the recognizer. Handlers for the recognizer's and events report the results of recognition and which grammar was used to perform the recognition. + +```csharp +using System; +using System.Speech.Recognition; + +namespace SampleRecognition +{ + class Program + { + private static SpeechRecognizer recognizer; + public static void Main(string[] args) + { + + // Initialize a shared speech recognition engine. + recognizer = new SpeechRecognizer(); + + // Add a handler for the LoadGrammarCompleted event. + recognizer.LoadGrammarCompleted += + new EventHandler(recognizer_LoadGrammarCompleted); + + // Add a handler for the SpeechRecognized event. + recognizer.SpeechRecognized += + new EventHandler(recognizer_SpeechRecognized); + + // Add a handler for the StateChanged event. + recognizer.StateChanged += + new EventHandler(recognizer_StateChanged); + + // Create the "yesno" grammar and build it into a Grammar object. + Choices yesChoices = new Choices(new string[] { "yes", "yup", "yah}" }); + SemanticResultValue yesValue = + new SemanticResultValue(yesChoices, (bool)true); + Choices noChoices = new Choices(new string[] { "no", "nope", "nah" }); + SemanticResultValue noValue = + new SemanticResultValue(noChoices, (bool)false); + SemanticResultKey yesNoKey = + new SemanticResultKey("yesno", new Choices(new GrammarBuilder[] { yesValue, noValue })); + Grammar yesnoGrammar = new Grammar(yesNoKey); + yesnoGrammar.Name = "yesNo"; + + // Create the "done" grammar within the constructor of a Grammar object. + Grammar doneGrammar = + new Grammar(new GrammarBuilder(new Choices(new string[] { "done", "exit", "quit", "stop" }))); + doneGrammar.Name = "Done"; + + // Create a dictation grammar. + Grammar dictation = new DictationGrammar(); + dictation.Name = "Dictation"; + + // Load grammars to the recognizer. + recognizer.LoadGrammarAsync(yesnoGrammar); + recognizer.LoadGrammarAsync(doneGrammar); + recognizer.LoadGrammarAsync(dictation); + + // Keep the console window open. + Console.ReadLine(); + } + + // Handle the SpeechRecognized event. + static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine("Grammar({0}): {1}", e.Result.Grammar.Name, e.Result.Text); + + // Add event handler code here. + } + + // Handle the LoadGrammarCompleted event. + static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) + { + string grammarName = e.Grammar.Name; + bool grammarLoaded = e.Grammar.Loaded; + + if (e.Error != null) + { + + Console.WriteLine("LoadGrammar for {0} failed with a {1}.", + grammarName, e.Error.GetType().Name); + + // Add exception handling code here. + } + + Console.WriteLine("Grammar {0} {1} loaded.", + grammarName, (grammarLoaded) ? "is" : "is not"); + } + + // Put the shared speech recognizer into "listening" mode. + static void recognizer_StateChanged(object sender, StateChangedEventArgs e) + { + if (e.RecognizerState != RecognizerState.Stopped) + { + recognizer.EmulateRecognizeAsync("Start listening"); + } + } + } +} + +``` + ]]> @@ -171,11 +171,11 @@ namespace SampleRecognition The object that has completed loading. The that was loaded by the recognizer. - property is set to the exception and the property of the associated may be `false`. - + property is set to the exception and the property of the associated may be `false`. + ]]> diff --git a/xml/System.Speech.Recognition/RecognitionEventArgs.xml b/xml/System.Speech.Recognition/RecognitionEventArgs.xml index 92c0fdbe21b..6a3d617f892 100644 --- a/xml/System.Speech.Recognition/RecognitionEventArgs.xml +++ b/xml/System.Speech.Recognition/RecognitionEventArgs.xml @@ -32,65 +32,65 @@ Provides information about speech recognition events. - property obtains the recognition information as a object. For more information about speech recognition events, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). - - **RecognitionEventArgs** is the base for the following classes: - -- - -- - -- - - derives from . - - - -## Examples - The following example attaches a handler for the , , and events of the speech recognizer. The event argument types for the three events all derive from , which is used as the event data parameter in the handler. - -```csharp - -// Initialize the speech recognizer. -private void Initialize(SpeechRecognitionEngine recognizer) -{ - // Attach handlers for the SpeechHypothesized, SpeechRecognitionRejected, - // and SpeechRecognized events. - recognizer.SpeechHypothesized += - new EventHandler(DisplayResult); - recognizer.SpeechRecognitionRejected += - new EventHandler(DisplayResult); - recognizer.SpeechRecognized += - new EventHandler(DisplayResult); - - // Add other initialization code here. -} - -// Handle the SpeechHypothesized, SpeechRecognitionRejected, -// and SpeechRecognized events. -private void DisplayResult(object sender, RecognitionEventArgs e) -{ - if (e is SpeechHypothesizedEventArgs) - { - Console.WriteLine("Speech hypothesized:"); - } - else if (e is SpeechRecognitionRejectedEventArgs) - { - Console.WriteLine("Speech recognition rejected:"); - } - else if (e is SpeechRecognizedEventArgs) - { - Console.WriteLine("Speech recognized:"); - } - - // Add code to handle the event. -} - -``` - + property obtains the recognition information as a object. For more information about speech recognition events, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). + + **RecognitionEventArgs** is the base for the following classes: + +- + +- + +- + + derives from . + + + +## Examples + The following example attaches a handler for the , , and events of the speech recognizer. The event argument types for the three events all derive from , which is used as the event data parameter in the handler. + +```csharp + +// Initialize the speech recognizer. +private void Initialize(SpeechRecognitionEngine recognizer) +{ + // Attach handlers for the SpeechHypothesized, SpeechRecognitionRejected, + // and SpeechRecognized events. + recognizer.SpeechHypothesized += + new EventHandler(DisplayResult); + recognizer.SpeechRecognitionRejected += + new EventHandler(DisplayResult); + recognizer.SpeechRecognized += + new EventHandler(DisplayResult); + + // Add other initialization code here. +} + +// Handle the SpeechHypothesized, SpeechRecognitionRejected, +// and SpeechRecognized events. +private void DisplayResult(object sender, RecognitionEventArgs e) +{ + if (e is SpeechHypothesizedEventArgs) + { + Console.WriteLine("Speech hypothesized:"); + } + else if (e is SpeechRecognitionRejectedEventArgs) + { + Console.WriteLine("Speech recognition rejected:"); + } + else if (e is SpeechRecognizedEventArgs) + { + Console.WriteLine("Speech recognized:"); + } + + // Add code to handle the event. +} + +``` + ]]> diff --git a/xml/System.Speech.Recognition/RecognitionResult.xml b/xml/System.Speech.Recognition/RecognitionResult.xml index 2cf354a68ba..9dbcfc683c0 100644 --- a/xml/System.Speech.Recognition/RecognitionResult.xml +++ b/xml/System.Speech.Recognition/RecognitionResult.xml @@ -45,15 +45,15 @@ ## Remarks This class derives from and provides detailed information about speech recognition, including the following: -- The property references the that the recognizer used to identify the speech. +- The property references the that the recognizer used to identify the speech. -- The property contains the normalized text for the phrase. For more information about text normalization, see . +- The property contains the normalized text for the phrase. For more information about text normalization, see . -- The property references the semantic information contained in the result. The semantic information is a dictionary of the key names and associated semantic data. +- The property references the semantic information contained in the result. The semantic information is a dictionary of the key names and associated semantic data. -- The property contains a collection of objects that represent other candidate interpretations of the audio input. See for additional information. +- The property contains a collection of objects that represent other candidate interpretations of the audio input. See for additional information. -- The property contains an ordered collection of objects that represent each recognized word in the input. Each contains display format, lexical format, and pronunciation information for the corresponding word. +- The property contains an ordered collection of objects that represent each recognized word in the input. Each contains display format, lexical format, and pronunciation information for the corresponding word. Certain members of the , , and classes can generate a . For more information, see the following methods and events. @@ -334,7 +334,7 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) property. + To get the complete audio associated with the recognition result, use the property. diff --git a/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml b/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml index 097524d8fe0..b5bcd0d9bd2 100644 --- a/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml +++ b/xml/System.Speech.Recognition/RecognizeCompletedEventArgs.xml @@ -25,127 +25,127 @@ Provides data for the event raised by a or a object. - is created when the or the object raises its `SpeechRecognized` event after completing a `RecognizeAsync` operation. For more information about speech recognition events, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). - - - -## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. - -``` -using System; -using System.Speech.Recognition; - -namespace SampleRecognition -{ - class Program - { - private static SpeechRecognitionEngine recognizer; - public static void Main(string[] args) - { - - // Initialize a SpeechRecognitionEngine object and set its input. - recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); - recognizer.SetInputToDefaultAudioDevice(); - - // Configure recognition parameters. - recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); - recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); - recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); - recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); - - // Add a handler for the LoadGrammarCompleted event. - recognizer.LoadGrammarCompleted += - new EventHandler(recognizer_LoadGrammarCompleted); - - // Add a handler for the RecognizeCompleted event. - recognizer.RecognizeCompleted += - new EventHandler(recognizer_RecognizeCompleted); - - // Create a speech recognition grammar and build it into a Grammar object. - Choices bankingMenu = new Choices(new string[] - { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); - GrammarBuilder banking = new GrammarBuilder(bankingMenu); - Grammar bankGrammar = new Grammar(banking); - bankGrammar.Name = "Banking Menu"; - - // Load the Grammar objects to the recognizer. - recognizer.LoadGrammarAsync(bankGrammar); - - // Start asynchronous, continuous recognition. - recognizer.RecognizeAsync(); - - // Keep the console window open. - Console.ReadLine(); - } - - // Handle the RecognizeCompleted event. - static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) - { - if (e.Error != null) - { - Console.WriteLine( - "RecognizeCompleted, error occurred during recognition: {0}", e.Error); - return; - } - - if (e.InitialSilenceTimeout || e.BabbleTimeout) - { - Console.WriteLine( - "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", - e.BabbleTimeout, e.InitialSilenceTimeout); - return; - } - - if (e.InputStreamEnded) - { - Console.WriteLine( - "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", - e.AudioPosition, e.InputStreamEnded); - } - - if (e.Result != null) - { - Console.WriteLine( - "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", - e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); - } - - else - { - Console.WriteLine("RecognizeCompleted: No result."); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // Handle the LoadGrammarCompleted event. - static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) - { - string grammarName = e.Grammar.Name; - bool grammarLoaded = e.Grammar.Loaded; - bool grammarEnabled = e.Grammar.Enabled; - - if (e.Error != null) - { - Console.WriteLine("LoadGrammar for {0} failed with a {1}.", - grammarName, e.Error.GetType().Name); - - // Add exception handling code here. - } - - Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, - (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); - } - } -} -``` - + is created when the or the object raises its `SpeechRecognized` event after completing a `RecognizeAsync` operation. For more information about speech recognition events, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). + + + +## Examples + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + +``` +using System; +using System.Speech.Recognition; + +namespace SampleRecognition +{ + class Program + { + private static SpeechRecognitionEngine recognizer; + public static void Main(string[] args) + { + + // Initialize a SpeechRecognitionEngine object and set its input. + recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); + recognizer.SetInputToDefaultAudioDevice(); + + // Configure recognition parameters. + recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); + recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); + recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); + recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); + + // Add a handler for the LoadGrammarCompleted event. + recognizer.LoadGrammarCompleted += + new EventHandler(recognizer_LoadGrammarCompleted); + + // Add a handler for the RecognizeCompleted event. + recognizer.RecognizeCompleted += + new EventHandler(recognizer_RecognizeCompleted); + + // Create a speech recognition grammar and build it into a Grammar object. + Choices bankingMenu = new Choices(new string[] + { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); + GrammarBuilder banking = new GrammarBuilder(bankingMenu); + Grammar bankGrammar = new Grammar(banking); + bankGrammar.Name = "Banking Menu"; + + // Load the Grammar objects to the recognizer. + recognizer.LoadGrammarAsync(bankGrammar); + + // Start asynchronous, continuous recognition. + recognizer.RecognizeAsync(); + + // Keep the console window open. + Console.ReadLine(); + } + + // Handle the RecognizeCompleted event. + static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) + { + if (e.Error != null) + { + Console.WriteLine( + "RecognizeCompleted, error occurred during recognition: {0}", e.Error); + return; + } + + if (e.InitialSilenceTimeout || e.BabbleTimeout) + { + Console.WriteLine( + "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", + e.BabbleTimeout, e.InitialSilenceTimeout); + return; + } + + if (e.InputStreamEnded) + { + Console.WriteLine( + "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", + e.AudioPosition, e.InputStreamEnded); + } + + if (e.Result != null) + { + Console.WriteLine( + "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", + e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); + } + + else + { + Console.WriteLine("RecognizeCompleted: No result."); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // Handle the LoadGrammarCompleted event. + static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) + { + string grammarName = e.Grammar.Name; + bool grammarLoaded = e.Grammar.Loaded; + bool grammarEnabled = e.Grammar.Enabled; + + if (e.Error != null) + { + Console.WriteLine("LoadGrammar for {0} failed with a {1}.", + grammarName, e.Error.GetType().Name); + + // Add exception handling code here. + } + + Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, + (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); + } + } +} +``` + ]]> @@ -181,128 +181,128 @@ namespace SampleRecognition Gets the location in the input device's audio stream associated with the event. The location in the input device's audio stream associated with the event. - property references the recognizer's position within its audio input. These positions can be different. For more information, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). - - - -## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. - -``` -using System; -using System.Speech.Recognition; - -namespace SampleRecognition -{ - class Program - { - private static SpeechRecognitionEngine recognizer; - public static void Main(string[] args) - { - - // Initialize a SpeechRecognitionEngine object and set its input. - recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); - recognizer.SetInputToDefaultAudioDevice(); - - // Configure recognition parameters. - recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); - recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); - recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); - recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); - - // Add a handler for the LoadGrammarCompleted event. - recognizer.LoadGrammarCompleted += - new EventHandler(recognizer_LoadGrammarCompleted); - - // Add a handler for the RecognizeCompleted event. - recognizer.RecognizeCompleted += - new EventHandler(recognizer_RecognizeCompleted); - - // Create a speech recognition grammar and build it into a Grammar object. - Choices bankingMenu = new Choices(new string[] - { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); - GrammarBuilder banking = new GrammarBuilder(bankingMenu); - Grammar bankGrammar = new Grammar(banking); - bankGrammar.Name = "Banking Menu"; - - // Load the Grammar objects to the recognizer. - recognizer.LoadGrammarAsync(bankGrammar); - - // Start asynchronous, continuous recognition. - recognizer.RecognizeAsync(); - - // Keep the console window open. - Console.ReadLine(); - } - - // Handle the RecognizeCompleted event. - static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) - { - if (e.Error != null) - { - Console.WriteLine( - "RecognizeCompleted, error occurred during recognition: {0}", e.Error); - return; - } - - if (e.InitialSilenceTimeout || e.BabbleTimeout) - { - Console.WriteLine( - "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", - e.BabbleTimeout, e.InitialSilenceTimeout); - return; - } - - if (e.InputStreamEnded) - { - Console.WriteLine( - "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", - e.AudioPosition, e.InputStreamEnded); - } - - if (e.Result != null) - { - Console.WriteLine( - "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", - e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); - } - - else - { - Console.WriteLine("RecognizeCompleted: No result."); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // Handle the LoadGrammarCompleted event. - static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) - { - string grammarName = e.Grammar.Name; - bool grammarLoaded = e.Grammar.Loaded; - bool grammarEnabled = e.Grammar.Enabled; - - if (e.Error != null) - { - Console.WriteLine("LoadGrammar for {0} failed with a {1}.", - grammarName, e.Error.GetType().Name); - - // Add exception handling code here. - } - - Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, - (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); - } - } -} - -``` - + property references the recognizer's position within its audio input. These positions can be different. For more information, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). + + + +## Examples + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + +``` +using System; +using System.Speech.Recognition; + +namespace SampleRecognition +{ + class Program + { + private static SpeechRecognitionEngine recognizer; + public static void Main(string[] args) + { + + // Initialize a SpeechRecognitionEngine object and set its input. + recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); + recognizer.SetInputToDefaultAudioDevice(); + + // Configure recognition parameters. + recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); + recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); + recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); + recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); + + // Add a handler for the LoadGrammarCompleted event. + recognizer.LoadGrammarCompleted += + new EventHandler(recognizer_LoadGrammarCompleted); + + // Add a handler for the RecognizeCompleted event. + recognizer.RecognizeCompleted += + new EventHandler(recognizer_RecognizeCompleted); + + // Create a speech recognition grammar and build it into a Grammar object. + Choices bankingMenu = new Choices(new string[] + { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); + GrammarBuilder banking = new GrammarBuilder(bankingMenu); + Grammar bankGrammar = new Grammar(banking); + bankGrammar.Name = "Banking Menu"; + + // Load the Grammar objects to the recognizer. + recognizer.LoadGrammarAsync(bankGrammar); + + // Start asynchronous, continuous recognition. + recognizer.RecognizeAsync(); + + // Keep the console window open. + Console.ReadLine(); + } + + // Handle the RecognizeCompleted event. + static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) + { + if (e.Error != null) + { + Console.WriteLine( + "RecognizeCompleted, error occurred during recognition: {0}", e.Error); + return; + } + + if (e.InitialSilenceTimeout || e.BabbleTimeout) + { + Console.WriteLine( + "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", + e.BabbleTimeout, e.InitialSilenceTimeout); + return; + } + + if (e.InputStreamEnded) + { + Console.WriteLine( + "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", + e.AudioPosition, e.InputStreamEnded); + } + + if (e.Result != null) + { + Console.WriteLine( + "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", + e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); + } + + else + { + Console.WriteLine("RecognizeCompleted: No result."); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // Handle the LoadGrammarCompleted event. + static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) + { + string grammarName = e.Grammar.Name; + bool grammarLoaded = e.Grammar.Loaded; + bool grammarEnabled = e.Grammar.Enabled; + + if (e.Error != null) + { + Console.WriteLine("LoadGrammar for {0} failed with a {1}.", + grammarName, e.Error.GetType().Name); + + // Add exception handling code here. + } + + Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, + (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); + } + } +} + +``` + ]]> @@ -338,123 +338,123 @@ namespace SampleRecognition if the has detected only background noise for longer than was specified by its property; otherwise . - method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. - -``` -using System; -using System.Speech.Recognition; - -namespace SampleRecognition -{ - class Program - { - private static SpeechRecognitionEngine recognizer; - public static void Main(string[] args) - { - - // Initialize a SpeechRecognitionEngine object and set its input. - recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); - recognizer.SetInputToDefaultAudioDevice(); - - // Configure recognition parameters. - recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); - recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); - recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); - recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); - - // Add a handler for the LoadGrammarCompleted event. - recognizer.LoadGrammarCompleted += - new EventHandler(recognizer_LoadGrammarCompleted); - - // Add a handler for the RecognizeCompleted event. - recognizer.RecognizeCompleted += - new EventHandler(recognizer_RecognizeCompleted); - - // Create a speech recognition grammar and build it into a Grammar object. - Choices bankingMenu = new Choices(new string[] - { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); - GrammarBuilder banking = new GrammarBuilder(bankingMenu); - Grammar bankGrammar = new Grammar(banking); - bankGrammar.Name = "Banking Menu"; - - // Load the Grammar objects to the recognizer. - recognizer.LoadGrammarAsync(bankGrammar); - - // Start asynchronous, continuous recognition. - recognizer.RecognizeAsync(); - - // Keep the console window open. - Console.ReadLine(); - } - - // Handle the RecognizeCompleted event. - static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) - { - if (e.Error != null) - { - Console.WriteLine( - "RecognizeCompleted, error occurred during recognition: {0}", e.Error); - return; - } - - if (e.InitialSilenceTimeout || e.BabbleTimeout) - { - Console.WriteLine( - "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", - e.BabbleTimeout, e.InitialSilenceTimeout); - return; - } - - if (e.InputStreamEnded) - { - Console.WriteLine( - "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", - e.AudioPosition, e.InputStreamEnded); - } - - if (e.Result != null) - { - Console.WriteLine( - "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", - e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); - } - - else - { - Console.WriteLine("RecognizeCompleted: No result."); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // Handle the LoadGrammarCompleted event. - static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) - { - string grammarName = e.Grammar.Name; - bool grammarLoaded = e.Grammar.Loaded; - bool grammarEnabled = e.Grammar.Enabled; - - if (e.Error != null) - { - Console.WriteLine("LoadGrammar for {0} failed with a {1}.", - grammarName, e.Error.GetType().Name); - - // Add exception handling code here. - } - - Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, - (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); - } - } -} - -``` - + method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + +``` +using System; +using System.Speech.Recognition; + +namespace SampleRecognition +{ + class Program + { + private static SpeechRecognitionEngine recognizer; + public static void Main(string[] args) + { + + // Initialize a SpeechRecognitionEngine object and set its input. + recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); + recognizer.SetInputToDefaultAudioDevice(); + + // Configure recognition parameters. + recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); + recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); + recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); + recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); + + // Add a handler for the LoadGrammarCompleted event. + recognizer.LoadGrammarCompleted += + new EventHandler(recognizer_LoadGrammarCompleted); + + // Add a handler for the RecognizeCompleted event. + recognizer.RecognizeCompleted += + new EventHandler(recognizer_RecognizeCompleted); + + // Create a speech recognition grammar and build it into a Grammar object. + Choices bankingMenu = new Choices(new string[] + { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); + GrammarBuilder banking = new GrammarBuilder(bankingMenu); + Grammar bankGrammar = new Grammar(banking); + bankGrammar.Name = "Banking Menu"; + + // Load the Grammar objects to the recognizer. + recognizer.LoadGrammarAsync(bankGrammar); + + // Start asynchronous, continuous recognition. + recognizer.RecognizeAsync(); + + // Keep the console window open. + Console.ReadLine(); + } + + // Handle the RecognizeCompleted event. + static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) + { + if (e.Error != null) + { + Console.WriteLine( + "RecognizeCompleted, error occurred during recognition: {0}", e.Error); + return; + } + + if (e.InitialSilenceTimeout || e.BabbleTimeout) + { + Console.WriteLine( + "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", + e.BabbleTimeout, e.InitialSilenceTimeout); + return; + } + + if (e.InputStreamEnded) + { + Console.WriteLine( + "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", + e.AudioPosition, e.InputStreamEnded); + } + + if (e.Result != null) + { + Console.WriteLine( + "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", + e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); + } + + else + { + Console.WriteLine("RecognizeCompleted: No result."); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // Handle the LoadGrammarCompleted event. + static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) + { + string grammarName = e.Grammar.Name; + bool grammarLoaded = e.Grammar.Loaded; + bool grammarEnabled = e.Grammar.Enabled; + + if (e.Error != null) + { + Console.WriteLine("LoadGrammar for {0} failed with a {1}.", + grammarName, e.Error.GetType().Name); + + // Add exception handling code here. + } + + Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, + (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); + } + } +} + +``` + ]]> @@ -490,123 +490,123 @@ namespace SampleRecognition if the has detected only silence for a longer time period than was specified by its property; otherwise . - method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. - -``` -using System; -using System.Speech.Recognition; - -namespace SampleRecognition -{ - class Program - { - private static SpeechRecognitionEngine recognizer; - public static void Main(string[] args) - { - - // Initialize a SpeechRecognitionEngine object and set its input. - recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); - recognizer.SetInputToDefaultAudioDevice(); - - // Configure recognition parameters. - recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); - recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); - recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); - recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); - - // Add a handler for the LoadGrammarCompleted event. - recognizer.LoadGrammarCompleted += - new EventHandler(recognizer_LoadGrammarCompleted); - - // Add a handler for the RecognizeCompleted event. - recognizer.RecognizeCompleted += - new EventHandler(recognizer_RecognizeCompleted); - - // Create a speech recognition grammar and build it into a Grammar object. - Choices bankingMenu = new Choices(new string[] - { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); - GrammarBuilder banking = new GrammarBuilder(bankingMenu); - Grammar bankGrammar = new Grammar(banking); - bankGrammar.Name = "Banking Menu"; - - // Load the Grammar objects to the recognizer. - recognizer.LoadGrammarAsync(bankGrammar); - - // Start asynchronous, continuous recognition. - recognizer.RecognizeAsync(); - - // Keep the console window open. - Console.ReadLine(); - } - - // Handle the RecognizeCompleted event. - static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) - { - if (e.Error != null) - { - Console.WriteLine( - "RecognizeCompleted, error occurred during recognition: {0}", e.Error); - return; - } - - if (e.InitialSilenceTimeout || e.BabbleTimeout) - { - Console.WriteLine( - "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", - e.BabbleTimeout, e.InitialSilenceTimeout); - return; - } - - if (e.InputStreamEnded) - { - Console.WriteLine( - "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", - e.AudioPosition, e.InputStreamEnded); - } - - if (e.Result != null) - { - Console.WriteLine( - "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", - e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); - } - - else - { - Console.WriteLine("RecognizeCompleted: No result."); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // Handle the LoadGrammarCompleted event. - static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) - { - string grammarName = e.Grammar.Name; - bool grammarLoaded = e.Grammar.Loaded; - bool grammarEnabled = e.Grammar.Enabled; - - if (e.Error != null) - { - Console.WriteLine("LoadGrammar for {0} failed with a {1}.", - grammarName, e.Error.GetType().Name); - - // Add exception handling code here. - } - - Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, - (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); - } - } -} - -``` - + method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + +``` +using System; +using System.Speech.Recognition; + +namespace SampleRecognition +{ + class Program + { + private static SpeechRecognitionEngine recognizer; + public static void Main(string[] args) + { + + // Initialize a SpeechRecognitionEngine object and set its input. + recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); + recognizer.SetInputToDefaultAudioDevice(); + + // Configure recognition parameters. + recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); + recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); + recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); + recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); + + // Add a handler for the LoadGrammarCompleted event. + recognizer.LoadGrammarCompleted += + new EventHandler(recognizer_LoadGrammarCompleted); + + // Add a handler for the RecognizeCompleted event. + recognizer.RecognizeCompleted += + new EventHandler(recognizer_RecognizeCompleted); + + // Create a speech recognition grammar and build it into a Grammar object. + Choices bankingMenu = new Choices(new string[] + { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); + GrammarBuilder banking = new GrammarBuilder(bankingMenu); + Grammar bankGrammar = new Grammar(banking); + bankGrammar.Name = "Banking Menu"; + + // Load the Grammar objects to the recognizer. + recognizer.LoadGrammarAsync(bankGrammar); + + // Start asynchronous, continuous recognition. + recognizer.RecognizeAsync(); + + // Keep the console window open. + Console.ReadLine(); + } + + // Handle the RecognizeCompleted event. + static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) + { + if (e.Error != null) + { + Console.WriteLine( + "RecognizeCompleted, error occurred during recognition: {0}", e.Error); + return; + } + + if (e.InitialSilenceTimeout || e.BabbleTimeout) + { + Console.WriteLine( + "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", + e.BabbleTimeout, e.InitialSilenceTimeout); + return; + } + + if (e.InputStreamEnded) + { + Console.WriteLine( + "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", + e.AudioPosition, e.InputStreamEnded); + } + + if (e.Result != null) + { + Console.WriteLine( + "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", + e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); + } + + else + { + Console.WriteLine("RecognizeCompleted: No result."); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // Handle the LoadGrammarCompleted event. + static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) + { + string grammarName = e.Grammar.Name; + bool grammarLoaded = e.Grammar.Loaded; + bool grammarEnabled = e.Grammar.Enabled; + + if (e.Error != null) + { + Console.WriteLine("LoadGrammar for {0} failed with a {1}.", + grammarName, e.Error.GetType().Name); + + // Add exception handling code here. + } + + Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, + (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); + } + } +} + +``` + ]]> @@ -642,128 +642,128 @@ namespace SampleRecognition if the recognizer no longer has audio input; otherwise, . - and methods. - - - -## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. - -``` -using System; -using System.Speech.Recognition; - -namespace SampleRecognition -{ - class Program - { - private static SpeechRecognitionEngine recognizer; - public static void Main(string[] args) - { - - // Initialize a SpeechRecognitionEngine object and set its input. - recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); - recognizer.SetInputToDefaultAudioDevice(); - - // Configure recognition parameters. - recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); - recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); - recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); - recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); - - // Add a handler for the LoadGrammarCompleted event. - recognizer.LoadGrammarCompleted += - new EventHandler(recognizer_LoadGrammarCompleted); - - // Add a handler for the RecognizeCompleted event. - recognizer.RecognizeCompleted += - new EventHandler(recognizer_RecognizeCompleted); - - // Create a speech recognition grammar and build it into a Grammar object. - Choices bankingMenu = new Choices(new string[] - { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); - GrammarBuilder banking = new GrammarBuilder(bankingMenu); - Grammar bankGrammar = new Grammar(banking); - bankGrammar.Name = "Banking Menu"; - - // Load the Grammar objects to the recognizer. - recognizer.LoadGrammarAsync(bankGrammar); - - // Start asynchronous, continuous recognition. - recognizer.RecognizeAsync(); - - // Keep the console window open. - Console.ReadLine(); - } - - // Handle the RecognizeCompleted event. - static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) - { - if (e.Error != null) - { - Console.WriteLine( - "RecognizeCompleted, error occurred during recognition: {0}", e.Error); - return; - } - - if (e.InitialSilenceTimeout || e.BabbleTimeout) - { - Console.WriteLine( - "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", - e.BabbleTimeout, e.InitialSilenceTimeout); - return; - } - - if (e.InputStreamEnded) - { - Console.WriteLine( - "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", - e.AudioPosition, e.InputStreamEnded); - } - - if (e.Result != null) - { - Console.WriteLine( - "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", - e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); - } - - else - { - Console.WriteLine("RecognizeCompleted: No result."); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // Handle the LoadGrammarCompleted event. - static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) - { - string grammarName = e.Grammar.Name; - bool grammarLoaded = e.Grammar.Loaded; - bool grammarEnabled = e.Grammar.Enabled; - - if (e.Error != null) - { - Console.WriteLine("LoadGrammar for {0} failed with a {1}.", - grammarName, e.Error.GetType().Name); - - // Add exception handling code here. - } - - Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, - (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); - } - } -} - -``` - + and methods. + + + +## Examples + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + +``` +using System; +using System.Speech.Recognition; + +namespace SampleRecognition +{ + class Program + { + private static SpeechRecognitionEngine recognizer; + public static void Main(string[] args) + { + + // Initialize a SpeechRecognitionEngine object and set its input. + recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); + recognizer.SetInputToDefaultAudioDevice(); + + // Configure recognition parameters. + recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); + recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); + recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); + recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); + + // Add a handler for the LoadGrammarCompleted event. + recognizer.LoadGrammarCompleted += + new EventHandler(recognizer_LoadGrammarCompleted); + + // Add a handler for the RecognizeCompleted event. + recognizer.RecognizeCompleted += + new EventHandler(recognizer_RecognizeCompleted); + + // Create a speech recognition grammar and build it into a Grammar object. + Choices bankingMenu = new Choices(new string[] + { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); + GrammarBuilder banking = new GrammarBuilder(bankingMenu); + Grammar bankGrammar = new Grammar(banking); + bankGrammar.Name = "Banking Menu"; + + // Load the Grammar objects to the recognizer. + recognizer.LoadGrammarAsync(bankGrammar); + + // Start asynchronous, continuous recognition. + recognizer.RecognizeAsync(); + + // Keep the console window open. + Console.ReadLine(); + } + + // Handle the RecognizeCompleted event. + static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) + { + if (e.Error != null) + { + Console.WriteLine( + "RecognizeCompleted, error occurred during recognition: {0}", e.Error); + return; + } + + if (e.InitialSilenceTimeout || e.BabbleTimeout) + { + Console.WriteLine( + "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", + e.BabbleTimeout, e.InitialSilenceTimeout); + return; + } + + if (e.InputStreamEnded) + { + Console.WriteLine( + "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", + e.AudioPosition, e.InputStreamEnded); + } + + if (e.Result != null) + { + Console.WriteLine( + "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", + e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); + } + + else + { + Console.WriteLine("RecognizeCompleted: No result."); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // Handle the LoadGrammarCompleted event. + static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) + { + string grammarName = e.Grammar.Name; + bool grammarLoaded = e.Grammar.Loaded; + bool grammarEnabled = e.Grammar.Enabled; + + if (e.Error != null) + { + Console.WriteLine("LoadGrammar for {0} failed with a {1}.", + grammarName, e.Error.GetType().Name); + + // Add exception handling code here. + } + + Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, + (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); + } + } +} + +``` + ]]> @@ -797,128 +797,128 @@ namespace SampleRecognition Gets the recognition result. The recognition result if the recognition operation succeeded; otherwise, . - object derives from and contains full information about a phrase returned by a recognition operation. - - - -## Examples - The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. - -``` -using System; -using System.Speech.Recognition; - -namespace SampleRecognition -{ - class Program - { - private static SpeechRecognitionEngine recognizer; - public static void Main(string[] args) - { - - // Initialize a SpeechRecognitionEngine object and set its input. - recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); - recognizer.SetInputToDefaultAudioDevice(); - - // Configure recognition parameters. - recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); - recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); - recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); - recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); - - // Add a handler for the LoadGrammarCompleted event. - recognizer.LoadGrammarCompleted += - new EventHandler(recognizer_LoadGrammarCompleted); - - // Add a handler for the RecognizeCompleted event. - recognizer.RecognizeCompleted += - new EventHandler(recognizer_RecognizeCompleted); - - // Create a speech recognition grammar and build it into a Grammar object. - Choices bankingMenu = new Choices(new string[] - { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); - GrammarBuilder banking = new GrammarBuilder(bankingMenu); - Grammar bankGrammar = new Grammar(banking); - bankGrammar.Name = "Banking Menu"; - - // Load the Grammar objects to the recognizer. - recognizer.LoadGrammarAsync(bankGrammar); - - // Start asynchronous, continuous recognition. - recognizer.RecognizeAsync(); - - // Keep the console window open. - Console.ReadLine(); - } - - // Handle the RecognizeCompleted event. - static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) - { - if (e.Error != null) - { - Console.WriteLine( - "RecognizeCompleted, error occurred during recognition: {0}", e.Error); - return; - } - - if (e.InitialSilenceTimeout || e.BabbleTimeout) - { - Console.WriteLine( - "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", - e.BabbleTimeout, e.InitialSilenceTimeout); - return; - } - - if (e.InputStreamEnded) - { - Console.WriteLine( - "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", - e.AudioPosition, e.InputStreamEnded); - } - - if (e.Result != null) - { - Console.WriteLine( - "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", - e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); - } - - else - { - Console.WriteLine("RecognizeCompleted: No result."); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // Handle the LoadGrammarCompleted event. - static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) - { - string grammarName = e.Grammar.Name; - bool grammarLoaded = e.Grammar.Loaded; - bool grammarEnabled = e.Grammar.Enabled; - - if (e.Error != null) - { - Console.WriteLine("LoadGrammar for {0} failed with a {1}.", - grammarName, e.Error.GetType().Name); - - // Add exception handling code here. - } - - Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, - (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); - } - } -} - -``` - + object derives from and contains full information about a phrase returned by a recognition operation. + + + +## Examples + The following example performs asynchronous speech recognition on a speech recognition grammar, using the method with the in-process recognizer. The example uses and objects to create the speech recognition grammar before building it into a object. A handler for the event outputs information about the recognition operation to the console. + +``` +using System; +using System.Speech.Recognition; + +namespace SampleRecognition +{ + class Program + { + private static SpeechRecognitionEngine recognizer; + public static void Main(string[] args) + { + + // Initialize a SpeechRecognitionEngine object and set its input. + recognizer = new SpeechRecognitionEngine(new System.Globalization.CultureInfo("en-US")); + recognizer.SetInputToDefaultAudioDevice(); + + // Configure recognition parameters. + recognizer.InitialSilenceTimeout = TimeSpan.FromSeconds(5.0); + recognizer.BabbleTimeout = TimeSpan.FromSeconds(3.0); + recognizer.EndSilenceTimeout = TimeSpan.FromSeconds(1.0); + recognizer.EndSilenceTimeoutAmbiguous = TimeSpan.FromSeconds(1.0); + + // Add a handler for the LoadGrammarCompleted event. + recognizer.LoadGrammarCompleted += + new EventHandler(recognizer_LoadGrammarCompleted); + + // Add a handler for the RecognizeCompleted event. + recognizer.RecognizeCompleted += + new EventHandler(recognizer_RecognizeCompleted); + + // Create a speech recognition grammar and build it into a Grammar object. + Choices bankingMenu = new Choices(new string[] + { "Access accounts", "Transfer funds", "Pay bills", "Get loan balance" }); + GrammarBuilder banking = new GrammarBuilder(bankingMenu); + Grammar bankGrammar = new Grammar(banking); + bankGrammar.Name = "Banking Menu"; + + // Load the Grammar objects to the recognizer. + recognizer.LoadGrammarAsync(bankGrammar); + + // Start asynchronous, continuous recognition. + recognizer.RecognizeAsync(); + + // Keep the console window open. + Console.ReadLine(); + } + + // Handle the RecognizeCompleted event. + static void recognizer_RecognizeCompleted(object sender, RecognizeCompletedEventArgs e) + { + if (e.Error != null) + { + Console.WriteLine( + "RecognizeCompleted, error occurred during recognition: {0}", e.Error); + return; + } + + if (e.InitialSilenceTimeout || e.BabbleTimeout) + { + Console.WriteLine( + "RecognizeCompleted: BabbleTimeout({0}), InitialSilenceTimeout({1}).", + e.BabbleTimeout, e.InitialSilenceTimeout); + return; + } + + if (e.InputStreamEnded) + { + Console.WriteLine( + "RecognizeCompleted: AudioPosition({0}), InputStreamEnded({1}).", + e.AudioPosition, e.InputStreamEnded); + } + + if (e.Result != null) + { + Console.WriteLine( + "RecognizeCompleted: Grammar ({0}), Text ({1}), Confidence ({2}), AudioPosition ({3}).", + e.Result.Grammar.Name, e.Result.Text, e.Result.Confidence, e.AudioPosition); + } + + else + { + Console.WriteLine("RecognizeCompleted: No result."); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // Handle the LoadGrammarCompleted event. + static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) + { + string grammarName = e.Grammar.Name; + bool grammarLoaded = e.Grammar.Loaded; + bool grammarEnabled = e.Grammar.Enabled; + + if (e.Error != null) + { + Console.WriteLine("LoadGrammar for {0} failed with a {1}.", + grammarName, e.Error.GetType().Name); + + // Add exception handling code here. + } + + Console.WriteLine("Grammar {0} {1} loaded and {2} enabled.", grammarName, + (grammarLoaded) ? "is" : "is not", (grammarEnabled) ? "is" : "is not"); + } + } +} + +``` + ]]> diff --git a/xml/System.Speech.Recognition/RecognizedAudio.xml b/xml/System.Speech.Recognition/RecognizedAudio.xml index e92f296483f..bce2b2af156 100644 --- a/xml/System.Speech.Recognition/RecognizedAudio.xml +++ b/xml/System.Speech.Recognition/RecognizedAudio.xml @@ -35,7 +35,7 @@ property or the method of the . + A speech recognizer generates information about the audio input as part of the recognition operation. To access the recognized audio, use the property or the method of the . A recognition result can be produced by the following events and methods of the and classes: @@ -62,7 +62,7 @@ - > [!IMPORTANT] -> A recognition result produced by emulated speech recognition does not contain recognized audio. For such a recognition result, its property returns `null` and its method throws an exception. For more information about emulated speech recognition, see the `EmulateRecognize` and `EmulateRecognizeAsync` methods of the and classes. +> A recognition result produced by emulated speech recognition does not contain recognized audio. For such a recognition result, its property returns `null` and its method throws an exception. For more information about emulated speech recognition, see the `EmulateRecognize` and `EmulateRecognizeAsync` methods of the and classes. @@ -135,7 +135,7 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) ## Remarks This property references the position at the beginning of the recognized phrase in the input device's generated audio stream. By contrast, the `RecognizerAudioPosition` property of the and classes reference the recognizer's position within its audio input. These positions can be different. For more information, see [Using Speech Recognition Events](https://msdn.microsoft.com/library/01c598ca-2e0e-4e89-b303-cd1cef9e8482). - The property gets the system time at the start of the recognition operation. + The property gets the system time at the start of the recognition operation. @@ -448,9 +448,9 @@ private static void TestAudio(object item) property gets the system time at the start of the recognition operation, which can be useful for latency and performance calculations. + The property gets the system time at the start of the recognition operation, which can be useful for latency and performance calculations. - The property gets the location in the input device's generated audio stream. + The property gets the location in the input device's generated audio stream. diff --git a/xml/System.Speech.Recognition/RecognizedPhrase.xml b/xml/System.Speech.Recognition/RecognizedPhrase.xml index 785ff43b754..dfd510e9b4f 100644 --- a/xml/System.Speech.Recognition/RecognizedPhrase.xml +++ b/xml/System.Speech.Recognition/RecognizedPhrase.xml @@ -41,21 +41,21 @@ ## Remarks This class contains detailed information about words and phrases processed during speech recognition operations, including the following: -- The property references the that the recognizer used to identify the input. +- The property references the that the recognizer used to identify the input. -- The property contains the normalized text for the phrase. +- The property contains the normalized text for the phrase. -- The property references the semantic information contained in the result. The semantic information is a dictionary of the key names and associated semantic data. +- The property references the semantic information contained in the result. The semantic information is a dictionary of the key names and associated semantic data. -- The property contains an ordered collection of objects that represent each recognized word in the input. Each word unit contains display format, lexical format, and pronunciation information for the corresponding word. +- The property contains an ordered collection of objects that represent each recognized word in the input. Each word unit contains display format, lexical format, and pronunciation information for the corresponding word. -- The property contains information about specialized word substitution. +- The property contains information about specialized word substitution. - The and properties contain information about recognition alternates that have the same or similar pronunciation. -- The value of the property indicates the degree of certainty, assigned by the speech recognizer, that a recognized phrase matches the input. +- The value of the property indicates the degree of certainty, assigned by the speech recognizer, that a recognized phrase matches the input. - The speech recognizer returns recognition results in a object, which inherits from . The recognition result property contains an ordered collection of objects, each of which is a possible match for the input to the recognizer. + The speech recognizer returns recognition results in a object, which inherits from . The recognition result property contains an ordered collection of objects, each of which is a possible match for the input to the recognizer. @@ -157,13 +157,13 @@ void SpeechRecognizedHandler(object sender, SpeechRecognizedEventArgs e) ## Remarks Confidence scores do not indicate the absolute likelihood that a phrase was recognized correctly. Instead, confidence scores provide a mechanism for comparing the relative accuracy of multiple recognition alternates for a given input. This facilitates returning the most accurate recognition result. For example, if a recognized phrase has a confidence score of 0.8, this does not mean that the phrase has an 80% chance of being the correct match for the input. It means that the phrase is more likely to be the correct match for the input than other results that have confidence scores less than 0.8. - A confidence score on its own is not meaningful unless you have alternative results to compare against, either from the same recognition operation or from previous recognitions of the same input. The values are used to rank alternative candidate phrases returned by the property on objects. + A confidence score on its own is not meaningful unless you have alternative results to compare against, either from the same recognition operation or from previous recognitions of the same input. The values are used to rank alternative candidate phrases returned by the property on objects. Confidence values are relative and unique to each recognition engine. Confidence values returned by two different recognition engines cannot be meaningfully compared. A speech recognition engine may assign a low confidence score to spoken input for various reasons, including background interference, inarticulate speech, or unanticipated words or word sequences. If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. Confidence thresholds for the shared recognizer, managed by , are associated with a user profile and stored in the Windows registry. Applications should not write changes to the registry for the properties of the shared recognizer. - The property of the object contains an ordered collection of objects, each of which is a possible match for the input to the recognizer. The alternates are ordered from highest to lowest confidence. + The property of the object contains an ordered collection of objects, each of which is a possible match for the input to the recognizer. The alternates are ordered from highest to lowest confidence. @@ -413,7 +413,7 @@ private string GetSemanticsSML(RecognizedPhrase result) ## Remarks As part of the speech recognition process, the speech recognizer normalizes the recognized input into a display form. - For example, the spoken input, "twenty five dollars", generates a recognition result where the property contains the words, "twenty", "five", and "dollars", and the property contains the phrase, "$25.00". For more information about text normalization, see the class. + For example, the spoken input, "twenty five dollars", generates a recognition result where the property contains the words, "twenty", "five", and "dollars", and the property contains the phrase, "$25.00". For more information about text normalization, see the class. ]]> @@ -502,7 +502,7 @@ static bool TryGetSemanticValue( ## Remarks As part of the speech recognition process, the speech recognizer performs speech-to-text normalization of the recognized input into a display form. - For example, the spoken input, "twenty five dollars", generates a recognition result where the property contains the words, "twenty", "five", and "dollars", and the property contains the phrase, "$25.00". For more information about text normalization, see . + For example, the spoken input, "twenty five dollars", generates a recognition result where the property contains the words, "twenty", "five", and "dollars", and the property contains the phrase, "$25.00". For more information about text normalization, see . ]]> @@ -536,7 +536,7 @@ static bool TryGetSemanticValue( ## Remarks This property contains the words produced from the input by the speech recognizer prior to the recognizer's speech-to-text normalization of the result. - For example, the spoken input, "twenty five dollars", generates a recognition result where the property contains the words, "twenty", "five", and "dollars", and the property contains the phrase, "$25.00". For more information about text normalization, see . + For example, the spoken input, "twenty five dollars", generates a recognition result where the property contains the words, "twenty", "five", and "dollars", and the property contains the phrase, "$25.00". For more information about text normalization, see . ]]> diff --git a/xml/System.Speech.Recognition/RecognizedWordUnit.xml b/xml/System.Speech.Recognition/RecognizedWordUnit.xml index a03ed06e4f9..9c506ca4d4b 100644 --- a/xml/System.Speech.Recognition/RecognizedWordUnit.xml +++ b/xml/System.Speech.Recognition/RecognizedWordUnit.xml @@ -41,7 +41,7 @@ ## Remarks All results returned by a recognition engine are constructed of objects. - An array of objects is accessible for any recognition operation through the property on the object. + An array of objects is accessible for any recognition operation through the property on the object. In addition to providing a measure of recognition certainty () a instance provides: @@ -49,12 +49,12 @@ - Pronunciation information using characters from a supported phonetic alphabet, such as the International Phonetic Alphabet (IPA) or the Universal Phone Set (UPS). For more information see . -- Formatting for printing. For more information see the class and its property. +- Formatting for printing. For more information see the class and its property. ## Examples - The following example shows a utility routine (`stringFromWordArray`) that generates strings. The strings contain lexical output (using ), normalized text (using ), or phonetic characters from the International Phonetic Alphabet (using ). Strings are formatted using objects obtained from the property from a of objects. The objects are obtained from the property on the object. + The following example shows a utility routine (`stringFromWordArray`) that generates strings. The strings contain lexical output (using ), normalized text (using ), or phonetic characters from the International Phonetic Alphabet (using ). Strings are formatted using objects obtained from the property from a of objects. The objects are obtained from the property on the object. ```csharp internal enum WordType @@ -170,7 +170,7 @@ internal static string stringFromWordArray(ReadOnlyCollection instances is typically used only when emulating recognition operations using the or methods of the class and the or methods of the class. - For actual applications, do not directly construct , rather obtain it through the property on the object. + For actual applications, do not directly construct , rather obtain it through the property on the object. @@ -304,14 +304,14 @@ private void _emulateAndVerify_Click(object sender, EventArgs e) object returned by the property specifies the leading and trailing spaces to be used with a given word, if any. + The object returned by the property specifies the leading and trailing spaces to be used with a given word, if any. For more information about how to use this formatting information, see the enumeration. ## Examples - The following example shows a utility routine (`stringFromWordArray`) that generates a string that is formatted in one of three ways: lexically (using ), normalized (using ), or phonetically (using ). The text output is obtained from the property on a of objects, which is obtained from the property on a object. + The following example shows a utility routine (`stringFromWordArray`) that generates a string that is formatted in one of three ways: lexically (using ), normalized (using ), or phonetically (using ). The text output is obtained from the property on a of objects, which is obtained from the property on a object. ```csharp internal enum WordType @@ -415,7 +415,7 @@ internal static string stringFromWordArray( Speech normalization is the use of special constructs or symbols to express speech in writing. For example, normalization can replace the spoken words "a dollar and sixteen cents" with "$1.16" in output text. ## Examples - The following example shows a utility routine that generates text in one of three formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. + The following example shows a utility routine that generates text in one of three formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. ```csharp internal enum WordType @@ -521,7 +521,7 @@ internal static string stringFromWordArray( ## Examples - The following example shows a utility routine that generates a string with one of three possible formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. + The following example shows a utility routine that generates a string with one of three possible formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. ```csharp internal enum WordType @@ -625,7 +625,7 @@ internal static string stringFromWordArray( Speech normalization is the use of special constructs or symbols to express speech in writing. For example, normalization can replace the spoken words "a dollar and sixteen cents" with "$1.16" in output text. ## Examples - The following example shows a utility routine that generates a string in one of three formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. + The following example shows a utility routine that generates a string in one of three formats: lexical (using ), normalized (using ), and phonetic (using ). The text output is obtained from a of objects, which is obtained from the property on the object. ```csharp internal enum WordType diff --git a/xml/System.Speech.Recognition/RecognizerInfo.xml b/xml/System.Speech.Recognition/RecognizerInfo.xml index 0f8d7656d05..c828c7909ef 100644 --- a/xml/System.Speech.Recognition/RecognizerInfo.xml +++ b/xml/System.Speech.Recognition/RecognizerInfo.xml @@ -182,7 +182,7 @@ private void recognizerInfoButton_Click(object sender, EventArgs e) ## Examples - The following example implements a button click that displays all the information in a instance. The example uses the property to obtain the identifying string for the used by the recognition engine configuration. + The following example implements a button click that displays all the information in a instance. The example uses the property to obtain the identifying string for the used by the recognition engine configuration. ```csharp private void recognizerInfoButton_Click(object sender, EventArgs e) @@ -252,7 +252,7 @@ private void recognizerInfoButton_Click(object sender, EventArgs e) instance. The example uses the property to obtain the description of a speech recognition engine configuration, and then displays it in a . + The following example below implements a button click that displays all the information in a instance. The example uses the property to obtain the description of a speech recognition engine configuration, and then displays it in a . ```csharp private void recognizerInfoButton_Click(object sender, EventArgs e) @@ -347,12 +347,12 @@ private void recognizerInfoButton_Click(object sender, EventArgs e) property is the same as the token name of the recognition engine in the Windows registry. + The identifier returned by the property is the same as the token name of the recognition engine in the Windows registry. ## Examples - The following example implements a button click that displays all the information in a instance. The example uses the property to obtain the identifier string of a recognition engine configuration, and then displays it in a . + The following example implements a button click that displays all the information in a instance. The example uses the property to obtain the identifier string of a recognition engine configuration, and then displays it in a . ```csharp private void recognizerInfoButton_Click(object sender, EventArgs e) @@ -421,7 +421,7 @@ private void recognizerInfoButton_Click(object sender, EventArgs e) instance. The example uses the property to obtain the friendly name of a recognition engine configuration, and then displays it in a . + The following example implements a button click that displays all the information in a instance. The example uses the property to obtain the friendly name of a recognition engine configuration, and then displays it in a . ```csharp private void recognizerInfoButton_Click(object sender, EventArgs e) @@ -490,7 +490,7 @@ private void recognizerInfoButton_Click(object sender, EventArgs e) instance. The example uses the property to obtain the encoding formats supported by a recognition engine configuration, and then displays it in a . + The following example implements a button click that displays all the information in a instance. The example uses the property to obtain the encoding formats supported by a recognition engine configuration, and then displays it in a . ```csharp private void recognizerInfoButton_Click(object sender, EventArgs e) diff --git a/xml/System.Speech.Recognition/RecognizerState.xml b/xml/System.Speech.Recognition/RecognizerState.xml index 21879b68c4e..5e57a722cdc 100644 --- a/xml/System.Speech.Recognition/RecognizerState.xml +++ b/xml/System.Speech.Recognition/RecognizerState.xml @@ -24,38 +24,38 @@ Enumerates values of the recognizer's state. - encapsulates the running state of the default speech recognition engine for clients using to access the Windows Desktop Speech Recognition Technology service. - - Applications can obtain the current state of the desktop recognition engine as a object by querying the property on a instance. To obtain the state of the desktop recognition engine after it changes, applications can query the property of the object passed to a handler for events. - + encapsulates the running state of the default speech recognition engine for clients using to access the Windows Desktop Speech Recognition Technology service. + + Applications can obtain the current state of the desktop recognition engine as a object by querying the property on a instance. To obtain the state of the desktop recognition engine after it changes, applications can query the property of the object passed to a handler for events. + > [!NOTE] -> instances run in-process and their running state is under the control of the application. Therefore, does not contain a property to return a object. - - The state of a desktop speech recognition server is a read-only property and cannot be controlled programmatically. Users can change a shared speech recognizer's state using the Speech Recognition user interface (UI) or through the **Speech Recognition** member of the Windows **Control Panel**. - - Both the **On** and **Sleep** settings in the Speech Recognition UI correspond to the `Listening` state. The **Off** setting in the Speech Recognition UI corresponds to Stopped. - - is the other property that affects the readiness of a shared speech recognition engine to receive and process speech input. You can use to control whether or not a shared speech recognition engine's grammars are active for recognition. However, changing the property has no effect on the property. - - Information such as the description, the supported culture and audio formats, and the recognition engine name is encapsulated in the type. - - - -## Examples - In the example below, an application displays the state of a recognizer in its implementation of a handler for the event. - -``` - -_recognizer.StateChanged += - delegate(object sender, StateChangedEventArgs eventArgs) { - _recognizerStateLabel.Text = "Speech Recognizer State: " + eventArgs.RecognizerState.ToString(); - }; - -``` - +> instances run in-process and their running state is under the control of the application. Therefore, does not contain a property to return a object. + + The state of a desktop speech recognition server is a read-only property and cannot be controlled programmatically. Users can change a shared speech recognizer's state using the Speech Recognition user interface (UI) or through the **Speech Recognition** member of the Windows **Control Panel**. + + Both the **On** and **Sleep** settings in the Speech Recognition UI correspond to the `Listening` state. The **Off** setting in the Speech Recognition UI corresponds to Stopped. + + is the other property that affects the readiness of a shared speech recognition engine to receive and process speech input. You can use to control whether or not a shared speech recognition engine's grammars are active for recognition. However, changing the property has no effect on the property. + + Information such as the description, the supported culture and audio formats, and the recognition engine name is encapsulated in the type. + + + +## Examples + In the example below, an application displays the state of a recognizer in its implementation of a handler for the event. + +``` + +_recognizer.StateChanged += + delegate(object sender, StateChangedEventArgs eventArgs) { + _recognizerStateLabel.Text = "Speech Recognizer State: " + eventArgs.RecognizerState.ToString(); + }; + +``` + ]]> diff --git a/xml/System.Speech.Recognition/ReplacementText.xml b/xml/System.Speech.Recognition/ReplacementText.xml index 835a3f16f52..3019a4beb4c 100644 --- a/xml/System.Speech.Recognition/ReplacementText.xml +++ b/xml/System.Speech.Recognition/ReplacementText.xml @@ -53,7 +53,7 @@ - The replaced text and its display attributes. For more information, see , and . - Instances of are typically obtained as members of the object returned by the property on (or classes that inherit from , such as ) when returned text has been normalized. + Instances of are typically obtained as members of the object returned by the property on (or classes that inherit from , such as ) when returned text has been normalized. diff --git a/xml/System.Speech.Recognition/SemanticResultKey.xml b/xml/System.Speech.Recognition/SemanticResultKey.xml index f37eec796d7..40d97d910e7 100644 --- a/xml/System.Speech.Recognition/SemanticResultKey.xml +++ b/xml/System.Speech.Recognition/SemanticResultKey.xml @@ -38,7 +38,7 @@ Using objects, you tag instances contained in objects and strings so that the values may readily be accessed from instances on recognition. - You can use and objects, in conjunction with and objects, to define the semantic structure for a speech recognition grammar. To access the semantic information in a recognition result, obtain an instance of through the property on . + You can use and objects, in conjunction with and objects, to define the semantic structure for a speech recognition grammar. To access the semantic information in a recognition result, obtain an instance of through the property on . ## Examples @@ -112,7 +112,7 @@ private void pwdGrammar() The grammar components can be specified either as an array of objects, or as an array of instances. - If the grammar components are used in recognition, you can access the returned using the text tag provided to the constructor of as a semantic key. The property of the instance will be determined by the grammar components used in the definition of . + If the grammar components are used in recognition, you can access the returned using the text tag provided to the constructor of as a semantic key. The property of the instance will be determined by the grammar components used in the definition of . ]]> @@ -170,7 +170,7 @@ SemanticResultKey stringTest=new SemanticResultKey( If the objects contain no defining instances of , the value of the is `null`. - If the objects provided in the `builders` parameter provide an untagged (not associated with a object) instance that is used by the recognition logic, that instance of will define the property of the that is produced. + If the objects provided in the `builders` parameter provide an untagged (not associated with a object) instance that is used by the recognition logic, that instance of will define the property of the that is produced. There should be one, and only one, untagged instance in the objects specified by the `builders` parameter. If multiple instances of untagged are associated with the , each will attempt to the set the value of the produced in the recognition result. This is not permitted, and the recognizer will generate an exception when it attempts to use a created using such a instance. diff --git a/xml/System.Speech.Recognition/SemanticResultValue.xml b/xml/System.Speech.Recognition/SemanticResultValue.xml index c2e3f3412f6..6eab75562d3 100644 --- a/xml/System.Speech.Recognition/SemanticResultValue.xml +++ b/xml/System.Speech.Recognition/SemanticResultValue.xml @@ -34,7 +34,7 @@ and objects, in conjunction with and , is the easiest way to design a semantic structure for a . Semantic information for a phrase is accessed by obtaining an instance of , through the property on . + Use of and objects, in conjunction with and , is the easiest way to design a semantic structure for a . Semantic information for a phrase is accessed by obtaining an instance of , through the property on . > [!NOTE] > Values managed by objects are defined by instances passed to their constructors. The underlying type of this must be `bool`, `int`, `float`, or `string`. Any other type will prevent construction of a instance with the . diff --git a/xml/System.Speech.Recognition/SemanticValue.xml b/xml/System.Speech.Recognition/SemanticValue.xml index b586151cfaf..ceca3b3b557 100644 --- a/xml/System.Speech.Recognition/SemanticValue.xml +++ b/xml/System.Speech.Recognition/SemanticValue.xml @@ -74,9 +74,9 @@ Each instance includes the following: -- An , accessed by means of the property, used to key the instance of the . +- An , accessed by means of the property, used to key the instance of the . -- A measure of the accuracy of semantic parsing, returned by the property. +- A measure of the accuracy of semantic parsing, returned by the property. - A collection of name/value pairs () of child objects, which are also instances. Child nodes are accessible through the implementation of using a string lookup key and a instance, as in the following example. @@ -89,13 +89,13 @@ Recognition engines based on System.Speech provide valid instances of for all output from recognition, even for phrases with no explicit semantic structure. - The instance for a phrase is obtained using the property on the object (or objects that inherit from it, such as ). + The instance for a phrase is obtained using the property on the object (or objects that inherit from it, such as ). objects obtained for recognized phrases without semantic structure are characterized by: - The lack of children ( is 0). -- The property is `null`. +- The property is `null`. - An artificial semantic confidence level of 1.0 (returned by ). @@ -263,9 +263,9 @@ newGrammar.SpeechRecognized += ## Remarks There are no restrictions on the type of `value` to be stored. - An application can retrieve `value` by using the property on a instance. + An application can retrieve `value` by using the property on a instance. - The value of the property for the instance will be set to -1. + The value of the property for the instance will be set to -1. A constructed with this method cannot be referenced by key name. @@ -303,9 +303,9 @@ newGrammar.SpeechRecognized += ## Remarks There are no restrictions on the type of `value` to be stored. - An application can retrieve `value` by using the property on a instance. + An application can retrieve `value` by using the property on a instance. - The `confidence` parameter (returned by the property on a instance), should be between 0.0 and 1.0. + The `confidence` parameter (returned by the property on a instance), should be between 0.0 and 1.0. ]]> @@ -341,7 +341,7 @@ newGrammar.SpeechRecognized += property, which returns a measure of the correctness of semantic parsing, should not be confused with the property, which returns a measure of the accuracy of speech recognition. + The property, which returns a measure of the correctness of semantic parsing, should not be confused with the property, which returns a measure of the accuracy of speech recognition. @@ -793,12 +793,12 @@ newGrammar.SpeechRecognized += You can only access data by key value at run-time, not at compile-time, for example to check `semantic["myKey"].Value`. Specifying a key that is not present generates an exception. - To detect the presence of a given key, use the property on an instance. + To detect the presence of a given key, use the property on an instance. ## Examples The following example shows a handler for a event designed to handle commands to change foreground and background color. - After handling recognized phrases that have no semantic structure, the handler checks for the presence of appropriate keys using (`applyChgToBackground`, `colorRGBValueList`, or `colorStringList)`, and then uses the property to obtain the nodes with needed information. + After handling recognized phrases that have no semantic structure, the handler checks for the presence of appropriate keys using (`applyChgToBackground`, `colorRGBValueList`, or `colorStringList)`, and then uses the property to obtain the nodes with needed information. The use of is highlighted below. @@ -1286,7 +1286,7 @@ This member is an explicit interface member implementation. It can be used only of `null` and a property of zero. + Recognition results which do not make use of semantic parsing always have a of `null` and a property of zero. diff --git a/xml/System.Speech.Recognition/SpeechHypothesizedEventArgs.xml b/xml/System.Speech.Recognition/SpeechHypothesizedEventArgs.xml index 1c35cd00ce1..1594f2aaef1 100644 --- a/xml/System.Speech.Recognition/SpeechHypothesizedEventArgs.xml +++ b/xml/System.Speech.Recognition/SpeechHypothesizedEventArgs.xml @@ -30,38 +30,38 @@ - Returns notification from or events. - + Returns notification from or events. + This class supports the .NET Framework infrastructure and is not intended to be used directly from application code. - and classes. - - You can obtain detailed information about a tentatively recognized phrase by using the property. - - Numerous `SpeechHypothesized` events are generated as a recognition engine attempts to identify an input phrase. Typically, handling these events is useful only for debugging. - - `SpeechHypothesizedEventArgs` derives from . - - - -## Examples - The example below creates a handler for or events. The handler uses an instance of `SpeechHypothesizedEventArgs` to return and display information about a tentatively recognized phrase. - -``` -// Create a handler for the SpeechHypothesized event. -recognizer.SpeechHypothesized += new EventHandler(recognizer_SpeechHypothesized); - -// Handle the event and display the hypothesized result. -void recognizer_SpeechHypothesized (object sender, SpeechHypothesizedEventArgs e) - { - Console.WriteLine("Hypothesized text: " + e.Result.Text); - } - -``` - + and classes. + + You can obtain detailed information about a tentatively recognized phrase by using the property. + + Numerous `SpeechHypothesized` events are generated as a recognition engine attempts to identify an input phrase. Typically, handling these events is useful only for debugging. + + `SpeechHypothesizedEventArgs` derives from . + + + +## Examples + The example below creates a handler for or events. The handler uses an instance of `SpeechHypothesizedEventArgs` to return and display information about a tentatively recognized phrase. + +``` +// Create a handler for the SpeechHypothesized event. +recognizer.SpeechHypothesized += new EventHandler(recognizer_SpeechHypothesized); + +// Handle the event and display the hypothesized result. +void recognizer_SpeechHypothesized (object sender, SpeechHypothesizedEventArgs e) + { + Console.WriteLine("Hypothesized text: " + e.Result.Text); + } + +``` + ]]> diff --git a/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml b/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml index 8ef1caec14c..e8e41d6125f 100644 --- a/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml +++ b/xml/System.Speech.Recognition/SpeechRecognitionEngine.xml @@ -38,7 +38,7 @@ - To create an in-process speech recognizer, use one of the constructors. -- To manage speech recognition grammars, use the , , , and methods, and the property. +- To manage speech recognition grammars, use the , , , and methods, and the property. - To configure the input to the recognizer, use the , , , , or method. @@ -46,7 +46,7 @@ - To modify how recognition handles silence or unexpected input, use the , , , and properties. -- To change the number of alternates the recognizer returns, use the property. The recognizer returns recognition results in a object. +- To change the number of alternates the recognizer returns, use the property. The recognizer returns recognition results in a object. - To synchronize changes to the recognizer, use the method. The recognizer uses more than one thread to perform tasks. @@ -450,7 +450,7 @@ namespace SpeechRecognitionApp property of the object returned by the property of the recognizer. To get a collection of all the installed recognizers, use the static method. + The token name of the recognizer is the value of the property of the object returned by the property of the recognizer. To get a collection of all the installed recognizers, use the static method. Before the speech recognizer can begin recognition, you must load at least one speech recognition grammar and configure the input for the recognizer. @@ -654,7 +654,7 @@ static void DisplayAudioDeviceFormat(Label label, SpeechRecognitionEngine recogn ## Remarks The raises this event multiple times per second. The frequency with which the event is raised depends on the computer on which the application is running. - To get the audio level at the time of the event, use the property of the associated . To get the current audio level of the input to the recognizer, use the recognizer's property. + To get the audio level at the time of the event, use the property of the associated . To get the current audio level of the input to the recognizer, use the recognizer's property. When you create an delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -716,7 +716,7 @@ void recognizer_AudioLevelUpdated(object sender, AudioLevelUpdatedEventArgs e) property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position within its audio input. These positions can be different. For example, if the recognizer has received input for which it has not yet generated a recognition result then the value of the property is less than the value of the property. + The property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position within its audio input. These positions can be different. For example, if the recognizer has received input for which it has not yet generated a recognition result then the value of the property is less than the value of the property. @@ -822,7 +822,7 @@ namespace SampleRecognition property of the associated . + To get which problem occurred, use the property of the associated . When you create an delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -893,7 +893,7 @@ void recognizer_AudioSignalProblemOccurred(object sender, AudioSignalProblemOccu property represents the audio state with a member of the enumeration. + The property represents the audio state with a member of the enumeration. ]]> @@ -925,7 +925,7 @@ void recognizer_AudioSignalProblemOccurred(object sender, AudioSignalProblemOccu property of the associated . To get the current audio state of the input to the recognizer, use the recognizer's property. For more information about audio state, see the enumeration. + To get the audio state at the time of the event, use the property of the associated . To get the current audio state of the input to the recognizer, use the recognizer's property. For more information about audio state, see the enumeration. When you create an delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -1052,7 +1052,7 @@ namespace SampleRecognition ## Remarks Each speech recognizer has an algorithm to distinguish between silence and speech. The recognizer classifies as background noise any non-silence input that does not match the initial rule of any of the recognizer's loaded and enabled speech recognition grammars. If the recognizer receives only background noise and silence within the babble timeout interval, then the recognizer finalizes that recognition operation. -- For asynchronous recognition operations, the recognizer raises the event, where the property is `true`, and the property is `null`. +- For asynchronous recognition operations, the recognizer raises the event, where the property is `true`, and the property is `null`. - For synchronous recognition operations and emulation, the recognizer returns `null`, instead of a valid . @@ -1260,7 +1260,7 @@ namespace SpeechRecognitionApp The speech recognizer raises the , , , and events as if the recognition operation is not emulated. The recognizer ignores new lines and extra white space and treats punctuation as literal input. > [!NOTE] -> The object generated by the speech recognizer in response to emulated input has a value of `null` for its property. +> The object generated by the speech recognizer in response to emulated input has a value of `null` for its property. To emulate asynchronous recognition, use the method. @@ -1621,7 +1621,7 @@ namespace Sre_EmulateRecognize The speech recognizer raises the , , , and events as if the recognition operation is not emulated. When the recognizer completes the asynchronous recognition operation, it raises the event. The recognizer ignores new lines and extra white space and treats punctuation as literal input. > [!NOTE] -> The object generated by the speech recognizer in response to emulated input has a value of `null` for its property. +> The object generated by the speech recognizer in response to emulated input has a value of `null` for its property. To emulate synchronous recognition, use the method. @@ -2039,9 +2039,9 @@ namespace SreEmulateRecognizeAsync If emulated recognition was successful, you can access the recognition result using the either of the following: -- The property in the object in the handler for the event. +- The property in the object in the handler for the event. -- property in the object in the handler for the event. +- property in the object in the handler for the event. If emulated recognition was not successful, the event is not raised and the will be null. @@ -2196,7 +2196,7 @@ namespace InProcessRecognizer This property determines how long the speech recognition engine will wait for additional input before finalizing a recognition operation. The timeout interval can be from 0 seconds to 10 seconds, inclusive. The default is 150 milliseconds. - To set the timeout interval for ambiguous input, use the property. + To set the timeout interval for ambiguous input, use the property. ]]> @@ -2244,7 +2244,7 @@ namespace InProcessRecognizer This property determines how long the speech recognition engine will wait for additional input before finalizing a recognition operation. The timeout interval can be from 0 seconds to 10 seconds, inclusive. The default is 500 milliseconds. - To set the timeout interval for unambiguous input, use the property. + To set the timeout interval for unambiguous input, use the property. ]]> @@ -2340,7 +2340,7 @@ private static void ListGrammars(SpeechRecognitionEngine recognizer) ## Remarks Each speech recognizer has an algorithm to distinguish between silence and speech. If the recognizer input is silence during the initial silence timeout period, then the recognizer finalizes that recognition operation. -- For asynchronous recognition operations and emulation, the recognizer raises the event, where the property is `true`, and the property is `null`. +- For asynchronous recognition operations and emulation, the recognizer raises the event, where the property is `true`, and the property is `null`. - For synchronous recognition operations and emulation, the recognizer returns `null`, instead of a valid . @@ -2495,7 +2495,7 @@ namespace SpeechRecognitionApp property. + To get information about the current recognizer, use the property. @@ -2597,7 +2597,7 @@ namespace SpeechRecognitionApp If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. - When you load a grammar, it is enabled by default. To disable a loaded grammar, use the property. + When you load a grammar, it is enabled by default. To disable a loaded grammar, use the property. To load a object asynchronously, use the method. @@ -2698,7 +2698,7 @@ namespace SpeechRecognitionApp If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. - When you load a grammar, it is enabled by default. To disable a loaded grammar, use the property. + When you load a grammar, it is enabled by default. To disable a loaded grammar, use the property. To load a speech recognition grammar synchronously, use the method. @@ -2742,7 +2742,7 @@ namespace SpeechRecognitionApp method initiates an asynchronous operation. The raises this event when it completes the operation. To get the object that the recognizer loaded, use the property of the associated . To get the current objects the recognizer has loaded, use the recognizer's property. + The recognizer's method initiates an asynchronous operation. The raises this event when it completes the operation. To get the object that the recognizer loaded, use the property of the associated . To get the current objects the recognizer has loaded, use the recognizer's property. If the recognizer is running, applications must use to pause the speech recognition engine before loading, unloading, enabling, or disabling a grammar. @@ -2873,7 +2873,7 @@ namespace SampleRecognition property of the class contains the collection of objects that represent possible interpretations of the input. + The property of the class contains the collection of objects that represent possible interpretations of the input. The default value for is 10. @@ -2920,8 +2920,8 @@ namespace SampleRecognition |Name|Description| |----------|-----------------| |`ResourceUsage`|Specifies the recognizer's CPU consumption. The range is from 0 to 100. The default value is 50.| -|`ResponseSpeed`|Indicates the length of silence at the end of unambiguous input before the speech recognizer completes a recognition operation. The range is from 0 to 10,000 milliseconds (ms). This setting corresponds to the recognizer's property. Default = 150ms.| -|`ComplexResponseSpeed`|Indicates the length of silence at the end of ambiguous input before the speech recognizer completes a recognition operation. The range is from 0 to 10,000ms. This setting corresponds to the recognizer's property. Default = 500ms.| +|`ResponseSpeed`|Indicates the length of silence at the end of unambiguous input before the speech recognizer completes a recognition operation. The range is from 0 to 10,000 milliseconds (ms). This setting corresponds to the recognizer's property. Default = 150ms.| +|`ComplexResponseSpeed`|Indicates the length of silence at the end of ambiguous input before the speech recognizer completes a recognition operation. The range is from 0 to 10,000ms. This setting corresponds to the recognizer's property. Default = 500ms.| |`AdaptationOn`|Indicates whether adaptation of the acoustic model is ON (value = `1`) or OFF (value = `0`). The default value is `1` (ON).| |`PersistedBackgroundAdaptation`|Indicates whether background adaptation is ON (value = `1`) or OFF (value = `0`), and persists the setting in the registry. The default value is `1` (ON).| @@ -3189,7 +3189,7 @@ namespace SynchronousRecognition performs a single recognition operation and then terminates. The `initialSilenceTimeout` parameter supersedes the recognizer's property. + If the speech recognition engine detects speech within the time interval specified by `initialSilenceTimeout` argument, performs a single recognition operation and then terminates. The `initialSilenceTimeout` parameter supersedes the recognizer's property. During a call to this method, the recognizer can raise the following events: @@ -3296,7 +3296,7 @@ namespace SynchronousRecognition - . Raised when a operation finishes. - To retrieve the result of an asynchronous recognition operation, attach an event handler to the recognizer's event. The recognizer raises this event whenever it successfully completes a synchronous or asynchronous recognition operation. If recognition was not successful, the property on object, which you can access in the handler for the event, will be `null`. + To retrieve the result of an asynchronous recognition operation, attach an event handler to the recognizer's event. The recognizer raises this event whenever it successfully completes a synchronous or asynchronous recognition operation. If recognition was not successful, the property on object, which you can access in the handler for the event, will be `null`. An asynchronous recognition operation can fail for the following reasons: @@ -3356,7 +3356,7 @@ namespace SynchronousRecognition - . Raised when a operation finishes. - To retrieve the result of an asynchronous recognition operation, attach an event handler to the recognizer's event. The recognizer raises this event whenever it successfully completes a synchronous or asynchronous recognition operation. If recognition was not successful, the property on object, which you can access in the handler for the event, will be `null`. + To retrieve the result of an asynchronous recognition operation, attach an event handler to the recognizer's event. The recognizer raises this event whenever it successfully completes a synchronous or asynchronous recognition operation. If recognition was not successful, the property on object, which you can access in the handler for the event, will be `null`. To perform synchronous recognition, use one of the methods. @@ -3604,7 +3604,7 @@ namespace AsynchronousRecognition - . Raised when a operation finishes. - To retrieve the result of an asynchronous recognition operation, attach an event handler to the recognizer's event. The recognizer raises this event whenever it successfully completes a synchronous or asynchronous recognition operation. If recognition was not successful, the property on object, which you can access in the handler for the event, will be `null`. + To retrieve the result of an asynchronous recognition operation, attach an event handler to the recognizer's event. The recognizer raises this event whenever it successfully completes a synchronous or asynchronous recognition operation. If recognition was not successful, the property on object, which you can access in the handler for the event, will be `null`. An asynchronous recognition operation can fail for the following reasons: @@ -3847,7 +3847,7 @@ namespace AsynchronousRecognition or event when an asynchronous operation is canceled, and sets the property of the to `true`. This method cancels asynchronous operations initiated by the and methods. + This method immediately finalizes asynchronous recognition. If the current asynchronous recognition operation is receiving input, the input is truncated and the operation completes with the existing input. The recognizer raises the or event when an asynchronous operation is canceled, and sets the property of the to `true`. This method cancels asynchronous operations initiated by the and methods. To stop asynchronous recognition without truncating the input, use the method. @@ -4073,7 +4073,7 @@ namespace AsynchronousRecognition or event when an asynchronous operation is stopped, and sets the property of the to `true`. This method stops asynchronous operations initiated by the and methods. + This method finalizes asynchronous recognition without truncating input. If the current asynchronous recognition operation is receiving input, the recognizer continues accepting input until the current recognition operation is completed. The recognizer raises the or event when an asynchronous operation is stopped, and sets the property of the to `true`. This method stops asynchronous operations initiated by the and methods. To immediately cancel asynchronous recognition with only the existing input, use the method. @@ -4455,7 +4455,7 @@ namespace SampleRecognition ## Remarks The audio position is specific to each speech recognizer. The zero value of an input stream is established when it is enabled. - The property references the object's position within its audio input. By contrast, the property references the input device's position in its generated audio stream. These positions can be different. For example, if the recognizer has received input for which it has not yet generated a recognition result then the value of the property is less than the value of the property. + The property references the object's position within its audio input. By contrast, the property references the input device's position in its generated audio stream. These positions can be different. For example, if the recognizer has received input for which it has not yet generated a recognition result then the value of the property is less than the value of the property. ]]> @@ -4700,9 +4700,9 @@ namespace SampleRecognition While the recognizer is handling the event: -- The recognizer does not process input, and the value of the property remains the same. +- The recognizer does not process input, and the value of the property remains the same. -- The recognizer continues to collect input, and the value of the property can change. +- The recognizer continues to collect input, and the value of the property can change. ]]> @@ -4732,7 +4732,7 @@ namespace SampleRecognition event, the property of the is `null`. + When the recognizer generates the event, the property of the is `null`. To provide a user token, use the or method. To specify an audio position offset, use the method. @@ -4879,7 +4879,7 @@ namespace SampleRecognition event, the property of the contains the value of the `userToken` parameter. + When the recognizer generates the event, the property of the contains the value of the `userToken` parameter. To specify an audio position offset, use the method. @@ -4921,7 +4921,7 @@ namespace SampleRecognition ## Remarks The recognizer does not initiate the recognizer update request until the recognizer's equals the current plus `audioPositionAheadToRaiseUpdate`. - When the recognizer generates the event, the property of the contains the value of the `userToken` parameter. + When the recognizer generates the event, the property of the contains the value of the `userToken` parameter. ]]> @@ -5435,7 +5435,7 @@ recognizer.SetInputToWaveFile(@"c:\temp\SampleWAVInput.wav"); performs a speech recognition operation, it raises the event when its algorithm identifies the input as speech. The property of the associated object indicates location in the input stream where the recognizer detected speech. The raises the event before it raises any of the , , or events. + Each speech recognizer has an algorithm to distinguish between silence and speech. When the performs a speech recognition operation, it raises the event when its algorithm identifies the input as speech. The property of the associated object indicates location in the input stream where the recognizer detected speech. The raises the event before it raises any of the , , or events. For more information see the , , , and methods. @@ -5553,11 +5553,11 @@ namespace SampleRecognition generates numerous events as it attempts to identify an input phrase. You can access the text of partially recognized phrases in the property of the object in the handler for the event. Typically, handling these events is useful only for debugging. + The generates numerous events as it attempts to identify an input phrase. You can access the text of partially recognized phrases in the property of the object in the handler for the event. Typically, handling these events is useful only for debugging. derives from . - For more information see the property and the , , , and methods. + For more information see the property and the , , , and methods. When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -5684,7 +5684,7 @@ namespace SampleRecognition objects. The property of the contains the rejected object. You can use the handler for the event to retrieve recognition that were rejected and their scores. + The recognizer raises this event if it determines that input does not match with sufficient confidence any of its loaded and enabled objects. The property of the contains the rejected object. You can use the handler for the event to retrieve recognition that were rejected and their scores. If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. You can modify how the speech recognition responds to non-speech input using the , , , and properties. @@ -5815,7 +5815,7 @@ namespace SampleRecognition or methods. The recognizer raises the event if it determines that input matches one of its loaded objects with a sufficient level of confidence to constitute recognition. The property of the contains the accepted object. Handlers of events can obtain the recognized phrase as well as a list of recognition with lower confidence scores. + You can initiate a recognition operation using the one of the or methods. The recognizer raises the event if it determines that input matches one of its loaded objects with a sufficient level of confidence to constitute recognition. The property of the contains the accepted object. Handlers of events can obtain the recognized phrase as well as a list of recognition with lower confidence scores. If your application is using a instance, you can modify the confidence level at which speech input is accepted or rejected with one of the methods. You can modify how the speech recognition responds to non-speech input using the , , , and properties. @@ -6207,8 +6207,8 @@ namespace UnloadGrammars |Name|Description| |----------|-----------------| |`ResourceUsage`|Specifies the recognizer's CPU consumption. The range is from 0 to 100. The default value is 50.| -|`ResponseSpeed`|Indicates the length of silence at the end of unambiguous input before the speech recognizer completes a recognition operation. The range is from 0 to 10,000 milliseconds (ms). This setting corresponds to the recognizer's property. Default = 150ms.| -|`ComplexResponseSpeed`|Indicates the length of silence in milliseconds (ms) at the end of ambiguous input before the speech recognizer completes a recognition operation. The range is from 0 to 10,000ms. This setting corresponds to the recognizer's property. Default = 500ms.| +|`ResponseSpeed`|Indicates the length of silence at the end of unambiguous input before the speech recognizer completes a recognition operation. The range is from 0 to 10,000 milliseconds (ms). This setting corresponds to the recognizer's property. Default = 150ms.| +|`ComplexResponseSpeed`|Indicates the length of silence in milliseconds (ms) at the end of ambiguous input before the speech recognizer completes a recognition operation. The range is from 0 to 10,000ms. This setting corresponds to the recognizer's property. Default = 500ms.| |`AdaptationOn`|Indicates whether adaptation of the acoustic model is ON (value = `1`) or OFF (value = `0`). The default value is `1` (ON).| |`PersistedBackgroundAdaptation`|Indicates whether background adaptation is ON (value = `1`) or OFF (value = `0`), and persists the setting in the registry. The default value is `1` (ON).| diff --git a/xml/System.Speech.Recognition/SpeechRecognitionRejectedEventArgs.xml b/xml/System.Speech.Recognition/SpeechRecognitionRejectedEventArgs.xml index 9cdc996cd72..3e3bdef68ac 100644 --- a/xml/System.Speech.Recognition/SpeechRecognitionRejectedEventArgs.xml +++ b/xml/System.Speech.Recognition/SpeechRecognitionRejectedEventArgs.xml @@ -32,97 +32,97 @@ Provides information for the and events. - and classes. - - **SpeechRecognitionRejected** events are generated by a speech recognition engine when none of the alternates from a recognition operation have a high enough confidence score to be accepted. Detailed information about rejected phrases is available through the property. - - **SpeechRecognitionRejectedEventArgs** derives from . - - - -## Examples - The following example recognizes phrases such as "Display the list of artists in the jazz category" or "Display albums gospel". The example uses a handler for the event to display a notification in the console when the speech input cannot be matched to the contents of the grammar with sufficient confidence to produce a successful recognition. - -``` -using System; -using System.Speech.Recognition; - -namespace SampleRecognition -{ - class Program - { - static void Main(string[] args) - - // Initialize a shared speech recognition engine. - { - using (SpeechRecognizer recognizer = - new SpeechRecognizer()) - { - - // Create a grammar. - // Create lists of alternative choices. - Choices listTypes = new Choices(new string[] { "albums", "artists" }); - Choices genres = new Choices(new string[] { - "blues", "classical", "gospel", "jazz", "rock" }); - - // Create a GrammarBuilder object and assemble the grammar components. - GrammarBuilder mediaMenu = new GrammarBuilder("Display"); - mediaMenu.Append("the list of", 0, 1); - mediaMenu.Append(listTypes); - mediaMenu.Append("in the", 0, 1); - mediaMenu.Append(genres); - mediaMenu.Append("category", 0, 1); - - // Build a Grammar object from the GrammarBuilder. - Grammar mediaMenuGrammar = new Grammar(mediaMenu); - mediaMenuGrammar.Name = "Media Chooser"; - - // Attach event handlers. - recognizer.LoadGrammarCompleted += - new EventHandler(recognizer_LoadGrammarCompleted); - recognizer.SpeechRecognized += - new EventHandler(recognizer_SpeechRecognized); - recognizer.SpeechRecognitionRejected += - new EventHandler(recognizer_SpeechRecognitionRejected); - - // Load the grammar object to the recognizer. - recognizer.LoadGrammarAsync(mediaMenuGrammar); - - // Keep the console window open. - Console.ReadLine(); - } - } - - // Handle the SpeechRecognitionRejected event. - static void recognizer_SpeechRecognitionRejected(object sender, SpeechRecognitionRejectedEventArgs e) - { - Console.WriteLine("Speech input was rejected."); - foreach (RecognizedPhrase phrase in e.Result.Alternates) - { - Console.WriteLine(" Rejected phrase: " + phrase.Text); - Console.WriteLine(" Confidence score: " + phrase.Confidence); - } - } - - // Handle the LoadGrammarCompleted event. - static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) - { - Console.WriteLine("Grammar loaded: " + e.Grammar.Name); - } - - // Handle the SpeechRecognized event. - static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine("Speech recognized: " + e.Result.Text); - } - } -} - -``` - + and classes. + + **SpeechRecognitionRejected** events are generated by a speech recognition engine when none of the alternates from a recognition operation have a high enough confidence score to be accepted. Detailed information about rejected phrases is available through the property. + + **SpeechRecognitionRejectedEventArgs** derives from . + + + +## Examples + The following example recognizes phrases such as "Display the list of artists in the jazz category" or "Display albums gospel". The example uses a handler for the event to display a notification in the console when the speech input cannot be matched to the contents of the grammar with sufficient confidence to produce a successful recognition. + +``` +using System; +using System.Speech.Recognition; + +namespace SampleRecognition +{ + class Program + { + static void Main(string[] args) + + // Initialize a shared speech recognition engine. + { + using (SpeechRecognizer recognizer = + new SpeechRecognizer()) + { + + // Create a grammar. + // Create lists of alternative choices. + Choices listTypes = new Choices(new string[] { "albums", "artists" }); + Choices genres = new Choices(new string[] { + "blues", "classical", "gospel", "jazz", "rock" }); + + // Create a GrammarBuilder object and assemble the grammar components. + GrammarBuilder mediaMenu = new GrammarBuilder("Display"); + mediaMenu.Append("the list of", 0, 1); + mediaMenu.Append(listTypes); + mediaMenu.Append("in the", 0, 1); + mediaMenu.Append(genres); + mediaMenu.Append("category", 0, 1); + + // Build a Grammar object from the GrammarBuilder. + Grammar mediaMenuGrammar = new Grammar(mediaMenu); + mediaMenuGrammar.Name = "Media Chooser"; + + // Attach event handlers. + recognizer.LoadGrammarCompleted += + new EventHandler(recognizer_LoadGrammarCompleted); + recognizer.SpeechRecognized += + new EventHandler(recognizer_SpeechRecognized); + recognizer.SpeechRecognitionRejected += + new EventHandler(recognizer_SpeechRecognitionRejected); + + // Load the grammar object to the recognizer. + recognizer.LoadGrammarAsync(mediaMenuGrammar); + + // Keep the console window open. + Console.ReadLine(); + } + } + + // Handle the SpeechRecognitionRejected event. + static void recognizer_SpeechRecognitionRejected(object sender, SpeechRecognitionRejectedEventArgs e) + { + Console.WriteLine("Speech input was rejected."); + foreach (RecognizedPhrase phrase in e.Result.Alternates) + { + Console.WriteLine(" Rejected phrase: " + phrase.Text); + Console.WriteLine(" Confidence score: " + phrase.Confidence); + } + } + + // Handle the LoadGrammarCompleted event. + static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) + { + Console.WriteLine("Grammar loaded: " + e.Grammar.Name); + } + + // Handle the SpeechRecognized event. + static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine("Speech recognized: " + e.Result.Text); + } + } +} + +``` + ]]> diff --git a/xml/System.Speech.Recognition/SpeechRecognizedEventArgs.xml b/xml/System.Speech.Recognition/SpeechRecognizedEventArgs.xml index 1463561f539..287aedbed7b 100644 --- a/xml/System.Speech.Recognition/SpeechRecognizedEventArgs.xml +++ b/xml/System.Speech.Recognition/SpeechRecognizedEventArgs.xml @@ -32,98 +32,98 @@ Provides information for the , , and events. - , and classes. - - `SpeechRecognized` events are generated when one or more of the alternates from a recognition operation have a high enough confidence score to be accepted. To obtain detailed information about a recognized phrase, access the property in the handler for the event. - - `SpeechRecognizedEventArgs` derives from the class. - - - -## Examples - The following example is part of a console application that loads a speech recognition grammar and demonstrates speech input to the shared recognizer, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. - - Spoken input such as "I want to fly from Chicago to Miami" will trigger a event. Speaking the phrase "Fly me from Houston to Chicago " will not trigger a event. - - The example uses a handler for the event to display successfully recognized phrases and the semantics they contain in the console. - -```csharp -using System; -using System.Speech.Recognition; - -namespace SampleRecognition -{ - class Program - { - static void Main(string[] args) - - // Initialize a shared speech recognition engine. - { - using (SpeechRecognizer recognizer = new SpeechRecognizer()) - { - - // Create SemanticResultValue objects that contain cities and airport codes. - SemanticResultValue chicago = new SemanticResultValue("Chicago", "ORD"); - SemanticResultValue boston = new SemanticResultValue("Boston", "BOS"); - SemanticResultValue miami = new SemanticResultValue("Miami", "MIA"); - SemanticResultValue dallas = new SemanticResultValue("Dallas", "DFW"); - - // Create a Choices object and add the SemanticResultValue objects, using - // implicit conversion from SemanticResultValue to GrammarBuilder - Choices cities = new Choices(); - cities.Add(new Choices(new GrammarBuilder[] { chicago, boston, miami, dallas })); - - // Build the phrase and add SemanticResultKeys. - GrammarBuilder chooseCities = new GrammarBuilder(); - chooseCities.Append("I want to fly from"); - chooseCities.Append(new SemanticResultKey("origin", cities)); - chooseCities.Append("to"); - chooseCities.Append(new SemanticResultKey("destination", cities)); - - // Build a Grammar object from the GrammarBuilder. - Grammar bookFlight = new Grammar(chooseCities); - bookFlight.Name = "Book Flight"; - - // Add a handler for the LoadGrammarCompleted event. - recognizer.LoadGrammarCompleted += - new EventHandler(recognizer_LoadGrammarCompleted); - - // Add a handler for the SpeechRecognized event. - recognizer.SpeechRecognized += - new EventHandler(recognizer_SpeechRecognized); - - // Load the grammar object to the recognizer. - recognizer.LoadGrammarAsync(bookFlight); - - // Keep the console window open. - Console.ReadLine(); - } - } - - // Handle the LoadGrammarCompleted event. - static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) - { - Console.WriteLine("Grammar loaded: " + e.Grammar.Name); - Console.WriteLine(); - } - - // Handle the SpeechRecognized event. - static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine("Speech recognized: " + e.Result.Text); - Console.WriteLine(); - Console.WriteLine("Semantic results:"); - Console.WriteLine(" The flight origin is " + e.Result.Semantics["origin"].Value); - Console.WriteLine(" The flight destination is " + e.Result.Semantics["destination"].Value); - } - } -} - -``` - + , and classes. + + `SpeechRecognized` events are generated when one or more of the alternates from a recognition operation have a high enough confidence score to be accepted. To obtain detailed information about a recognized phrase, access the property in the handler for the event. + + `SpeechRecognizedEventArgs` derives from the class. + + + +## Examples + The following example is part of a console application that loads a speech recognition grammar and demonstrates speech input to the shared recognizer, the associated recognition results, and the associated events raised by the speech recognizer. If Windows Speech Recognition is not running, then starting this application will also start Windows Speech Recognition. + + Spoken input such as "I want to fly from Chicago to Miami" will trigger a event. Speaking the phrase "Fly me from Houston to Chicago " will not trigger a event. + + The example uses a handler for the event to display successfully recognized phrases and the semantics they contain in the console. + +```csharp +using System; +using System.Speech.Recognition; + +namespace SampleRecognition +{ + class Program + { + static void Main(string[] args) + + // Initialize a shared speech recognition engine. + { + using (SpeechRecognizer recognizer = new SpeechRecognizer()) + { + + // Create SemanticResultValue objects that contain cities and airport codes. + SemanticResultValue chicago = new SemanticResultValue("Chicago", "ORD"); + SemanticResultValue boston = new SemanticResultValue("Boston", "BOS"); + SemanticResultValue miami = new SemanticResultValue("Miami", "MIA"); + SemanticResultValue dallas = new SemanticResultValue("Dallas", "DFW"); + + // Create a Choices object and add the SemanticResultValue objects, using + // implicit conversion from SemanticResultValue to GrammarBuilder + Choices cities = new Choices(); + cities.Add(new Choices(new GrammarBuilder[] { chicago, boston, miami, dallas })); + + // Build the phrase and add SemanticResultKeys. + GrammarBuilder chooseCities = new GrammarBuilder(); + chooseCities.Append("I want to fly from"); + chooseCities.Append(new SemanticResultKey("origin", cities)); + chooseCities.Append("to"); + chooseCities.Append(new SemanticResultKey("destination", cities)); + + // Build a Grammar object from the GrammarBuilder. + Grammar bookFlight = new Grammar(chooseCities); + bookFlight.Name = "Book Flight"; + + // Add a handler for the LoadGrammarCompleted event. + recognizer.LoadGrammarCompleted += + new EventHandler(recognizer_LoadGrammarCompleted); + + // Add a handler for the SpeechRecognized event. + recognizer.SpeechRecognized += + new EventHandler(recognizer_SpeechRecognized); + + // Load the grammar object to the recognizer. + recognizer.LoadGrammarAsync(bookFlight); + + // Keep the console window open. + Console.ReadLine(); + } + } + + // Handle the LoadGrammarCompleted event. + static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) + { + Console.WriteLine("Grammar loaded: " + e.Grammar.Name); + Console.WriteLine(); + } + + // Handle the SpeechRecognized event. + static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine("Speech recognized: " + e.Result.Text); + Console.WriteLine(); + Console.WriteLine("Semantic results:"); + Console.WriteLine(" The flight origin is " + e.Result.Semantics["origin"].Value); + Console.WriteLine(" The flight destination is " + e.Result.Semantics["destination"].Value); + } + } +} + +``` + ]]> diff --git a/xml/System.Speech.Recognition/SpeechRecognizer.xml b/xml/System.Speech.Recognition/SpeechRecognizer.xml index 0c81d4d0e62..b7c1fd5f37b 100644 --- a/xml/System.Speech.Recognition/SpeechRecognizer.xml +++ b/xml/System.Speech.Recognition/SpeechRecognizer.xml @@ -40,7 +40,7 @@ - To get information about current speech recognition operations, subscribe to the 's , , , and events. -- To view or modify the number of alternate results the recognizer returns, use the property. The recognizer returns recognition results in a object. +- To view or modify the number of alternate results the recognizer returns, use the property. The recognizer returns recognition results in a object. - To access or monitor the state of the shared recognizer, use the , , , , , , and properties and the , , , and events. @@ -366,7 +366,7 @@ namespace SharedRecognizer ## Remarks The recognizer raises this event multiple times per second. The frequency with which the event is raised depends on the computer on which the application is running. - To get the audio level at the time of the event, use the property of the associated . To get the current audio level of the input to the recognizer, use the recognizer's property. + To get the audio level at the time of the event, use the property of the associated . To get the current audio level of the input to the recognizer, use the recognizer's property. When you create a delegate for an `AudioLevelUpdated` event, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -430,7 +430,7 @@ void recognizer_AudioLevelUpdated(object sender, AudioLevelUpdatedEventArgs e) ## Remarks The shared recognizer receives input while the desktop speech recognition is running. - The `AudioPosition` property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position in processing audio input. These positions can be different. For example, if the recognizer has received input for which it has not yet generated a recognition result then the value of the property is less than the value of the property. + The `AudioPosition` property references the input device's position in its generated audio stream. By contrast, the property references the recognizer's position in processing audio input. These positions can be different. For example, if the recognizer has received input for which it has not yet generated a recognition result then the value of the property is less than the value of the property. @@ -538,7 +538,7 @@ namespace SampleRecognition property of the associated . + To get which problem occurred, use the property of the associated . When you create a delegate for an `AudioSignalProblemOccurred` event, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -632,7 +632,7 @@ void recognizer_AudioSignalProblemOccurred(object sender, AudioSignalProblemOccu property of the associated . To get the current audio state of the input to the recognizer, use the recognizer's property. For more information about audio state, see the enumeration. + To get the audio state at the time of the event, use the property of the associated . To get the current audio state of the input to the recognizer, use the recognizer's property. For more information about audio state, see the enumeration. When you create a delegate for an `AudioStateChanged` event, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -802,7 +802,7 @@ namespace SampleRecognition The shared recognizer raises the , , , and events as if the recognition operation is not emulated. The recognizer ignores new lines and extra white space and treats punctuation as literal input. > [!NOTE] -> The object generated by the shared recognizer in response to emulated input has a value of `null` for its property. +> The object generated by the shared recognizer in response to emulated input has a value of `null` for its property. To emulate asynchronous recognition, use the method. @@ -1018,7 +1018,7 @@ namespace SharedRecognizer > If Windows Speech Recognition is in the **Sleeping** state, then the shared recognizer does not process input and does not raise the and related events, but still raises the event. > [!NOTE] -> The object generated by the shared recognizer in response to emulated input has a value of `null` for its property. +> The object generated by the shared recognizer in response to emulated input has a value of `null` for its property. To emulate synchronous recognition, use the method. @@ -1413,7 +1413,7 @@ namespace SharedRecognizer ## Remarks Changes to this property do not affect other instances of the class. - By default, the value of the property is `true` for a newly instantiated instance of . While the recognizer is disabled, none of the recognizer's speech recognition grammars are available for recognition operations. Setting the recognizer's property has no effect on the recognizer's property. + By default, the value of the property is `true` for a newly instantiated instance of . While the recognizer is disabled, none of the recognizer's speech recognition grammars are available for recognition operations. Setting the recognizer's property has no effect on the recognizer's property. ]]> @@ -1711,7 +1711,7 @@ namespace SharedRecognizer method initiates an asynchronous operation. The recognizer raises the `LoadGrammarCompleted` event when it completes the operation. To get the object that the recognizer loaded, use the property of the associated . To get the current objects the recognizer has loaded, use the recognizer's property. + The recognizer's method initiates an asynchronous operation. The recognizer raises the `LoadGrammarCompleted` event when it completes the operation. To get the object that the recognizer loaded, use the property of the associated . To get the current objects the recognizer has loaded, use the recognizer's property. When you create a delegate for a `LoadGrammarCompleted` event, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -1848,7 +1848,7 @@ namespace SampleRecognition property of the class contains the collection of objects that represent other candidate interpretations of the input. + The property of the class contains the collection of objects that represent other candidate interpretations of the input. The default value for is 10. @@ -1892,7 +1892,7 @@ namespace SampleRecognition When is `true`, during the execution of the handler the speech recognition service pauses and buffers new audio input as it arrives. Once the event handler exits, the speech recognition service resumes recognition and starts processing information from its input buffer. - To enable or disable the speech recognition service, use the property. + To enable or disable the speech recognition service, use the property. ]]> @@ -1925,7 +1925,7 @@ namespace SampleRecognition property references the input device's position in its generated audio stream. These positions can be different. For example, if the recognizer has received input for which it has not yet generated a recognition result then the value of the property is less than the value of the property. + The `RecognizerAudioPosition` property references the recognizer's position in processing its audio input. By contrast, the property references the input device's position in its generated audio stream. These positions can be different. For example, if the recognizer has received input for which it has not yet generated a recognition result then the value of the property is less than the value of the property. ]]> @@ -2161,11 +2161,11 @@ namespace SampleRecognition While the recognizer is handling the event: -- The recognizer does not process input, and the value of the property remains the same. +- The recognizer does not process input, and the value of the property remains the same. -- The recognizer continues to collect input, and the value of the property can change. +- The recognizer continues to collect input, and the value of the property can change. - To change whether the shared recognizer pauses recognition operations while an application is handling a event, use the property. + To change whether the shared recognizer pauses recognition operations while an application is handling a event, use the property. @@ -2299,7 +2299,7 @@ namespace SampleRecognition event, the property of the is `null`. + When the recognizer generates the event, the property of the is `null`. To provide a user token, use the or method. To specify an audio position offset, use the method. @@ -2337,7 +2337,7 @@ namespace SampleRecognition event, the property of the contains the value of the `userToken` parameter. + When the recognizer generates the event, the property of the contains the value of the `userToken` parameter. To specify an audio position offset, use the method. @@ -2379,7 +2379,7 @@ namespace SampleRecognition ## Remarks The recognizer does not initiate the recognizer update request until the recognizer's equals the current plus the value of the `audioPositionAheadToRaiseUpdate` parameter. - When the recognizer generates the event, the property of the contains the value of the `userToken` parameter. + When the recognizer generates the event, the property of the contains the value of the `userToken` parameter. ]]> @@ -2412,7 +2412,7 @@ namespace SampleRecognition property of the associated object indicates location in the input stream where the recognizer detected speech. For more information see the and properties and the and methods. + The shared recognizer can raise this event in response to input. The property of the associated object indicates location in the input stream where the recognizer detected speech. For more information see the and properties and the and methods. When you create a delegate for a event, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). @@ -2629,7 +2629,7 @@ namespace SampleRecognition property of the contains the rejected object. + The shared recognizer raises this event if it determines that input does not match with sufficient confidence any of the loaded speech recognition grammars. The property of the contains the rejected object. Confidence thresholds for the shared recognizer, managed by , are associated with a user profile and stored in the Windows registry. Applications should not write changes to the registry for the properties of the shared recognizer. @@ -2744,7 +2744,7 @@ namespace SampleRecognition property of the contains the accepted object. + The recognizer raises the `SpeechRecognized` event if it determines with sufficient confidence that input matches one of the loaded and enabled speech recognition grammars. The property of the contains the accepted object. Confidence thresholds for the shared recognizer, managed by , are associated with a user profile and stored in the Windows registry. Applications should not write changes to the registry for the properties of the shared recognizer. @@ -2903,7 +2903,7 @@ namespace SampleRecognition ## Remarks The shared recognizer raises this event when the state of Windows Speech Recognition changes to the or state. - To get the state of the shared recognizer at the time of the event, use the property of the associated . To get the current state of the shared recognizer, use the recognizer's property. + To get the state of the shared recognizer at the time of the event, use the property of the associated . To get the current state of the shared recognizer, use the recognizer's property. When you create a delegate for a event, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Events and Delegates](https://go.microsoft.com/fwlink/?LinkId=162418). diff --git a/xml/System.Speech.Recognition/StateChangedEventArgs.xml b/xml/System.Speech.Recognition/StateChangedEventArgs.xml index 492603ed885..9386fa968d6 100644 --- a/xml/System.Speech.Recognition/StateChangedEventArgs.xml +++ b/xml/System.Speech.Recognition/StateChangedEventArgs.xml @@ -25,110 +25,110 @@ Returns data from the event. - event is raised by the class. derives from and is passed to handlers for events. - - is a read-only property. A shared speech recognizer's state cannot be changed programmatically. Users can change a shared speech recognizer's state using the Speech Recognition user interface (UI) or through the **Speech Recognition** member of the Windows **Control Panel**. - - Both the **On** and **Sleep** settings in the Speech Recognition UI correspond to the `Listening` state. The **Off** setting in the Speech Recognition UI corresponds to . - - - -## Examples - The following example creates a shared speech recognizer, and then creates two types of grammars for recognizing specific words and for accepting free dictation. The example asynchronously loads all the created grammars to the recognizer. A handler for the event uses the method to put Windows Recognition in "listening" mode. - -``` -using System; -using System.Speech.Recognition; - -namespace SampleRecognition -{ - class Program - { - private static SpeechRecognizer recognizer; - public static void Main(string[] args) - { - - // Initialize a shared speech recognition engine. - recognizer = new SpeechRecognizer(); - - // Add a handler for the LoadGrammarCompleted event. - recognizer.LoadGrammarCompleted += new EventHandler(recognizer_LoadGrammarCompleted); - - // Add a handler for the SpeechRecognized event. - recognizer.SpeechRecognized += new EventHandler(recognizer_SpeechRecognized); - - // Add a handler for the StateChanged event. - recognizer.StateChanged += new EventHandler(recognizer_StateChanged); - - // Create "yesno" grammar. - Choices yesChoices = new Choices(new string[] { "yes", "yup", "yah}" }); - SemanticResultValue yesValue = - new SemanticResultValue(yesChoices, (bool)true); - Choices noChoices = new Choices(new string[] { "no", "nope", "nah" }); - SemanticResultValue noValue = new SemanticResultValue(noChoices, (bool)false); - SemanticResultKey yesNoKey = - new SemanticResultKey("yesno", new Choices(new GrammarBuilder[] { yesValue, noValue })); - Grammar yesnoGrammar = new Grammar(yesNoKey); - yesnoGrammar.Name = "yesNo"; - - // Create "done" grammar. - Grammar doneGrammar = - new Grammar(new Choices(new string[] { "done", "exit", "quit", "stop" })); - doneGrammar.Name = "Done"; - - // Create dictation grammar. - Grammar dictation = new DictationGrammar(); - dictation.Name = "Dictation"; - - // Load grammars to the recognizer. - recognizer.LoadGrammarAsync(yesnoGrammar); - recognizer.LoadGrammarAsync(doneGrammar); - recognizer.LoadGrammarAsync(dictation); - - // Keep the console window open. - Console.ReadLine(); - } - - // Put the shared speech recognizer into "listening" mode. - static void recognizer_StateChanged(object sender, StateChangedEventArgs e) - { - if (e.RecognizerState != RecognizerState.Stopped) - { - recognizer.EmulateRecognizeAsync("Start listening"); - } - } - - // Write the grammar name and the text of the recognized phrase to the console. - static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) - { - Console.WriteLine("Grammar({0}): {1}", e.Result.Grammar.Name, e.Result.Text); - - // Add event handler code here. - } - - // Handle the LoadGrammarCompleted event. - static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) - { - string grammarName = e.Grammar.Name; - bool grammarLoaded = e.Grammar.Loaded; - if (e.Error != null) - { - Console.WriteLine("LoadGrammar for {0} failed with a {1}.", - grammarName, e.Error.GetType().Name); - } - - // Add exception handling code here. - Console.WriteLine("Grammar {0} {1} loaded.", - grammarName, (grammarLoaded) ? "is" : "is not"); - } - } -} - -``` - + event is raised by the class. derives from and is passed to handlers for events. + + is a read-only property. A shared speech recognizer's state cannot be changed programmatically. Users can change a shared speech recognizer's state using the Speech Recognition user interface (UI) or through the **Speech Recognition** member of the Windows **Control Panel**. + + Both the **On** and **Sleep** settings in the Speech Recognition UI correspond to the `Listening` state. The **Off** setting in the Speech Recognition UI corresponds to . + + + +## Examples + The following example creates a shared speech recognizer, and then creates two types of grammars for recognizing specific words and for accepting free dictation. The example asynchronously loads all the created grammars to the recognizer. A handler for the event uses the method to put Windows Recognition in "listening" mode. + +``` +using System; +using System.Speech.Recognition; + +namespace SampleRecognition +{ + class Program + { + private static SpeechRecognizer recognizer; + public static void Main(string[] args) + { + + // Initialize a shared speech recognition engine. + recognizer = new SpeechRecognizer(); + + // Add a handler for the LoadGrammarCompleted event. + recognizer.LoadGrammarCompleted += new EventHandler(recognizer_LoadGrammarCompleted); + + // Add a handler for the SpeechRecognized event. + recognizer.SpeechRecognized += new EventHandler(recognizer_SpeechRecognized); + + // Add a handler for the StateChanged event. + recognizer.StateChanged += new EventHandler(recognizer_StateChanged); + + // Create "yesno" grammar. + Choices yesChoices = new Choices(new string[] { "yes", "yup", "yah}" }); + SemanticResultValue yesValue = + new SemanticResultValue(yesChoices, (bool)true); + Choices noChoices = new Choices(new string[] { "no", "nope", "nah" }); + SemanticResultValue noValue = new SemanticResultValue(noChoices, (bool)false); + SemanticResultKey yesNoKey = + new SemanticResultKey("yesno", new Choices(new GrammarBuilder[] { yesValue, noValue })); + Grammar yesnoGrammar = new Grammar(yesNoKey); + yesnoGrammar.Name = "yesNo"; + + // Create "done" grammar. + Grammar doneGrammar = + new Grammar(new Choices(new string[] { "done", "exit", "quit", "stop" })); + doneGrammar.Name = "Done"; + + // Create dictation grammar. + Grammar dictation = new DictationGrammar(); + dictation.Name = "Dictation"; + + // Load grammars to the recognizer. + recognizer.LoadGrammarAsync(yesnoGrammar); + recognizer.LoadGrammarAsync(doneGrammar); + recognizer.LoadGrammarAsync(dictation); + + // Keep the console window open. + Console.ReadLine(); + } + + // Put the shared speech recognizer into "listening" mode. + static void recognizer_StateChanged(object sender, StateChangedEventArgs e) + { + if (e.RecognizerState != RecognizerState.Stopped) + { + recognizer.EmulateRecognizeAsync("Start listening"); + } + } + + // Write the grammar name and the text of the recognized phrase to the console. + static void recognizer_SpeechRecognized(object sender, SpeechRecognizedEventArgs e) + { + Console.WriteLine("Grammar({0}): {1}", e.Result.Grammar.Name, e.Result.Text); + + // Add event handler code here. + } + + // Handle the LoadGrammarCompleted event. + static void recognizer_LoadGrammarCompleted(object sender, LoadGrammarCompletedEventArgs e) + { + string grammarName = e.Grammar.Name; + bool grammarLoaded = e.Grammar.Loaded; + if (e.Error != null) + { + Console.WriteLine("LoadGrammar for {0} failed with a {1}.", + grammarName, e.Error.GetType().Name); + } + + // Add exception handling code here. + Console.WriteLine("Grammar {0} {1} loaded.", + grammarName, (grammarLoaded) ? "is" : "is not"); + } + } +} + +``` + ]]> @@ -162,22 +162,22 @@ namespace SampleRecognition Gets the current state of the shared speech recognition engine in Windows. A instance that indicates whether the state of a shared speech recognition engine is or . - instance that is obtained from the property of a instance passed to a handler for a event. - -``` - -// Make sure that _recognizer and recognition start buttons are disabled if state is stopped. -// Re-enable the start button to allow manual re-enable if the speech recognizer is listening. -_recognizer.StateChanged += - delegate(object sender, StateChangedEventArgs eventArgs) -{ - _recognizerStateLabel.Text = "Speech Recognizer State: " + eventArgs.RecognizerState.ToString(); -}; -``` - + instance that is obtained from the property of a instance passed to a handler for a event. + +``` + +// Make sure that _recognizer and recognition start buttons are disabled if state is stopped. +// Re-enable the start button to allow manual re-enable if the speech recognizer is listening. +_recognizer.StateChanged += + delegate(object sender, StateChangedEventArgs eventArgs) +{ + _recognizerStateLabel.Text = "Speech Recognizer State: " + eventArgs.RecognizerState.ToString(); +}; +``` + ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml b/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml index baed880c467..d2b0eee84a2 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/ContourPoint.xml @@ -35,13 +35,13 @@ Represents changes in pitch for the speech content of a . - objects are obtained by the method, or used to set the pitch contour for a by the method. - + objects are obtained by the method, or used to set the pitch contour for a by the method. + ]]> @@ -106,13 +106,13 @@ Gets the value that represents the amount to raise or lower the pitch at a point in a . To be added. - property to define the amount to raise or lower the pitch. - - If a pitch value is not defined for 0% or 100% then the nearest pitch target is copied. All relative values for the pitch are relative to the pitch value just before the contained text. - + property to define the amount to raise or lower the pitch. + + If a pitch value is not defined for 0% or 100% then the nearest pitch target is copied. All relative values for the pitch are relative to the pitch value just before the contained text. + ]]> @@ -144,11 +144,11 @@ Gets a member of that specifies the unit to use for the number specified in the parameter of a object. To be added. - property to define the amount to raise or lower the pitch. - + property to define the amount to raise or lower the pitch. + ]]> @@ -187,11 +187,11 @@ Determines if a given object is an instance of and equal to the current instance of . Returns if the current instance of and that obtained from the argument are equal, otherwise returns . - provided by the `obj` argument cannot be cast to . - + provided by the `obj` argument cannot be cast to . + ]]> @@ -248,11 +248,11 @@ Returns a hash code for this instance. A 32-bit signed integer hash code. - objects might have the same hash code even though they represent different time values. - + objects might have the same hash code even though they represent different time values. + ]]> @@ -346,11 +346,11 @@ Gets a that specifies the point at which to apply the pitch change in a . This is expressed as the elapsed percentage of the duration of the at that point. To be added. - diff --git a/xml/System.Speech.Synthesis.TtsEngine/EmphasisBreak.xml b/xml/System.Speech.Synthesis.TtsEngine/EmphasisBreak.xml index a144e20c554..f32f830f9a4 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/EmphasisBreak.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/EmphasisBreak.xml @@ -24,17 +24,17 @@ Enumerates values for lengths of between spoken words. - instances through the property on the object returned by the property on an instance of . - - Each synthetic speech engine is free to determine how to render breaks between words; the nature of emphasis differs between languages, dialects, genders, or voices. - - Both and may be used when setting or getting the on a instance. - - The two values may be distinguished by the fact that the actual values of are all less than zero and values of are greater than or equal to zero; and by using the value of returned by the property on the object returned by the property on an instance. From more information, see ,and . - + instances through the property on the object returned by the property on an instance of . + + Each synthetic speech engine is free to determine how to render breaks between words; the nature of emphasis differs between languages, dialects, genders, or voices. + + Both and may be used when setting or getting the on a instance. + + The two values may be distinguished by the fact that the actual values of are all less than zero and values of are greater than or equal to zero; and by using the value of returned by the property on the object returned by the property on an instance. From more information, see ,and . + ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/EmphasisWord.xml b/xml/System.Speech.Synthesis.TtsEngine/EmphasisWord.xml index 3f84d1672d8..6ee46d51dc9 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/EmphasisWord.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/EmphasisWord.xml @@ -24,17 +24,17 @@ Enumerates the values of for a specific . - instances through the property on the object returned by the property on an instance of . - - Each synthetic speech engine is free to determine how to render emphasis; the nature of emphasis differs between languages, dialects, genders, or voices. - - Both and may be used when setting or getting the on a instance. - - The two values may be distinguished by the fact that the actual values of are greater than or equal to zero, and the values of are all less than zero; and by using the value of returned by the property on the object returned by the property on an instance. From more information, see ,and . - + instances through the property on the object returned by the property on an instance of . + + Each synthetic speech engine is free to determine how to render emphasis; the nature of emphasis differs between languages, dialects, genders, or voices. + + Both and may be used when setting or getting the on a instance. + + The two values may be distinguished by the fact that the actual values of are greater than or equal to zero, and the values of are all less than zero; and by using the value of returned by the property on the object returned by the property on an instance. From more information, see ,and . + ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml b/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml index e3c0a59e617..329711a287d 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/EventParameterType.xml @@ -24,90 +24,90 @@ Enumerates the types of data pointers passed to speech synthesis events. - object. An `EventParameterType` enumeration member passed as the `parameterType` argument to the constructor for specifies how the `param2` argument of the constructor (which must be an ) is interpreted. - -The choice of `EventParameterType` is dictated by the type of event being requested, as specified by a member of . - -For detailed information on how use `EventParameterType`, see the documentation for - +The `EventParameterType` enumeration is used when constructing a object. An `EventParameterType` enumeration member passed as the `parameterType` argument to the constructor for specifies how the `param2` argument of the constructor (which must be an ) is interpreted. + +The choice of `EventParameterType` is dictated by the type of event being requested, as specified by a member of . + +For detailed information on how use `EventParameterType`, see the documentation for + > [!NOTE] -> Currently, instances of a managed synthetic speech engines written using the members of the namespace cannot change resources after construction. - -## Examples - The following example is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and . - - The implementation of - -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - - Translates Americanism to Britishisms in the text to be spoken. - - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - - The parameters on , including the member value returned by , are used to log the event generated through the `LogSpeechEvent` method. - -3. A speech rendering engine is then called with the modified array. - +> Currently, instances of a managed synthetic speech engines written using the members of the namespace cannot change resources after construction. + +## Examples + The following example is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and . + + The implementation of + +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. + +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation + + - Translates Americanism to Britishisms in the text to be spoken. + + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + + The parameters on , including the member value returned by , are used to log the event generated through the `LogSpeechEvent` method. + +3. A speech rendering engine is then called with the modified array. + ```csharp -private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; -private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; -internal struct UsVsUk -{ - internal string UK; - internal string US; -} - -override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) -{ - TextFragment [] newFrags=new TextFragment[frags.Length]; - - for (int i=0;i 0) { - SpeechEventInfo[] events = new SpeechEventInfo[1]; - events[0] = spEvent; - site.AddEvents(events, 1); - } - } - } - } - } - - _baseSynthesize.Speak(newFrags, wfx, site); - -} -``` - +private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; +private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; +internal struct UsVsUk +{ + internal string UK; + internal string US; +} + +override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) +{ + TextFragment [] newFrags=new TextFragment[frags.Length]; + + for (int i=0;i 0) { + SpeechEventInfo[] events = new SpeechEventInfo[1]; + events[0] = spEvent; + site.AddEvents(events, 1); + } + } + } + } + } + + _baseSynthesize.Speak(newFrags, wfx, site); + +} +``` + ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml b/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml index 49465bad46d..6e574709c41 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/FragmentState.xml @@ -42,7 +42,7 @@ The information in is obtained by parsing the attributes decorating speech text in the Synthesize Speech Markup Language (SSML) used as an input to a synthesis engine. - A object can exist for any synthesizer action request as specified by its property. However, the meaning of its members may change for different actions. For more information on synthesize actions, see for more information about specifying synthesizer actions. + A object can exist for any synthesizer action request as specified by its property. However, the meaning of its members may change for different actions. For more information on synthesize actions, see for more information about specifying synthesizer actions. - Specification and control of the quality of the spoken output is largely handled through the , , and @@ -114,7 +114,7 @@ If the value specified by the `action` argument is not , the `emphasis` argument must be of type . - If the value of the `duration` argument and The property or the object specified by the `prosody` argument differ, the value on the object is used. + If the value of the `duration` argument and The property or the object specified by the `prosody` argument differ, the value on the object is used. ]]> @@ -209,7 +209,7 @@ depends on the value returned by the property on the current . + The interpretation of the value returned by depends on the value returned by the property on the current . 1. If the value of is @@ -453,9 +453,9 @@ property corresponds to the `` XML tag of SSML input to a synthesis engine. + The information returned by the property corresponds to the `` XML tag of SSML input to a synthesis engine. - The array of `char` objects returned by property expresses pronunciation using the International Phonetic Alphabet (IPA). + The array of `char` objects returned by property expresses pronunciation using the International Phonetic Alphabet (IPA). ]]> @@ -530,11 +530,11 @@ ## Remarks The information returned by corresponds to the `` tag and its attributes in the SSML specification, and can specify: -- The content type (such as currency, date, or address) or language construct represented by property of a . +- The content type (such as currency, date, or address) or language construct represented by property of a . -- Optional formatting information to handle the content type represented by property of a , for example, a date syntax. +- Optional formatting information to handle the content type represented by property of a , for example, a date syntax. -- The detail to be used in generating speech from the property of a , for example, whether to explicitly render punctuation. +- The detail to be used in generating speech from the property of a , for example, whether to explicitly render punctuation. ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/ProsodyVolume.xml b/xml/System.Speech.Synthesis.TtsEngine/ProsodyVolume.xml index e87793ee544..b707f86cc7f 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/ProsodyVolume.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/ProsodyVolume.xml @@ -24,15 +24,15 @@ Enumerates values for the property of a object. - property on the site supplied to that engine. - - Fine tuning and modulation of output volume is managed on the basis of particular objects, using members of `ProsodyVolume` to set the property on instances of used in creating or modifying the object for the instance of . - + + The current base volume setting for a custom synthetic speech engine is obtained as a `ProsodyVolume` value through the property on the site supplied to that engine. + + Fine tuning and modulation of output volume is managed on the basis of particular objects, using members of `ProsodyVolume` to set the property on instances of used in creating or modifying the object for the instance of . + ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/SayAs.xml b/xml/System.Speech.Synthesis.TtsEngine/SayAs.xml index 63fca4111dd..3a470c574fc 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/SayAs.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/SayAs.xml @@ -50,11 +50,11 @@ Creates a new instance of the SayAs class. - class are used to get or set the values for the attributes of the `say-as` element in SSML markup. The property uses a instance to inform the how to speak the text contained in the property of a . - + class are used to get or set the values for the attributes of the `say-as` element in SSML markup. The property uses a instance to inform the how to speak the text contained in the property of a . + ]]> @@ -86,11 +86,11 @@ Gets or sets the value of the detail attribute for a say-as element in the SSML markup language of a prompt. To be added. - property gets or sets the value for the property in a instance. - + property gets or sets the value for the property in a instance. + ]]> @@ -122,13 +122,13 @@ Gets or sets the value of the format attribute for a say-as element in the SSML markup language of a prompt. To be added. - property gets or sets the value for the property in a instance. - - For example, a prompt may contain the phrase "The time is ` 05:00 `". In this example, `05:00` could be spoken as "five o'clock" or "five AM" or "oh five hundred". The property allows the value of the `interpret-as` attribute to be extended to specify which time format to speak. If the value for the `interpret-as` attribute is "time:24hour", the speaks "oh five hundred". If the value for the `interpret-as` attribute is "time:12hour", the speaks "five A M". - + property gets or sets the value for the property in a instance. + + For example, a prompt may contain the phrase "The time is ` 05:00 `". In this example, `05:00` could be spoken as "five o'clock" or "five AM" or "oh five hundred". The property allows the value of the `interpret-as` attribute to be extended to specify which time format to speak. If the value for the `interpret-as` attribute is "time:24hour", the speaks "oh five hundred". If the value for the `interpret-as` attribute is "time:12hour", the speaks "five A M". + ]]> @@ -160,15 +160,15 @@ Gets or sets the value of the interpret-as attribute for a say-as element in the SSML markup language of a prompt. To be added. - property gets or sets the value for the property in a instance. - - The uses the content type indicated by the property to determine how to render specified text. - - For example, the name Edgar could be spoken as a name: "My name is Edgar". Or it could be spelled out with letters, as specified with the `interpret-as` attribute in this sentence: "My name is ` Edgar `." In this case, the speaks Edgar as "E D G A R". - + property gets or sets the value for the property in a instance. + + The uses the content type indicated by the property to determine how to render specified text. + + For example, the name Edgar could be spoken as a name: "My name is Edgar". Or it could be spelled out with letters, as specified with the `interpret-as` attribute in this sentence: "My name is ` Edgar `." In this case, the speaks Edgar as "E D G A R". + ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml b/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml index 49763dc956a..525c5f889e6 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/SpeechEventInfo.xml @@ -47,11 +47,11 @@ 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. 3. A speech rendering engine is then called with the modified array. @@ -153,7 +153,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si For detailed information on appropriate values for `parameterType`, `param1`, and `param2`, see documentation for - The type of the events which can be handled by the Speech platform infrastructure can be obtained through the property on the synthesizer engine site implementation of . + The type of the events which can be handled by the Speech platform infrastructure can be obtained through the property on the synthesizer engine site implementation of . @@ -164,11 +164,11 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. 3. A speech rendering engine is then called with the modified array. @@ -330,11 +330,11 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. @@ -516,7 +516,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si property of are uniquely determined by the values of the and properties the instance. + The requirements and meaning of property of are uniquely determined by the values of the and properties the instance. For detailed information on how use , see documentation for . @@ -529,11 +529,11 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. @@ -627,7 +627,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si property of are uniquely determined by the values of the and properties the instance. + The requirements on the `System.IntPtr` reference of the property of are uniquely determined by the values of the and properties the instance. For detailed information on how use , see documentation for . @@ -640,11 +640,11 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. @@ -738,7 +738,7 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si property of are uniquely determined by the values of the and properties the instance. + The requirements on the `System.IntPtr` reference of the property of are uniquely determined by the values of the and properties the instance. For detailed information on how use , see documentation for . @@ -751,11 +751,11 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si 1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - Translates Americanism to Britishisms in the text to be spoken. - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. The parameters on , including are used to log the event generated through the `LogSpeechEvent` method. diff --git a/xml/System.Speech.Synthesis.TtsEngine/TextFragment.xml b/xml/System.Speech.Synthesis.TtsEngine/TextFragment.xml index aee78e502a4..a0b49c5a3aa 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TextFragment.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TextFragment.xml @@ -25,84 +25,84 @@ Contains text and speech attribute information for consumption by a speech synthesizer engine. - objects. - - Speech content is available through the , , and properties of a instance. - - Speech attribute information, such as emphasis, pitch, and rate, are obtained from the object returned by the property. - - - -## Examples - The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and . - - The implementation of - -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - - Particular care is used to respect the , on the original when creating the on the new instances. - -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - - Translates Americanism to Britishisms in the text to be spoken. - - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - -3. A speech rendering engine is then called with the modified array. - -``` -private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; -private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; -internal struct UsVsUk -{ - internal string UK; - internal string US; -} - -override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) -{ - TextFragment [] newFrags=new TextFragment[frags.Length]; - - for (int i=0;i 0) { - SpeechEventInfo[] events = new SpeechEventInfo[1]; - events[0] = spEvent; - site.AddEvents(events, 1); - } - } - } - } - } - - _baseSynthesize.Speak(newFrags, wfx, site); - -} -``` - + objects. + + Speech content is available through the , , and properties of a instance. + + Speech attribute information, such as emphasis, pitch, and rate, are obtained from the object returned by the property. + + + +## Examples + The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and . + + The implementation of + +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. + + Particular care is used to respect the , on the original when creating the on the new instances. + +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation + + - Translates Americanism to Britishisms in the text to be spoken. + + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + +3. A speech rendering engine is then called with the modified array. + +``` +private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; +private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; +internal struct UsVsUk +{ + internal string UK; + internal string US; +} + +override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) +{ + TextFragment [] newFrags=new TextFragment[frags.Length]; + + for (int i=0;i 0) { + SpeechEventInfo[] events = new SpeechEventInfo[1]; + events[0] = spEvent; + site.AddEvents(events, 1); + } + } + } + } + } + + _baseSynthesize.Speak(newFrags, wfx, site); + +} +``` + ]]> @@ -124,11 +124,11 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si Constructs a new instance of . - . - + . + ]]> @@ -164,13 +164,13 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si Gets or sets speech attribute information for a . A instance is returned, or used to set speech attribute information for a . - returned by the property on the instance of returned by . - + returned by the property on the instance of returned by . + ]]> @@ -206,80 +206,80 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si Gets or sets the length of the speech text in the fragment. An is returned or can be used to set the length, in character, of the text string associated with this fragment to be spoken. - , and using the use of , , , and . - - The implementation of - -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - - Particular care is used to respect the , on the original when creating the on the new instances. - -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - - Translates Americanism to Britishisms in the text to be spoken. - - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - -3. A speech rendering engine is then called with the modified array. - -``` -private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; -private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; -internal struct UsVsUk -{ - internal string UK; - internal string US; -} - -override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) -{ - TextFragment [] newFrags=new TextFragment[frags.Length]; - - for (int i=0;i 0) { - SpeechEventInfo[] events = new SpeechEventInfo[1]; - events[0] = spEvent; - site.AddEvents(events, 1); - } - } - } - } - } - - _baseSynthesize.Speak(newFrags, wfx, site); - -} -``` - + , and using the use of , , , and . + + The implementation of + +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. + + Particular care is used to respect the , on the original when creating the on the new instances. + +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation + + - Translates Americanism to Britishisms in the text to be spoken. + + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + +3. A speech rendering engine is then called with the modified array. + +``` +private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; +private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; +internal struct UsVsUk +{ + internal string UK; + internal string US; +} + +override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) +{ + TextFragment [] newFrags=new TextFragment[frags.Length]; + + for (int i=0;i 0) { + SpeechEventInfo[] events = new SpeechEventInfo[1]; + events[0] = spEvent; + site.AddEvents(events, 1); + } + } + } + } + } + + _baseSynthesize.Speak(newFrags, wfx, site); + +} +``` + ]]> @@ -315,80 +315,80 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si Gets or sets the starting location of the text in the fragment. An is returned or can be used to set the start location, in character, of the part of text string associated with this fragment to be spoken. - , and using the use of , , , and . - - The implementation of - -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - - Particular care is used to respect the , on the original when creating the on the new instances. - -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - - Translates Americanism to Britishisms in the text to be spoken. - - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - -3. A speech rendering engine is then called with the modified array. - -``` -private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; -private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; -internal struct UsVsUk -{ - internal string UK; - internal string US; -} - -override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) -{ - TextFragment [] newFrags=new TextFragment[frags.Length]; - - for (int i=0;i 0) { - SpeechEventInfo[] events = new SpeechEventInfo[1]; - events[0] = spEvent; - site.AddEvents(events, 1); - } - } - } - } - } - - _baseSynthesize.Speak(newFrags, wfx, site); - -} -``` - + , and using the use of , , , and . + + The implementation of + +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. + + Particular care is used to respect the , on the original when creating the on the new instances. + +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation + + - Translates Americanism to Britishisms in the text to be spoken. + + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + +3. A speech rendering engine is then called with the modified array. + +``` +private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; +private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; +internal struct UsVsUk +{ + internal string UK; + internal string US; +} + +override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) +{ + TextFragment [] newFrags=new TextFragment[frags.Length]; + + for (int i=0;i 0) { + SpeechEventInfo[] events = new SpeechEventInfo[1]; + events[0] = spEvent; + site.AddEvents(events, 1); + } + } + } + } + } + + _baseSynthesize.Speak(newFrags, wfx, site); + +} +``` + ]]> @@ -420,84 +420,84 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si Gets or sets the speech text of the fragment. A is returned or can be used to set the speech text to be used by a speech synthesis engine to generate audio output. - . - - Resetting the value of will not change the value of and . - - - -## Examples - The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and . - - The implementation of - -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - - Particular care is used to respect the , on the original when creating the on the new instances. - -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - - Translates Americanism to Britishisms in the text to be spoken. - - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - -3. A speech rendering engine is then called with the modified array. - -``` -private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; -private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; -internal struct UsVsUk -{ - internal string UK; - internal string US; -} - -override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) -{ - TextFragment [] newFrags=new TextFragment[frags.Length]; - - for (int i=0;i 0) { - SpeechEventInfo[] events = new SpeechEventInfo[1]; - events[0] = spEvent; - site.AddEvents(events, 1); - } - } - } - } - } - - _baseSynthesize.Speak(newFrags, wfx, site); - -} -``` - + . + + Resetting the value of will not change the value of and . + + + +## Examples + The example below is part of a custom speech synthesis implementation inheriting from , and using the use of , , , and . + + The implementation of + +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. + + Particular care is used to respect the , on the original when creating the on the new instances. + +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation + + - Translates Americanism to Britishisms in the text to be spoken. + + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + +3. A speech rendering engine is then called with the modified array. + +``` +private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; +private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; +internal struct UsVsUk +{ + internal string UK; + internal string US; +} + +override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) +{ + TextFragment [] newFrags=new TextFragment[frags.Length]; + + for (int i=0;i 0) { + SpeechEventInfo[] events = new SpeechEventInfo[1]; + events[0] = spEvent; + site.AddEvents(events, 1); + } + } + } + } + } + + _baseSynthesize.Speak(newFrags, wfx, site); + +} +``` + ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml index 73de1337683..9c7bc1dce89 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineAction.xml @@ -24,33 +24,33 @@ Specifies the Speech Synthesis Markup Language (SSML) action to be taken in rendering a given . - . The actions correspond closely to elements in the SSML specification and are implemented on the text returned by the property on a . - - The value associated with a is returned by the property. - - Processing of the value returned by the property is handled by a speech synthesizes implementation of the method on a class derived from . - - - -## Examples - The following example is part of a custom speech synthesis implementation inheriting from , and using the use of , , and - - The implementation of - -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - -2. If the enumeration value by found from the property on the returned by the property of each instance is Speak, the implementation - - - Translates Americanism to Britishisms in the text to be spoken. - - - If the property on the interface provided to the implementation support the event type, an event to drive a synthesizer progress meter is created. - -3. A speech rendering engine is then called with the modified array. - +`TtsEngineAction` represents requests for servicing a . The actions correspond closely to elements in the SSML specification and are implemented on the text returned by the property on a . + + The value associated with a is returned by the property. + + Processing of the value returned by the property is handled by a speech synthesizes implementation of the method on a class derived from . + + + +## Examples + The following example is part of a custom speech synthesis implementation inheriting from , and using the use of , , and + + The implementation of + +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. + +2. If the enumeration value by found from the property on the returned by the property of each instance is Speak, the implementation + + - Translates Americanism to Britishisms in the text to be spoken. + + - If the property on the interface provided to the implementation support the event type, an event to drive a synthesizer progress meter is created. + +3. A speech rendering engine is then called with the modified array. + ```csharp private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; @@ -59,11 +59,11 @@ internal struct UsVsUk internal string UK; internal string US; } - + override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) { - TextFragment [] newFrags=new TextFragment[frags.Length]; - + TextFragment [] newFrags=new TextFragment[frags.Length]; + for (int i=0;i 0) + if (s.Trim().Length > 0) { SpeechEventInfo[] events = new SpeechEventInfo[1]; events[0] = spEvent; @@ -105,8 +105,8 @@ override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite si _baseSynthesize.Speak(newFrags, wfx, site); } -``` - +``` + ]]> diff --git a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml index 7c8d04a8854..1d83b0a68cd 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TtsEngineSsml.xml @@ -25,27 +25,27 @@ Abstract base class to be implemented by all text to speech synthesis engines. - . - - A properly registered implementation of can then be used as a synthesizer voice by name space based applications. - - Objects inheriting from must override the following members: , , , and . - - The most important member of the class to be implemented is the method. - - The method is called by the infrastructures text parser receiving: - -1. A reference to the interface, which provides access to system services such as even queuing and writing audio output. - -2. An array of instance produced from Speech Synthesis Markup Language (SSML) input. In addition to text to be rendered as speech, the parsing of the SSML stores information about the requested attributes of the speech in a instance associated with each incoming object. - - A speech synthesizer application can optionally make requests for a specified output format by implementing to be called by the platform when it tries to provide the correct audio output. - - An implementer can also provide support for managing external definitions of pronunciations, or lexicons, by their implementation of and . - + . + + A properly registered implementation of can then be used as a synthesizer voice by name space based applications. + + Objects inheriting from must override the following members: , , , and . + + The most important member of the class to be implemented is the method. + + The method is called by the infrastructures text parser receiving: + +1. A reference to the interface, which provides access to system services such as even queuing and writing audio output. + +2. An array of instance produced from Speech Synthesis Markup Language (SSML) input. In addition to text to be rendered as speech, the parsing of the SSML stores information about the requested attributes of the speech in a instance associated with each incoming object. + + A speech synthesizer application can optionally make requests for a specified output format by implementing to be called by the platform when it tries to provide the correct audio output. + + An implementer can also provide support for managing external definitions of pronunciations, or lexicons, by their implementation of and . + ]]> @@ -77,13 +77,13 @@ Full name of the registry key for the Voice Token associated with the implementation. engine. Constructs a new instance of based on an appropriate Voice Token registry key. - based applications selecting a synthesizer voice to be used by an instance of . - - A must be register under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Speech\Voices\Tokens. - + based applications selecting a synthesizer voice to be used by an instance of . + + A must be register under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Speech\Voices\Tokens. + ]]> @@ -116,38 +116,38 @@ A reference to an interface used to interact with the platform infrastructure. Adds a lexicon to the implemented by the current instance. - based applications calling and using the synthesizer voice implemented by the current instance. - - The value of `mediaType` is typically a MIME specification, as the SSML specification uses MIME for media specifications. - + based applications calling and using the synthesizer voice implemented by the current instance. + + The value of `mediaType` is typically a MIME specification, as the SSML specification uses MIME for media specifications. + [!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)] - -## Examples - The implementation of uses the interface passed in to load a lexicon from a resource. It then stores a `System.IO.Stream` to the lexicon in a `System.Collections.Generic.Dictionary` instance, indexed by the lexicon URI. - -``` -public static Dictionary _aLexicons = new Dictionary(); - - public void AddLexicon(Uri uri, string mediaType, ITtsEngineSite site) { - Stream stream = site.LoadResource(uri, mediaType); - _aLexicons.Add(uri, stream); -} - - public void RemoveLexicon(Uri uri, ITtsEngineSite site) { - Stream stream; - if (_aLexicons.TryGetValue(uri, out stream)) { - stream.Close(); - _aLexicons.Remove(uri); - } -} - -``` - + +## Examples + The implementation of uses the interface passed in to load a lexicon from a resource. It then stores a `System.IO.Stream` to the lexicon in a `System.Collections.Generic.Dictionary` instance, indexed by the lexicon URI. + +``` +public static Dictionary _aLexicons = new Dictionary(); + + public void AddLexicon(Uri uri, string mediaType, ITtsEngineSite site) { + Stream stream = site.LoadResource(uri, mediaType); + _aLexicons.Add(uri, stream); +} + + public void RemoveLexicon(Uri uri, ITtsEngineSite site) { + Stream stream; + if (_aLexicons.TryGetValue(uri, out stream)) { + stream.Close(); + _aLexicons.Remove(uri); + } +} + +``` + ]]> @@ -182,62 +182,62 @@ public static Dictionary _aLexicons = new Dictionary() Returns the best matching audio output supported by a given synthesize engine response to a request to the synthesizer engine for the support of a particular output format. Returns a valid instance referring to a containing detailed information about the output format. - @@ -271,35 +271,35 @@ internal struct WaveFormat { A reference to an interface passed in by the platform infrastructure to allow access to the infrastructure resources. Removes a lexicon currently loaded by the implemented by the current instance. - based applications calling and using the synthesizer voice implemented by the current instance. - + based applications calling and using the synthesizer voice implemented by the current instance. + [!INCLUDE [untrusted-data-class-note](~/includes/untrusted-data-class-note.md)] - -## Examples - The implementation of uses the lexicon URI to query an instance `System.Collections.Generic.Dictionary` for the `System.IO.Stream`, closes the stream and removes the uri referring to the lexicon. - -``` -public static Dictionary _aLexicons = new Dictionary(); - - public void AddLexicon(Uri uri, string mediaType, ITtsEngineSite site) { - Stream stream = site.LoadResource(uri, mediaType); - _aLexicons.Add(uri, stream); -} - - public void RemoveLexicon(Uri uri, ITtsEngineSite site) { - Stream stream; - if (_aLexicons.TryGetValue(uri, out stream)) { - stream.Close(); - _aLexicons.Remove(uri); - } -} -``` - + +## Examples + The implementation of uses the lexicon URI to query an instance `System.Collections.Generic.Dictionary` for the `System.IO.Stream`, closes the stream and removes the uri referring to the lexicon. + +``` +public static Dictionary _aLexicons = new Dictionary(); + + public void AddLexicon(Uri uri, string mediaType, ITtsEngineSite site) { + Stream stream = site.LoadResource(uri, mediaType); + _aLexicons.Add(uri, stream); +} + + public void RemoveLexicon(Uri uri, ITtsEngineSite site) { + Stream stream; + if (_aLexicons.TryGetValue(uri, out stream)) { + stream.Close(); + _aLexicons.Remove(uri); + } +} +``` + ]]> @@ -335,111 +335,111 @@ public static Dictionary _aLexicons = new Dictionary() A reference to an interface passed in by the platform infrastructure to allow access to the infrastructure resources. Renders specified array in the specified output format. - , and using the use of , , , and - - The implementation of - -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - -2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation - - - Translates Americanism to Britishisms in the text to be spoken. - - - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. - -3. A speech rendering engine is then called with the modified array. - -``` -private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; -private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; -internal struct UsVsUk -{ - internal string UK; - internal string US; -} - -override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) -{ - TextFragment [] newFrags=new TextFragment[frags.Length]; - - for (int i=0;i 0) { - SpeechEventInfo[] events = new SpeechEventInfo[1]; - events[0] = spEvent; - site.AddEvents(events, 1); - } - } - } - } - } - _baseSynthesize.Speak(newFrags, wfx, site); - -} -``` - + , and using the use of , , , and + + The implementation of + +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. + +2. If the enumeration value by found from the property on the returned by the property of each instance is , the implementation + + - Translates Americanism to Britishisms in the text to be spoken. + + - If the property on the interfaces provided to the implementation support the event type, a instance is used to create an event to drive a synthesizer progress meter is created. + +3. A speech rendering engine is then called with the modified array. + +``` +private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; +private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; +internal struct UsVsUk +{ + internal string UK; + internal string US; +} + +override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) +{ + TextFragment [] newFrags=new TextFragment[frags.Length]; + + for (int i=0;i 0) { + SpeechEventInfo[] events = new SpeechEventInfo[1]; + events[0] = spEvent; + site.AddEvents(events, 1); + } + } + } + } + } + _baseSynthesize.Speak(newFrags, wfx, site); + +} +``` + ]]> - Custom speech synthesizer implements using and work as filters or intermediaries between synthesizer applications constructed using the platform infrastructure through the members of the namespace and underlying system speech synthesis engines. - - A implementation: - -1. Traps or modify aspects of the incoming objects - -2. Generates any necessary events using the site reference to a instance - -3. Generates the actual synthesized speech. - - Generation of speech is most typically done by calling Speak on one of the speech rendering engines provided by the operating system. - - If one of the available speech rendering engines is not used, a object inheriting from must create its own speech rendering engine. - - Access to the Speak method on obtained using the registry and reflection. . - + Custom speech synthesizer implements using and work as filters or intermediaries between synthesizer applications constructed using the platform infrastructure through the members of the namespace and underlying system speech synthesis engines. + + A implementation: + +1. Traps or modify aspects of the incoming objects + +2. Generates any necessary events using the site reference to a instance + +3. Generates the actual synthesized speech. + + Generation of speech is most typically done by calling Speak on one of the speech rendering engines provided by the operating system. + + If one of the available speech rendering engines is not used, a object inheriting from must create its own speech rendering engine. + + Access to the Speak method on obtained using the registry and reflection. . + When you inherit from , you must override the following members: , , , , and . diff --git a/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml b/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml index 2cbc547fb96..d3c8ec99c8d 100644 --- a/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml +++ b/xml/System.Speech.Synthesis.TtsEngine/TtsEventId.xml @@ -24,35 +24,35 @@ Enumerates types of speech synthesis events. - . - - Specification is performed by setting the property of instances passed to the member of the class implementing the interface passed to the method on a custom speech engine's implementation of . - - The Speech platform infrastructure indicates the type of events it is currently handling through the property on the passed to the speak implementation. - - The value of is a bitmask, where the members of define the location of the bit corresponding to the event type. For example, WordBoundary has a value of five (5), meaning the fifth bit in the value returned by indicates if the site supports the event type. - - - -## Examples + . + + Specification is performed by setting the property of instances passed to the member of the class implementing the interface passed to the method on a custom speech engine's implementation of . + + The Speech platform infrastructure indicates the type of events it is currently handling through the property on the passed to the speak implementation. + + The value of is a bitmask, where the members of define the location of the bit corresponding to the event type. For example, WordBoundary has a value of five (5), meaning the fifth bit in the value returned by indicates if the site supports the event type. + + + +## Examples The following example is part of a custom speech synthesis implementation inheriting from , and using the , , , and classes. - + The implementation of includes the following steps: - -1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. - -2. If the property of each instance is equal to + +1. Receives an array of instances and creates a new array of instances to be passed to the `Speak` method on an underlying synthesis engine. + +2. If the property of each instance is equal to , the code does the following: - + - Translates American English to British English in the text to be spoken. - - - If the property provided to the implementation supports the `WordBoundary` event type, a instance is used to create an event to drive a synthesizer progress meter is created. - + + - If the property provided to the implementation supports the `WordBoundary` event type, a instance is used to create an event to drive a synthesizer progress meter is created. + 3. A speech rendering engine is then called with the modified array. - + ```csharp private const int WordBoundaryFlag = 1 << (int)TtsEventId.WordBoundary; private readonly char[] spaces = new char[] { ' ', '\t', '\r', '\n' }; @@ -65,7 +65,7 @@ internal struct UsVsUk override public void Speak (TextFragment [] frags, IntPtr wfx, ITtsEngineSite site) { TextFragment [] newFrags=new TextFragment[frags.Length]; - + for (int i=0;i diff --git a/xml/System.Speech.Synthesis/InstalledVoice.xml b/xml/System.Speech.Synthesis/InstalledVoice.xml index 081de0053ce..d3835ac1366 100644 --- a/xml/System.Speech.Synthesis/InstalledVoice.xml +++ b/xml/System.Speech.Synthesis/InstalledVoice.xml @@ -36,7 +36,7 @@ ## Remarks Use this class to get information about an installed voice, including its culture, name, gender, age, and whether it is enabled. - To perform text-to-speech using the language specified in the property, a speech synthesis engine that supports that language-country code must be installed. The speech synthesis engines that shipped with Microsoft Windows 7 work with the following language-country codes: + To perform text-to-speech using the language specified in the property, a speech synthesis engine that supports that language-country code must be installed. The speech synthesis engines that shipped with Microsoft Windows 7 work with the following language-country codes: - en-US. English (United States) @@ -151,7 +151,7 @@ namespace SampleSynthesis property is `true` by default. When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `false`. An application cannot select a voice whose property is `false`. Typically, applications will not set a voice's property. + The value of the property is `true` by default. When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `false`. An application cannot select a voice whose property is `false`. Typically, applications will not set a voice's property. ]]> diff --git a/xml/System.Speech.Synthesis/PromptBuilder.xml b/xml/System.Speech.Synthesis/PromptBuilder.xml index 6b15df088e1..d086263a914 100644 --- a/xml/System.Speech.Synthesis/PromptBuilder.xml +++ b/xml/System.Speech.Synthesis/PromptBuilder.xml @@ -129,7 +129,7 @@ public void MySimpleText () property. The object will attempt to select an installed voice that supports the language specified by the `culture` parameter to process the prompt. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. + This constructor sets the value for the property. The object will attempt to select an installed voice that supports the language specified by the `culture` parameter to process the prompt. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. @@ -1658,11 +1658,11 @@ public void ProperName() object will attempt to select an installed voice that supports the language specified by the property to process the prompt. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. + The object will attempt to select an installed voice that supports the language specified by the property to process the prompt. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. - A culture may also be specified within the prompt for discreet sections of content using the , , and methods. A culture specified for a portion of content using one of the above methods will override the property while in effect, and the will attempt to select an installed voice that supports the language specified by the `culture` parameter of the method. + A culture may also be specified within the prompt for discreet sections of content using the , , and methods. A culture specified for a portion of content using one of the above methods will override the property while in effect, and the will attempt to select an installed voice that supports the language specified by the `culture` parameter of the method. - To correctly pronounce words in the language specified by the property, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. + To correctly pronounce words in the language specified by the property, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. Microsoft Windows and the System.Speech API accept all valid language-country codes as values for `culture`. The TTS engines that shipped with Windows 7 support the following language-country codes: @@ -1954,7 +1954,7 @@ namespace SampleSynthesis ## Remarks Long prompts can be rendered more like human speech if they are broken into sentences and paragraphs. - The `culture` parameter for a paragraph can be different than the property of the object that contains it. While in effect, the value of the `culture` parameter will override the property. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the paragraph. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . + The `culture` parameter for a paragraph can be different than the property of the object that contains it. While in effect, the value of the `culture` parameter will override the property. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the paragraph. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. @@ -2105,9 +2105,9 @@ namespace SampleSynthesis ## Remarks Long prompts can be rendered more like human speech if they are broken into sentences and paragraphs. - The `culture` parameter for a sentence can be different than the `culture` parameter for the paragraph that contains the sentence or the property of the object that contains them. + The `culture` parameter for a sentence can be different than the `culture` parameter for the paragraph that contains the sentence or the property of the object that contains them. - While in effect, the value of the `culture` parameter will override the property and the `culture` parameter for the paragraph that contains the sentence. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the sentence. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . + While in effect, the value of the `culture` parameter will override the property and the `culture` parameter for the paragraph that contains the sentence. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the sentence. If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. @@ -2218,7 +2218,7 @@ namespace SampleSynthesis ## Remarks A voice represents an installed TTS engine. Use the methods and class to obtain the names and attributes of installed text-to-speech (TTS) voices that you can select. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot call any of the methods on a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot call any of the methods on a voice whose property is `False`. Typically, applications will not set a voice's property. ]]> @@ -2251,7 +2251,7 @@ namespace SampleSynthesis can be different than the property of the object that contains it. While in effect, the value of the `culture` parameter will override the property. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the content enclosed by and . If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . + The `culture` parameter for can be different than the property of the object that contains it. While in effect, the value of the `culture` parameter will override the property. The will attempt to select an installed voice that supports the language specified by the `culture` parameter to speak the content enclosed by and . If a voice with the specified culture is found, it will be used. If a voice with the specified culture cannot be found, the default voice will be used. To stop using the voice specified by , call . To correctly pronounce words in the language specified by the `culture` parameter, a speech synthesis (text-to-speech or TTS) engine that supports the language must be installed. An installed TTS engine is called a voice. To get information about which voices are installed for a specific culture, use the method. diff --git a/xml/System.Speech.Synthesis/PromptEmphasis.xml b/xml/System.Speech.Synthesis/PromptEmphasis.xml index 2503bcb5ead..71de61936c5 100644 --- a/xml/System.Speech.Synthesis/PromptEmphasis.xml +++ b/xml/System.Speech.Synthesis/PromptEmphasis.xml @@ -24,14 +24,14 @@ Enumerates values for levels of emphasis in prompts. - enumeration are used by the constructor, by the method, and by the method to specify the level of emphasis for spoken text. The property gets the emphasis for a object using a instance. - + enumeration are used by the constructor, by the method, and by the method to specify the level of emphasis for spoken text. The property gets the emphasis for a object using a instance. + > [!NOTE] -> The speech synthesis engines in Windows do not support variations in the emphasis of speech output at this time. Setting values for emphasis using a member of the enumeration will produce no audible change in the synthesized speech output. - +> The speech synthesis engines in Windows do not support variations in the emphasis of speech output at this time. Setting values for emphasis using a member of the enumeration will produce no audible change in the synthesized speech output. + ]]> diff --git a/xml/System.Speech.Synthesis/PromptRate.xml b/xml/System.Speech.Synthesis/PromptRate.xml index bd18a733bfa..6844ec6a187 100644 --- a/xml/System.Speech.Synthesis/PromptRate.xml +++ b/xml/System.Speech.Synthesis/PromptRate.xml @@ -24,11 +24,11 @@ Enumerates values for the speaking rate of prompts. - enumeration are used by the constructor, by the method, and by the method to specify the rate of speech for spoken text. The property gets the rate for a object using a instance. - + enumeration are used by the constructor, by the method, and by the method to specify the rate of speech for spoken text. The property gets the rate for a object using a instance. + ]]> diff --git a/xml/System.Speech.Synthesis/PromptVolume.xml b/xml/System.Speech.Synthesis/PromptVolume.xml index be4223b9694..da29c5561a4 100644 --- a/xml/System.Speech.Synthesis/PromptVolume.xml +++ b/xml/System.Speech.Synthesis/PromptVolume.xml @@ -24,11 +24,11 @@ Enumerates values for volume levels (loudness) in prompts. - enumeration are used by the constructor, by the method, and by the method to specify the volume level for spoken text. The property gets the volume for a object using a instance. - + enumeration are used by the constructor, by the method, and by the method to specify the volume level for spoken text. The property gets the volume for a object using a instance. + ]]> diff --git a/xml/System.Speech.Synthesis/SpeakProgressEventArgs.xml b/xml/System.Speech.Synthesis/SpeakProgressEventArgs.xml index 751d52ca9fe..7e88b9db259 100644 --- a/xml/System.Speech.Synthesis/SpeakProgressEventArgs.xml +++ b/xml/System.Speech.Synthesis/SpeakProgressEventArgs.xml @@ -25,79 +25,79 @@ Returns data from the event. - is created when the object raises the event. The raises this event for each new word that it speaks in a prompt using any of the , , , or methods. - - The returned data is based on the Speech Synthesis Markup Language (SSML) that the code generates. The values returned for include spaces and the characters and contents of the SSML tags generated by the code. - - - -## Examples - The following example demonstrates the information that is available from . Note how the , , , and methods affect the by their addition of **\

**, **\

**, **\**, and **\** tags to the generated SSML. Also, there are two entries in the output for "30%", one for each word to speak this number string (thirty percent). The and are the same for each entry and represent the characters "30%. However, the changes to reflect the speaking of the words "thirty" and "percent" by the . - -```csharp -using System; -using System.Speech.Synthesis; - -namespace SampleSynthesis -{ - class Program - { - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Configure the audio output. - synth.SetOutputToWaveFile(@"C:\test\weather.wav"); - - // Create a SoundPlayer instance to play the output audio file. - System.Media.SoundPlayer m_SoundPlayer = - new System.Media.SoundPlayer(@"C:\test\weather.wav"); - - // Build a prompt containing a paragraph and two sentences. - PromptBuilder builder = new PromptBuilder( - new System.Globalization.CultureInfo("en-US")); - builder.StartParagraph(); - builder.StartSentence(); - builder.AppendText( - "The weather forecast for today is partly cloudy with some sun breaks."); - builder.EndSentence(); - builder.StartSentence(); - builder.AppendText( - "Tonight's weather will be cloudy with a 30% chance of showers."); - builder.EndSentence(); - builder.EndParagraph(); - - // Add a handler for the SpeakProgress event. - synth.SpeakProgress += - new EventHandler(synth_SpeakProgress); - - // Speak the prompt and play back the output file. - synth.Speak(builder); - m_SoundPlayer.Play(); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // Write each word and its character position to the console. - static void synth_SpeakProgress(object sender, SpeakProgressEventArgs e) - { - Console.WriteLine("CharPos: {0} CharCount: {1} AudioPos: {2} \"{3}\"", - e.CharacterPosition, e.CharacterCount, e.AudioPosition, e.Text); - } - } -} - -``` - + is created when the object raises the event. The raises this event for each new word that it speaks in a prompt using any of the , , , or methods. + + The returned data is based on the Speech Synthesis Markup Language (SSML) that the code generates. The values returned for include spaces and the characters and contents of the SSML tags generated by the code. + + + +## Examples + The following example demonstrates the information that is available from . Note how the , , , and methods affect the by their addition of **\

**, **\

**, **\**, and **\** tags to the generated SSML. Also, there are two entries in the output for "30%", one for each word to speak this number string (thirty percent). The and are the same for each entry and represent the characters "30%. However, the changes to reflect the speaking of the words "thirty" and "percent" by the . + +```csharp +using System; +using System.Speech.Synthesis; + +namespace SampleSynthesis +{ + class Program + { + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Configure the audio output. + synth.SetOutputToWaveFile(@"C:\test\weather.wav"); + + // Create a SoundPlayer instance to play the output audio file. + System.Media.SoundPlayer m_SoundPlayer = + new System.Media.SoundPlayer(@"C:\test\weather.wav"); + + // Build a prompt containing a paragraph and two sentences. + PromptBuilder builder = new PromptBuilder( + new System.Globalization.CultureInfo("en-US")); + builder.StartParagraph(); + builder.StartSentence(); + builder.AppendText( + "The weather forecast for today is partly cloudy with some sun breaks."); + builder.EndSentence(); + builder.StartSentence(); + builder.AppendText( + "Tonight's weather will be cloudy with a 30% chance of showers."); + builder.EndSentence(); + builder.EndParagraph(); + + // Add a handler for the SpeakProgress event. + synth.SpeakProgress += + new EventHandler(synth_SpeakProgress); + + // Speak the prompt and play back the output file. + synth.Speak(builder); + m_SoundPlayer.Play(); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // Write each word and its character position to the console. + static void synth_SpeakProgress(object sender, SpeakProgressEventArgs e) + { + Console.WriteLine("CharPos: {0} CharCount: {1} AudioPos: {2} \"{3}\"", + e.CharacterPosition, e.CharacterCount, e.AudioPosition, e.Text); + } + } +} + +``` + ]]>
@@ -129,11 +129,11 @@ namespace SampleSynthesis Gets the audio position of the event. Returns the position of the event in the audio output stream. - normalizes numbers to the words that correspond to how the number will be spoken. For example, the synthesizer speaks the number "4003" as "four thousand three". It raises a event for each of the spoken words, and returns the for each word. - + normalizes numbers to the words that correspond to how the number will be spoken. For example, the synthesizer speaks the number "4003" as "four thousand three". It raises a event for each of the spoken words, and returns the for each word. + ]]>
@@ -165,11 +165,11 @@ namespace SampleSynthesis Gets the number of characters in the word that was spoken just before the event was raised. Returns the number of characters in the word that was spoken just before the event was raised. - normalizes numbers to the words that correspond to how the number will be spoken. For example, the synthesizer speaks the number "4003" as "four thousand three". It raises a event for each of the spoken words. However, the property for each of the three words is the same. It is the count of the characters in the number "4003" in the text of the prompt, in this case, four. - + normalizes numbers to the words that correspond to how the number will be spoken. For example, the synthesizer speaks the number "4003" as "four thousand three". It raises a event for each of the spoken words. However, the property for each of the three words is the same. It is the count of the characters in the number "4003" in the text of the prompt, in this case, four. + ]]>
@@ -201,118 +201,118 @@ namespace SampleSynthesis Gets the number of characters and spaces from the beginning of the prompt to the position before the first letter of the word that was just spoken. Returns the number of characters and spaces from the beginning of the prompt to the position before the first letter of the word that was just spoken. - includes the count for characters in XML tags, including their enclosing brackets. When using any of the , , , , or methods, the contents are added to an SSML prompt that includes the opening and closing `speak` elements. The opening `speak` element adds an offset of 82 characters and spaces to the of the all the words and letters in the prompt. For example, in the following snippet, the of the first word, "this", is 82. - -```csharp -builder.AppendText("This is a test"); -Synthesizer.Speak(builder); -``` - - In the above example the of the word "test" is 92. In the following snippet the of the word "test" is 23 characters higher (115) because the opening **\** tag that precedes it contains 23 characters and spaces (the two escape characters "\\" are not counted). - -```csharp -builder.AppendSsmlMarkup("This is a test ."); -Synthesizer.Speak(builder); -``` - - If you use the methods to add content to a prompt by specifying a file, the opening `xml` declaration and `speak` elements in the file are not used or counted. The first character in the file after the opening `speak` tag will be at position 82 if it is the first content in the prompt. - - By contrast, the string parameter of a method does not get added to an SSML prompt before being spoken. Therefore, the of the first word, "this", in the following snippet is zero. - -```csharp -Synthesizer.Speak("This is a test."); -``` - - The normalizes numbers to the words that correspond to how the number will be spoken. For example, the synthesizer speaks the number "4003" as "four thousand three". It raises a event for each of the three spoken words. However, the property for each of the three words is the same. It is the position before the first character of the number "4003" in the text of the prompt. - - - -## Examples - The following example creates a and appends the SSML contents of an XML file using . The example outputs speech to a WAV file for playback. The contents of the XML file containing the SSML appear below the code example. - -```csharp -using System; -using System.Xml; -using System.IO; -using System.Speech.Synthesis; - -namespace SampleSynthesis -{ - class Program - { - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Configure the audio output. - synth.SetOutputToDefaultAudioDevice(); - - // Create a path to the file that contains SSML. - string weatherFile = Path.GetFullPath("c:\\test\\Weather.ssml"); - - // Create an XML Reader from the file, create a PromptBuilder and - // append the XmlReader. - PromptBuilder builder = new PromptBuilder(); - - if (File.Exists(weatherFile)) - { - XmlReader reader = XmlReader.Create(weatherFile); - builder.AppendSsml(reader); - reader.Close(); - } - - // Add a handler for the SpeakProgress event. - synth.SpeakProgress += - new EventHandler(synth_SpeakProgress); - - // Speak the prompt and play back the output file. - synth.Speak(builder); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // Write each word and its character position to the console. - static void synth_SpeakProgress(object sender, SpeakProgressEventArgs e) - { - Console.WriteLine("Speak progress: {0} {1}", - e.CharacterPosition, e.Text); - } - } -} - -``` - -```xml - - - - - -

The weather forecast for today is partly cloudy with -some sun breaks.

- - - -

Tonight's weather will be cloudy with a 30% chance of -showers.

- -
- -``` - + includes the count for characters in XML tags, including their enclosing brackets. When using any of the , , , , or methods, the contents are added to an SSML prompt that includes the opening and closing `speak` elements. The opening `speak` element adds an offset of 82 characters and spaces to the of the all the words and letters in the prompt. For example, in the following snippet, the of the first word, "this", is 82. + +```csharp +builder.AppendText("This is a test"); +Synthesizer.Speak(builder); +``` + + In the above example the of the word "test" is 92. In the following snippet the of the word "test" is 23 characters higher (115) because the opening **\** tag that precedes it contains 23 characters and spaces (the two escape characters "\\" are not counted). + +```csharp +builder.AppendSsmlMarkup("This is a test ."); +Synthesizer.Speak(builder); +``` + + If you use the methods to add content to a prompt by specifying a file, the opening `xml` declaration and `speak` elements in the file are not used or counted. The first character in the file after the opening `speak` tag will be at position 82 if it is the first content in the prompt. + + By contrast, the string parameter of a method does not get added to an SSML prompt before being spoken. Therefore, the of the first word, "this", in the following snippet is zero. + +```csharp +Synthesizer.Speak("This is a test."); +``` + + The normalizes numbers to the words that correspond to how the number will be spoken. For example, the synthesizer speaks the number "4003" as "four thousand three". It raises a event for each of the three spoken words. However, the property for each of the three words is the same. It is the position before the first character of the number "4003" in the text of the prompt. + + + +## Examples + The following example creates a and appends the SSML contents of an XML file using . The example outputs speech to a WAV file for playback. The contents of the XML file containing the SSML appear below the code example. + +```csharp +using System; +using System.Xml; +using System.IO; +using System.Speech.Synthesis; + +namespace SampleSynthesis +{ + class Program + { + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Configure the audio output. + synth.SetOutputToDefaultAudioDevice(); + + // Create a path to the file that contains SSML. + string weatherFile = Path.GetFullPath("c:\\test\\Weather.ssml"); + + // Create an XML Reader from the file, create a PromptBuilder and + // append the XmlReader. + PromptBuilder builder = new PromptBuilder(); + + if (File.Exists(weatherFile)) + { + XmlReader reader = XmlReader.Create(weatherFile); + builder.AppendSsml(reader); + reader.Close(); + } + + // Add a handler for the SpeakProgress event. + synth.SpeakProgress += + new EventHandler(synth_SpeakProgress); + + // Speak the prompt and play back the output file. + synth.Speak(builder); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // Write each word and its character position to the console. + static void synth_SpeakProgress(object sender, SpeakProgressEventArgs e) + { + Console.WriteLine("Speak progress: {0} {1}", + e.CharacterPosition, e.Text); + } + } +} + +``` + +```xml + + + + + +

The weather forecast for today is partly cloudy with +some sun breaks.

+ + + +

Tonight's weather will be cloudy with a 30% chance of +showers.

+ +
+ +``` + ]]>
@@ -344,64 +344,64 @@ showers.

The text that was just spoken when the event was raised. Returns the text that was just spoken when the event was raised. - normalizes numbers to the words that correspond to how the number will be spoken. For example, the synthesizer speaks the number "4003" as "four thousand three". It raises a event for each of the spoken words. However, the property for each of the three words is the same. It is the text "4003" from the prompt. - - - -## Examples - The following example illustrates the how the event reports the and properties for strings that contain numbers. - -```csharp -using System; -using System.Xml; -using System.IO; -using System.Speech.Synthesis; - -namespace SampleSynthesis -{ - class Program - { - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Configure the audio output. - synth.SetOutputToDefaultAudioDevice(); - - // Create an XML Reader from the file, create a PromptBuilder and - // append the XmlReader. - PromptBuilder builder = new PromptBuilder(); - builder.AppendText("4003"); - - // Add a handler for the SpeakProgress event. - synth.SpeakProgress += - new EventHandler(synth_SpeakProgress); - - // Speak the prompt and play back the output file. - synth.Speak(builder); - } - - Console.WriteLine(); - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - - // Write each word and its character position to the console. - static void synth_SpeakProgress(object sender, SpeakProgressEventArgs e) - { - Console.WriteLine("Speak progress - Character position: {0} Text: {1}", - e.CharacterPosition, e.Text); - } - } -} -``` - + normalizes numbers to the words that correspond to how the number will be spoken. For example, the synthesizer speaks the number "4003" as "four thousand three". It raises a event for each of the spoken words. However, the property for each of the three words is the same. It is the text "4003" from the prompt. + + + +## Examples + The following example illustrates the how the event reports the and properties for strings that contain numbers. + +```csharp +using System; +using System.Xml; +using System.IO; +using System.Speech.Synthesis; + +namespace SampleSynthesis +{ + class Program + { + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Configure the audio output. + synth.SetOutputToDefaultAudioDevice(); + + // Create an XML Reader from the file, create a PromptBuilder and + // append the XmlReader. + PromptBuilder builder = new PromptBuilder(); + builder.AppendText("4003"); + + // Add a handler for the SpeakProgress event. + synth.SpeakProgress += + new EventHandler(synth_SpeakProgress); + + // Speak the prompt and play back the output file. + synth.Speak(builder); + } + + Console.WriteLine(); + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + + // Write each word and its character position to the console. + static void synth_SpeakProgress(object sender, SpeakProgressEventArgs e) + { + Console.WriteLine("Speak progress - Character position: {0} Text: {1}", + e.CharacterPosition, e.Text); + } + } +} +``` + ]]> diff --git a/xml/System.Speech.Synthesis/SpeechSynthesizer.xml b/xml/System.Speech.Synthesis/SpeechSynthesizer.xml index d506b1054aa..0768bf45574 100644 --- a/xml/System.Speech.Synthesis/SpeechSynthesizer.xml +++ b/xml/System.Speech.Synthesis/SpeechSynthesizer.xml @@ -413,7 +413,7 @@ namespace SampleSynthesis , the method verifies that each of the voices (engines for text-to-speech) it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices (engines for text-to-speech) it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. ]]> @@ -830,9 +830,9 @@ namespace SampleSynthesis method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. To select a voice, pass the entire contents of the property as the argument for the method. The object selects the first installed voice that contains `name` in the voice's property. The performs a case-sensitive, substring comparison to determine if the voice matches the `name`. + Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. To select a voice, pass the entire contents of the property as the argument for the method. The object selects the first installed voice that contains `name` in the voice's property. The performs a case-sensitive, substring comparison to determine if the voice matches the `name`. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. To select a voice by gender, age, or locale, use one of the methods. @@ -855,7 +855,7 @@ namespace SampleSynthesis ## Remarks Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object selects the first installed voice that matches the specified characteristics. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. To select a voice by name, use the method @@ -890,9 +890,9 @@ namespace SampleSynthesis method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object selects the first installed voice whose property matches the `gender` parameter. + Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object selects the first installed voice whose property matches the `gender` parameter. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. To select a voice based on other characteristics, see the other methods. @@ -936,7 +936,7 @@ namespace SampleSynthesis ## Remarks Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object selects the first installed voice whose and properties match the `gender` and `age` parameters. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. To select a voice based on other characteristics, see the other methods. @@ -983,7 +983,7 @@ namespace SampleSynthesis ## Remarks Use the method and class to obtain the names of installed text-to-speech (TTS) voices that you can select. The object finds installed voices whose and properties match the `gender` and `age` parameters. The counts the matches it finds, and returns the voice when the count equals the `voiceAlternate` parameter. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. To select a voice based on other characteristics, see the other overloads. @@ -1042,7 +1042,7 @@ namespace SampleSynthesis Two-letter language codes such as "en" are also permitted. - When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. + When an application calls , the method verifies that each of the voices it finds in the registry meets certain minimum criteria. For any voice that fails verification, sets its property to `False`. An application cannot select a voice whose property is `False`. Typically, applications will not set a voice's property. To select a voice based on other characteristics, see the other overloads. @@ -2419,7 +2419,7 @@ namespace SampleSynthesis after it changes, use the property of the class. + To get the new state of the after it changes, use the property of the class. diff --git a/xml/System.Speech.Synthesis/StateChangedEventArgs.xml b/xml/System.Speech.Synthesis/StateChangedEventArgs.xml index b6d2d50aa02..34879207c0a 100644 --- a/xml/System.Speech.Synthesis/StateChangedEventArgs.xml +++ b/xml/System.Speech.Synthesis/StateChangedEventArgs.xml @@ -25,71 +25,71 @@ Returns data from the event. - is created when the object raises the event. To obtain the values for the new and the previous , access the and properties in the handler for the event. - - - -## Examples - The following example demonstrates the information that is available about the event. - -```csharp -using System; -using System.Speech.Synthesis; - -namespace SampleSynthesis -{ - class Program - { - - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Configure the audio output. - synth.SetOutputToDefaultAudioDevice(); - - // Subscribe to StateChanged event. - synth.StateChanged += new EventHandler(synth_StateChanged); - - // Subscribe to the SpeakProgress event. - synth.SpeakProgress += new EventHandler(synth_SpeakProgress); - - // Speak the prompt. - synth.Speak("What is your favorite color?"); - - // Pause the SpeechSynthesizer object. - synth.Pause(); - - // Resume the SpeechSynthesizer object. - synth.Resume(); - } - - Console.WriteLine("\nPress any key to exit..."); - Console.ReadKey(); - } - - // Write the state of the SpeechSynthesizer to the console. - static void synth_StateChanged(object sender, StateChangedEventArgs e) - { - Console.WriteLine("State: {0} Previous State: {1}\n", e.State, e.PreviousState); - } - - // Write the speak progress of the SpeechSynthesizer to the console. - static void synth_SpeakProgress(object sender, SpeakProgressEventArgs e) - { - Console.WriteLine(e.Text); - } - } -} - -``` - + is created when the object raises the event. To obtain the values for the new and the previous , access the and properties in the handler for the event. + + + +## Examples + The following example demonstrates the information that is available about the event. + +```csharp +using System; +using System.Speech.Synthesis; + +namespace SampleSynthesis +{ + class Program + { + + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Configure the audio output. + synth.SetOutputToDefaultAudioDevice(); + + // Subscribe to StateChanged event. + synth.StateChanged += new EventHandler(synth_StateChanged); + + // Subscribe to the SpeakProgress event. + synth.SpeakProgress += new EventHandler(synth_SpeakProgress); + + // Speak the prompt. + synth.Speak("What is your favorite color?"); + + // Pause the SpeechSynthesizer object. + synth.Pause(); + + // Resume the SpeechSynthesizer object. + synth.Resume(); + } + + Console.WriteLine("\nPress any key to exit..."); + Console.ReadKey(); + } + + // Write the state of the SpeechSynthesizer to the console. + static void synth_StateChanged(object sender, StateChangedEventArgs e) + { + Console.WriteLine("State: {0} Previous State: {1}\n", e.State, e.PreviousState); + } + + // Write the speak progress of the SpeechSynthesizer to the console. + static void synth_SpeakProgress(object sender, SpeakProgressEventArgs e) + { + Console.WriteLine(e.Text); + } + } +} + +``` + ]]> @@ -121,11 +121,11 @@ namespace SampleSynthesis Gets the state of the before the event. Returns the state of the synthesizer before the state changed. - property represents the synthesizer state with a member of the enumeration. - + property represents the synthesizer state with a member of the enumeration. + ]]> @@ -157,11 +157,11 @@ namespace SampleSynthesis Gets the state of the before the event. The state of the synthesizer after the state changed. - property represents the synthesizer state with a member of the enumeration. - + property represents the synthesizer state with a member of the enumeration. + ]]> diff --git a/xml/System.Speech.Synthesis/SynthesizerEmphasis.xml b/xml/System.Speech.Synthesis/SynthesizerEmphasis.xml index 6002edbeba0..156fbea8b0f 100644 --- a/xml/System.Speech.Synthesis/SynthesizerEmphasis.xml +++ b/xml/System.Speech.Synthesis/SynthesizerEmphasis.xml @@ -30,11 +30,11 @@ Enumerates levels of synthesizer emphasis. - property uses `SynthesizerEmphasis` to describe the emphasis of a viseme when the event is raised. The property uses `SynthesizerEmphasis` to describe the emphasis of a phoneme when the event is raised. - + property uses `SynthesizerEmphasis` to describe the emphasis of a viseme when the event is raised. The property uses `SynthesizerEmphasis` to describe the emphasis of a phoneme when the event is raised. + ]]> diff --git a/xml/System.Speech.Synthesis/SynthesizerState.xml b/xml/System.Speech.Synthesis/SynthesizerState.xml index 4f82c707023..ba5a9ef0436 100644 --- a/xml/System.Speech.Synthesis/SynthesizerState.xml +++ b/xml/System.Speech.Synthesis/SynthesizerState.xml @@ -24,13 +24,13 @@ Enumerates values for the state of the . - property uses to indicate the current state of the . See for an example. - - The and properties use to indicate state of the when the event is raised. - + property uses to indicate the current state of the . See for an example. + + The and properties use to indicate state of the when the event is raised. + ]]> diff --git a/xml/System.Speech.Synthesis/VoiceAge.xml b/xml/System.Speech.Synthesis/VoiceAge.xml index 2e3a89e757a..18ef025a443 100644 --- a/xml/System.Speech.Synthesis/VoiceAge.xml +++ b/xml/System.Speech.Synthesis/VoiceAge.xml @@ -24,11 +24,11 @@ Defines the values for the age of a synthesized voice. - can indicate the age of an existing voice or an age preference when selecting a voice. Three of the methods and two of the methods use to specify the age when selecting a voice. The property obtains the age of an existing voice using a member. - + can indicate the age of an existing voice or an age preference when selecting a voice. Three of the methods and two of the methods use to specify the age when selecting a voice. The property obtains the age of an existing voice using a member. + ]]> diff --git a/xml/System.Speech.Synthesis/VoiceChangeEventArgs.xml b/xml/System.Speech.Synthesis/VoiceChangeEventArgs.xml index cca0e179573..8d3904ecd62 100644 --- a/xml/System.Speech.Synthesis/VoiceChangeEventArgs.xml +++ b/xml/System.Speech.Synthesis/VoiceChangeEventArgs.xml @@ -25,13 +25,13 @@ Returns data from the event. - is created when the object raises the event. To obtain the identity of the new , access the property in the handler for the event. - - You can change the voice in use by the with any of the 's methods or the 's or methods. - + is created when the object raises the event. To obtain the identity of the new , access the property in the handler for the event. + + You can change the voice in use by the with any of the 's methods or the 's or methods. + ]]> @@ -63,11 +63,11 @@ Gets the object of the new voice. Returns information that describes and identifies the new voice. - property gets the object when a event is raised. - + property gets the object when a event is raised. + ]]> diff --git a/xml/System.Speech.Synthesis/VoiceGender.xml b/xml/System.Speech.Synthesis/VoiceGender.xml index 34930857dc7..fdb9b72227f 100644 --- a/xml/System.Speech.Synthesis/VoiceGender.xml +++ b/xml/System.Speech.Synthesis/VoiceGender.xml @@ -24,11 +24,11 @@ Defines the values for the gender of a synthesized voice. - can indicate the gender of an existing voice or a gender preference when selecting a voice. All of the methods and three of the methods use to specify the gender when selecting a voice. The property obtains the gender of an existing voice using a member. - + can indicate the gender of an existing voice or a gender preference when selecting a voice. All of the methods and three of the methods use to specify the gender when selecting a voice. The property obtains the gender of an existing voice using a member. + ]]> diff --git a/xml/System.Speech.Synthesis/VoiceInfo.xml b/xml/System.Speech.Synthesis/VoiceInfo.xml index d91f31a4683..8d8c1ea546a 100644 --- a/xml/System.Speech.Synthesis/VoiceInfo.xml +++ b/xml/System.Speech.Synthesis/VoiceInfo.xml @@ -36,80 +36,80 @@ Represents an installed speech synthesis engine. - object uses a voice to generate speech from text. The properties of the object identify a voice and describe its characteristics. The most defining characteristic of a voice is its , which defines the single language that a voice can speak. - - The property returns a object that contains information about the current voice in use by the . You can also use a object to get information about any of the voices that are installed on the system, as returned by the method. See for more information. - - - -## Examples - The following example is part of a console application that initializes a object and outputs to the console a list of the installed voices (engines for speech synthesis) and demonstrates the information that is available for each voice. - -```csharp -using System; -using System.Speech.Synthesis; -using System.Speech.AudioFormat; - -namespace SampleSynthesis -{ - class Program - { - static void Main(string[] args) - { - - // Initialize a new instance of the SpeechSynthesizer. - using (SpeechSynthesizer synth = new SpeechSynthesizer()) - { - - // Output information about all of the installed voices. - Console.WriteLine("Installed voices -"); - foreach (InstalledVoice voice in synth.GetInstalledVoices()) - { - VoiceInfo info = voice.VoiceInfo; - string AudioFormats = ""; - foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) - { - AudioFormats += String.Format("{0}\n", - fmt.EncodingFormat.ToString()); - } - - Console.WriteLine(" Name: " + info.Name); - Console.WriteLine(" Culture: " + info.Culture); - Console.WriteLine(" Age: " + info.Age); - Console.WriteLine(" Gender: " + info.Gender); - Console.WriteLine(" Description: " + info.Description); - Console.WriteLine(" ID: " + info.Id); - Console.WriteLine(" Enabled: " + voice.Enabled); - if (info.SupportedAudioFormats.Count != 0) - { - Console.WriteLine( " Audio formats: " + AudioFormats); - } - else - { - Console.WriteLine(" No supported audio formats found"); - } - - string AdditionalInfo = ""; - foreach (string key in info.AdditionalInfo.Keys) - { - AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); - } - - Console.WriteLine(" Additional Info - " + AdditionalInfo); - Console.WriteLine(); - } - } - Console.WriteLine("Press any key to exit..."); - Console.ReadKey(); - } - } -} - -``` - + object uses a voice to generate speech from text. The properties of the object identify a voice and describe its characteristics. The most defining characteristic of a voice is its , which defines the single language that a voice can speak. + + The property returns a object that contains information about the current voice in use by the . You can also use a object to get information about any of the voices that are installed on the system, as returned by the method. See for more information. + + + +## Examples + The following example is part of a console application that initializes a object and outputs to the console a list of the installed voices (engines for speech synthesis) and demonstrates the information that is available for each voice. + +```csharp +using System; +using System.Speech.Synthesis; +using System.Speech.AudioFormat; + +namespace SampleSynthesis +{ + class Program + { + static void Main(string[] args) + { + + // Initialize a new instance of the SpeechSynthesizer. + using (SpeechSynthesizer synth = new SpeechSynthesizer()) + { + + // Output information about all of the installed voices. + Console.WriteLine("Installed voices -"); + foreach (InstalledVoice voice in synth.GetInstalledVoices()) + { + VoiceInfo info = voice.VoiceInfo; + string AudioFormats = ""; + foreach (SpeechAudioFormatInfo fmt in info.SupportedAudioFormats) + { + AudioFormats += String.Format("{0}\n", + fmt.EncodingFormat.ToString()); + } + + Console.WriteLine(" Name: " + info.Name); + Console.WriteLine(" Culture: " + info.Culture); + Console.WriteLine(" Age: " + info.Age); + Console.WriteLine(" Gender: " + info.Gender); + Console.WriteLine(" Description: " + info.Description); + Console.WriteLine(" ID: " + info.Id); + Console.WriteLine(" Enabled: " + voice.Enabled); + if (info.SupportedAudioFormats.Count != 0) + { + Console.WriteLine( " Audio formats: " + AudioFormats); + } + else + { + Console.WriteLine(" No supported audio formats found"); + } + + string AdditionalInfo = ""; + foreach (string key in info.AdditionalInfo.Keys) + { + AdditionalInfo += String.Format(" {0}: {1}\n", key, info.AdditionalInfo[key]); + } + + Console.WriteLine(" Additional Info - " + AdditionalInfo); + Console.WriteLine(); + } + } + Console.WriteLine("Press any key to exit..."); + Console.ReadKey(); + } + } +} + +``` + ]]> @@ -176,11 +176,11 @@ namespace SampleSynthesis Gets the age of the voice. Returns the age of the voice. - property gets a member of the enumeration that indicates the age of the voice. - + property gets a member of the enumeration that indicates the age of the voice. + ]]> @@ -214,11 +214,11 @@ namespace SampleSynthesis Gets the culture of the voice. Returns a object that provides information about a specific culture, such as the names of the culture, the writing system, the calendar used, and how to format dates and sort strings. - class specifies a unique name for each culture. The name is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region. Examples of culture names include "es-US" for Spanish as spoken in the US, or "fr-CA" for French as spoken in Canada. You can specify a neutral culture by using only the two-digit lowercase language code. For example, "fr" specifies the neutral culture for French, and "de" specifies the neutral culture for German. - + class specifies a unique name for each culture. The name is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an ISO 3166 two-letter uppercase subculture code associated with a country or region. Examples of culture names include "es-US" for Spanish as spoken in the US, or "fr-CA" for French as spoken in Canada. You can specify a neutral culture by using only the two-digit lowercase language code. For example, "fr" specifies the neutral culture for French, and "de" specifies the neutral culture for German. + ]]> @@ -272,11 +272,11 @@ namespace SampleSynthesis if the fields of the two objects are equal; otherwise, . - method takes a type as its parameter. If that object is not of the type, the method returns `False`. - + method takes a type as its parameter. If that object is not of the type, the method returns `False`. + ]]> @@ -308,11 +308,11 @@ namespace SampleSynthesis Gets the gender of the voice. Returns the gender of the voice. - property gets a member of the enumeration that indicates the gender of the voice. - + property gets a member of the enumeration that indicates the gender of the voice. + ]]> diff --git a/xml/System.Text.RegularExpressions/Capture.xml b/xml/System.Text.RegularExpressions/Capture.xml index 8582d38081e..5449f728c30 100644 --- a/xml/System.Text.RegularExpressions/Capture.xml +++ b/xml/System.Text.RegularExpressions/Capture.xml @@ -58,32 +58,32 @@ Represents the results from a single successful subexpression capture. - object is immutable and has no public constructor. Instances are returned through the object, which is returned by the `Match.Captures` and properties. However, the `Match.Captures` property provides information about the same match as the object. - - If you do not apply a quantifier to a capturing group, the property returns a with a single object that provides information about the same capture as the object. If you do apply a quantifier to a capturing group, the `Group.Index`, `Group.Length`, and `Group.Value` properties provide information only about the last captured group, whereas the objects in the provide information about all subexpression captures. The example provides an illustration. - - - -## Examples - The following example defines a regular expression that matches sentences that contain no punctuation except for a period ("."). + object is immutable and has no public constructor. Instances are returned through the object, which is returned by the `Match.Captures` and properties. However, the `Match.Captures` property provides information about the same match as the object. + + If you do not apply a quantifier to a capturing group, the property returns a with a single object that provides information about the same capture as the object. If you do apply a quantifier to a capturing group, the `Group.Index`, `Group.Length`, and `Group.Value` properties provide information only about the last captured group, whereas the objects in the provide information about all subexpression captures. The example provides an illustration. + + + +## Examples + The following example defines a regular expression that matches sentences that contain no punctuation except for a period ("."). :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Capture/Overview/example1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Capture/Overview/example1.vb" id="Snippet1"::: - - The regular expression pattern `((\w+)[\s.])+` is defined as shown in the following table. Note that in this regular expression, a quantifier (+) is applied to the entire regular expression. - -|Pattern|Description| -|-------------|-----------------| -|`(\w+)`|Match one or more word characters. This is the second capturing group.| -|`[\s.])`|Match a white-space character or period (".").| -|`((\w+)[\s.])`|Match one or more word characters followed by a white-space character or period ("."). This is the first capturing group.| -|`((\w+)[\s.])+`|Match one or more occurrences of a word character or characters followed by a white-space character or period (".").| - - In this example, the input string consists of two sentences. As the output shows, the first sentence consists of only one word, so the object has a single object that represents the same capture as the object. The second sentence consists of multiple words, so the objects only contain information about the last matched subexpression. Group 1, which represents the first capture, contains the last word in the sentence that has a closing period. Group 2, which represents the second capture, contains the last word in the sentence. However, the objects in the group's object capture each subexpression match. The objects in the first capturing group's collection of captures contain information about each captured word and white-space character or period. The objects in the second capturing group's collection of captures contain information about each captured word. - + :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Capture/Overview/example1.vb" id="Snippet1"::: + + The regular expression pattern `((\w+)[\s.])+` is defined as shown in the following table. Note that in this regular expression, a quantifier (+) is applied to the entire regular expression. + +|Pattern|Description| +|-------------|-----------------| +|`(\w+)`|Match one or more word characters. This is the second capturing group.| +|`[\s.])`|Match a white-space character or period (".").| +|`((\w+)[\s.])`|Match one or more word characters followed by a white-space character or period ("."). This is the first capturing group.| +|`((\w+)[\s.])+`|Match one or more occurrences of a word character or characters followed by a white-space character or period (".").| + + In this example, the input string consists of two sentences. As the output shows, the first sentence consists of only one word, so the object has a single object that represents the same capture as the object. The second sentence consists of multiple words, so the objects only contain information about the last matched subexpression. Group 1, which represents the first capture, contains the last word in the sentence that has a closing period. Group 2, which represents the second capture, contains the last word in the sentence. However, the objects in the group's object capture each subexpression match. The objects in the first capturing group's collection of captures contain information about each captured word and white-space character or period. The objects in the second capturing group's collection of captures contain information about each captured word. + ]]> @@ -244,11 +244,11 @@ Retrieves the captured substring from the input string by calling the property. The substring that was captured by the match. - property. - + property. + ]]> @@ -303,48 +303,48 @@ Gets the captured substring from the input string. The substring that is captured by the match. - or method fails to find a match, the value of the returned `Match.Value` property is . If the regular expression engine is unable to match a capturing group. the value of the returned `Group.Value` property is . See the second example for an illustration. - - - -## Examples - The following example defines a regular expression that matches sentences that contain no punctuation except for a period ("."). The `Match.Value` property displays the result string, which consists of a matched sentence, for each match. The `Group.Value` property displays the result string for each capturing group; it consists of the last string captured by that capturing group. The property displays the result string for each capture. - + or method fails to find a match, the value of the returned `Match.Value` property is . If the regular expression engine is unable to match a capturing group. the value of the returned `Group.Value` property is . See the second example for an illustration. + + + +## Examples + The following example defines a regular expression that matches sentences that contain no punctuation except for a period ("."). The `Match.Value` property displays the result string, which consists of a matched sentence, for each match. The `Group.Value` property displays the result string for each capturing group; it consists of the last string captured by that capturing group. The property displays the result string for each capture. + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Capture/Overview/example1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Capture/Overview/example1.vb" id="Snippet1"::: - - The regular expression pattern `((\w+)[\s.])+` is defined as shown in the following table. Note that in this regular expression, a quantifier (+) is applied to the entire regular expression. - -|Pattern|Description| -|-------------|-----------------| -|`(\w+)`|Match one or more word characters. This is the second capturing group.| -|`[\s.])`|Match a white-space character or period (".").| -|`((\w+)[\s.])`|Match one or more word characters followed by a white-space character or period ("."). This is the first capturing group.| -|`((\w+)[\s.])+`|Match one or more occurrences of a word character or characters followed by a white-space character or period (".").| - - In this example, the input string consists of two sentences. As the output shows, the first sentence consists of only one word, so the object has a single object that represents the same capture as the object. The second sentence consists of multiple words, so the objects only contain information about the last matched subexpression. Group 1, which represents the first capture, contains the last word in the sentence that has a closing period. Group 2, which represents the second capture, contains the last word in the sentence. However, the objects in the group's object capture each subexpression match. The objects in the first capturing group's collection of captures contain information about each captured word and white-space character or period. The objects in the second capturing group's collection of captures contain information about each captured word. - - The following example uses a regular expression pattern, `^([a-z]+)(\d+)*\.([a-z]+(\d)*)$`, to match a product number that consists of two parts separated by a period. Both parts consist of alphabetic characters followed by optional numbers. Because the first input string does not match the pattern, the value of the returned object's `Value` property is . Similarly, when the regular expression pattern is unable to match a capturing group, the value of the corresponding object's `Value` property is . - + :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Capture/Overview/example1.vb" id="Snippet1"::: + + The regular expression pattern `((\w+)[\s.])+` is defined as shown in the following table. Note that in this regular expression, a quantifier (+) is applied to the entire regular expression. + +|Pattern|Description| +|-------------|-----------------| +|`(\w+)`|Match one or more word characters. This is the second capturing group.| +|`[\s.])`|Match a white-space character or period (".").| +|`((\w+)[\s.])`|Match one or more word characters followed by a white-space character or period ("."). This is the first capturing group.| +|`((\w+)[\s.])+`|Match one or more occurrences of a word character or characters followed by a white-space character or period (".").| + + In this example, the input string consists of two sentences. As the output shows, the first sentence consists of only one word, so the object has a single object that represents the same capture as the object. The second sentence consists of multiple words, so the objects only contain information about the last matched subexpression. Group 1, which represents the first capture, contains the last word in the sentence that has a closing period. Group 2, which represents the second capture, contains the last word in the sentence. However, the objects in the group's object capture each subexpression match. The objects in the first capturing group's collection of captures contain information about each captured word and white-space character or period. The objects in the second capturing group's collection of captures contain information about each captured word. + + The following example uses a regular expression pattern, `^([a-z]+)(\d+)*\.([a-z]+(\d)*)$`, to match a product number that consists of two parts separated by a period. Both parts consist of alphabetic characters followed by optional numbers. Because the first input string does not match the pattern, the value of the returned object's `Value` property is . Similarly, when the regular expression pattern is unable to match a capturing group, the value of the corresponding object's `Value` property is . + :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Capture/Value/value1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Capture/Value/value1.vb" id="Snippet1"::: - - The regular expression pattern is defined as shown in the following table: - -|Pattern|Description| -|-------------|-----------------| -|`^`|Begin the match at the beginning of the string.| -|`([a-z]+)`|Match one or more occurrences of any character from a to z. Because the regular expression engine is passed the option, this comparison is case-insensitive. This is the first capturing group.| -|`(\d+)?`|Match zero or one occurrence of one or more decimal digits. This is the second capturing group.| -|`\.`|Match a literal period character.| -|`([a-z]+`|Match one or more occurrences of any character from a to z. The comparison is case-insensitive.| -|`(\d)*`|Match zero or more decimal digits. A single matched digit is the fourth capturing group.| -|`([a-z]+(\d)*)`|Match one or more alphabetic characters from a to z followed by zero, one, or more decimal digits. This is the fourth capturing group.| -|`$`|Conclude the match at the end of the string.| - + :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Capture/Value/value1.vb" id="Snippet1"::: + + The regular expression pattern is defined as shown in the following table: + +|Pattern|Description| +|-------------|-----------------| +|`^`|Begin the match at the beginning of the string.| +|`([a-z]+)`|Match one or more occurrences of any character from a to z. Because the regular expression engine is passed the option, this comparison is case-insensitive. This is the first capturing group.| +|`(\d+)?`|Match zero or one occurrence of one or more decimal digits. This is the second capturing group.| +|`\.`|Match a literal period character.| +|`([a-z]+`|Match one or more occurrences of any character from a to z. The comparison is case-insensitive.| +|`(\d)*`|Match zero or more decimal digits. A single matched digit is the fourth capturing group.| +|`([a-z]+(\d)*)`|Match one or more alphabetic characters from a to z followed by zero, one, or more decimal digits. This is the fourth capturing group.| +|`$`|Conclude the match at the end of the string.| + ]]> diff --git a/xml/System.Text.RegularExpressions/CaptureCollection.xml b/xml/System.Text.RegularExpressions/CaptureCollection.xml index cafc37da234..296b3bb2b27 100644 --- a/xml/System.Text.RegularExpressions/CaptureCollection.xml +++ b/xml/System.Text.RegularExpressions/CaptureCollection.xml @@ -109,7 +109,7 @@ Instances of the class are returned by the following properties: -- The property. Each member of the collection represents a substring captured by a capturing group. If a quantifier is not applied to a capturing group, the includes a single object that represents the same captured substring as the object. If a quantifier is applied to a capturing group, the includes one object for each captured substring, and the object provides information only about the last captured substring. +- The property. Each member of the collection represents a substring captured by a capturing group. If a quantifier is not applied to a capturing group, the includes a single object that represents the same captured substring as the object. If a quantifier is applied to a capturing group, the includes one object for each captured substring, and the object provides information only about the last captured substring. - The `Match.Captures` property. In this case, the collection consists of a single object that provides information about the match as a whole. That is, the object provides the same information as the object. @@ -118,7 +118,7 @@ ## Examples - The following example compares the objects in the object returned by the and `Match.Captures` properties. It also compares objects with the objects in the returned by the property. The example uses the following two regular expressions to find matches in a single input string: + The following example compares the objects in the object returned by the and `Match.Captures` properties. It also compares objects with the objects in the returned by the property. The example uses the following two regular expressions to find matches in a single input string: - `\b\w+\W{1,2}` @@ -126,7 +126,7 @@ - `(\b\w+\W{1,2})+` - This regular expression pattern identifies the words in a sentence. The pattern defines a single capturing group that consists of one or more word characters followed by one or two non-word characters. The regular expression pattern uses the `+` quantifier to match one or more occurrences of this group. The output from this example shows that the object and the object returned by the `Match.Captures` property contain information about the same match. The second object, which corresponds to the only capturing group in the regular expression, identifies only the last captured string, whereas the object returned by the first capturing group's property includes all captured substrings. + This regular expression pattern identifies the words in a sentence. The pattern defines a single capturing group that consists of one or more word characters followed by one or two non-word characters. The regular expression pattern uses the `+` quantifier to match one or more occurrences of this group. The output from this example shows that the object and the object returned by the `Match.Captures` property contain information about the same match. The second object, which corresponds to the only capturing group in the regular expression, identifies only the last captured string, whereas the object returned by the first capturing group's property includes all captured substrings. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/CaptureCollection/Overview/capturecollectionex1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/CaptureCollection/Overview/capturecollectionex1.vb" id="Snippet1"::: @@ -418,7 +418,7 @@ ## Remarks -A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. +A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. ]]> @@ -473,7 +473,7 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks > [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. ]]> @@ -596,7 +596,7 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks > [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. ]]> @@ -821,7 +821,7 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks -The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. +The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . returns the same object until is called again as 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. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. @@ -977,7 +977,7 @@ If an object occurs multiple times in the list, the property. Visual Basic implements as a [default](/dotnet/visual-basic/language-reference/modifiers/default) property, which provides the same indexing functionality. + 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](/dotnet/visual-basic/language-reference/modifiers/default) property, which provides the same indexing functionality. ]]>
@@ -1504,7 +1504,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - 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. + 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. ]]>
diff --git a/xml/System.Text.RegularExpressions/Group.xml b/xml/System.Text.RegularExpressions/Group.xml index 9cc9deb2754..64964c64b43 100644 --- a/xml/System.Text.RegularExpressions/Group.xml +++ b/xml/System.Text.RegularExpressions/Group.xml @@ -65,9 +65,9 @@ property. Information about the last substring captured can be accessed directly from the `Value` and `Index` properties. (That is, the instance is equivalent to the last item of the collection returned by the property, which reflects the last capture made by the capturing group.) + A capturing group can capture zero, one, or more strings in a single match because of quantifiers. (For more information, see [Quantifiers](/dotnet/standard/base-types/quantifiers-in-regular-expressions).) All the substrings matched by a single capturing group are available from the property. Information about the last substring captured can be accessed directly from the `Value` and `Index` properties. (That is, the instance is equivalent to the last item of the collection returned by the property, which reflects the last capture made by the capturing group.) - An example helps to clarify this relationship between a object and the that is returned by the property. The regular expression pattern `(\b(\w+?)[,:;]?\s?)+[?.!]` matches entire sentences. The regular expression is defined as shown in the following table. + An example helps to clarify this relationship between a object and the that is returned by the property. The regular expression pattern `(\b(\w+?)[,:;]?\s?)+[?.!]` matches entire sentences. The regular expression is defined as shown in the following table. |Pattern|Description| |-------------|-----------------| @@ -78,7 +78,7 @@ |`(\b(\w+?)[,:;]?\s?)+`|Match the pattern consisting of a word boundary, one or more word characters, a punctuation symbol, and a white-space character one or more times. This is the first capturing group.| |`[?.!]`|Match any occurrence of a period, question mark, or exclamation point.| - In this regular expression pattern, the subpattern `(\w+?)` is designed to match multiple words within a sentence. However, the value of the object represents only the last match that `(\w+?)` captures, whereas the property returns a that represents all captured text. As the output shows, the for the second capturing group contains four objects. The last of these corresponds to the object. + In this regular expression pattern, the subpattern `(\w+?)` is designed to match multiple words within a sentence. However, the value of the object represents only the last match that `(\w+?)` captures, whereas the property returns a that represents all captured text. As the output shows, the for the second capturing group contains four objects. The last of these corresponds to the object. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Group/Overview/groupandcaptures1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Group/Overview/groupandcaptures1.vb" id="Snippet1"::: @@ -134,12 +134,12 @@ property contains a single object that provides information about the same substring as the object. This is illustrated in the following example. It defines a regular expression, `\b(\w+)\b`, that extracts a single word from a sentence. The object captures the word "This", and the single object in the contains information about the same capture. + If a quantifier is not applied to a capturing group, the collection returned by the property contains a single object that provides information about the same substring as the object. This is illustrated in the following example. It defines a regular expression, `\b(\w+)\b`, that extracts a single word from a sentence. The object captures the word "This", and the single object in the contains information about the same capture. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Group/Captures/captures1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Group/Captures/captures1.vb" id="Snippet1"::: - The real utility of the property occurs when a quantifier is applied to a capturing group so that the group captures multiple substrings in a single regular expression. In this case, the object contains information about the last captured substring, whereas the property contains information about all the substrings captured by the group. In the following example, the regular expression `\b(\w+\s*)+\.` matches an entire sentence that ends in a period. The group `(\w+\s*)+` captures the individual words in the collection. Because the collection contains information only about the last captured substring, it captures the last word in the sentence, "sentence". However, each word captured by the group is available from the collection returned by the property. + The real utility of the property occurs when a quantifier is applied to a capturing group so that the group captures multiple substrings in a single regular expression. In this case, the object contains information about the last captured substring, whereas the property contains information about all the substrings captured by the group. In the following example, the regular expression `\b(\w+\s*)+\.` matches an entire sentence that ends in a period. The group `(\w+\s*)+` captures the individual words in the collection. Because the collection contains information only about the last captured substring, it captures the last word in the sentence, "sentence". However, each word captured by the group is available from the collection returned by the property. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Group/Captures/captures2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Group/Captures/captures2.vb" id="Snippet2"::: diff --git a/xml/System.Text.RegularExpressions/GroupCollection.xml b/xml/System.Text.RegularExpressions/GroupCollection.xml index 78a952e0ad8..deb4873af27 100644 --- a/xml/System.Text.RegularExpressions/GroupCollection.xml +++ b/xml/System.Text.RegularExpressions/GroupCollection.xml @@ -125,9 +125,9 @@ class is a zero-based collection class that consists of one or more objects that provide information about captured groups in a regular expression match. The collection is immutable (read-only) and has no public constructor. A object is returned by the property. + The class is a zero-based collection class that consists of one or more objects that provide information about captured groups in a regular expression match. The collection is immutable (read-only) and has no public constructor. A object is returned by the property. - The collection contains one or more objects. If the match is successful, the first element in the collection contains the object that corresponds to the entire match. Each subsequent element represents a captured group, if the regular expression includes capturing groups. Matches from numbered (unnamed) capturing groups appear in numeric order before matches from named capturing groups. If the match is unsuccessful, the collection contains a single object whose property is `false` and whose property equals . For more information, see the "Grouping Constructs and Regular Expression Objects" section in the [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions) article. + The collection contains one or more objects. If the match is successful, the first element in the collection contains the object that corresponds to the entire match. Each subsequent element represents a captured group, if the regular expression includes capturing groups. Matches from numbered (unnamed) capturing groups appear in numeric order before matches from named capturing groups. If the match is unsuccessful, the collection contains a single object whose property is `false` and whose property equals . For more information, see the "Grouping Constructs and Regular Expression Objects" section in the [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions) article. To iterate through the members of the collection, you should use the collection iteration construct provided by your language (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) instead of retrieving the enumerator that is returned by the method. In addition, you can access individual numbered captured groups from the property (the indexer in C#), and you can access individual named captured groups from the property. Note that you can retrieve an array that contains the numbers and names of all capturing groups by calling the and methods, respectively. Both are instance methods and require that you instantiate a object that represents the regular expression to be matched. @@ -385,7 +385,7 @@ object always has at least one member. If a match is unsuccessful, the property returns a object that contains a single member. + The object always has at least one member. If a match is unsuccessful, the property returns a object that contains a single member. ]]> @@ -497,7 +497,7 @@ ## Remarks -A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. +A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. ]]> @@ -552,7 +552,7 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks > [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. ]]> @@ -636,11 +636,11 @@ A collection that is read-only does not allow the addition or removal of element You can also use this property to retrieve individual captured groups by their index number. You can retrieve an array that contains the numbers of all capturing groups in a regular expression by calling the instance method. You can also map named capturing groups to their numbers by calling the instance method. - You can determine the number of items in the collection by retrieving the value of the property. Valid values for the `groupnum` parameter range from 0 to one less than the number of items in the collection. + You can determine the number of items in the collection by retrieving the value of the property. Valid values for the `groupnum` parameter range from 0 to one less than the number of items in the collection. - The object returned by the property always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the single object in the collection has its property set to `false` and its `Group.Value` property set to . + The object returned by the property always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the single object in the collection has its property set to `false` and its `Group.Value` property set to . - If `groupnum` is not the index of a member of the collection, or if `groupnum` is the index of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . + If `groupnum` is not the index of a member of the collection, or if `groupnum` is the index of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . @@ -719,7 +719,7 @@ A collection that is read-only does not allow the addition or removal of element You can retrieve the names of all the captured groups in a object by calling the method. You can also map the numbers of capturing groups in a regular expression to their names by calling the method. Individual names from the array can then be passed to the property to retrieve the captured string. - If `groupname` is not the name of a capturing group in the collection, or if `groupname` is the name of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . + If `groupname` is not the name of a capturing group in the collection, or if `groupname` is the name of a capturing group that has not been matched in the input string, the method returns a object whose property is `false` and whose `Group.Value` property is . @@ -780,7 +780,7 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks -The order of the keys in the enumerable collection is unspecified, but the implementation must guarantee that the keys are in the same order as the corresponding values in the enumerable collection that is returned by the property. +The order of the keys in the enumerable collection is unspecified, but the implementation must guarantee that the keys are in the same order as the corresponding values in the enumerable collection that is returned by the property. ]]> @@ -840,7 +840,7 @@ The order of the keys in the enumerable collection is unspecified, but the imple ## Remarks > [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. ]]>
diff --git a/xml/System.Text.RegularExpressions/Match.xml b/xml/System.Text.RegularExpressions/Match.xml index 5e0eb7e0064..2148dfe122b 100644 --- a/xml/System.Text.RegularExpressions/Match.xml +++ b/xml/System.Text.RegularExpressions/Match.xml @@ -69,14 +69,14 @@ If the method fails to match a regular expression pattern in an input string, it returns an empty object. You can then use a `foreach` construct in C# or a `For Each` construct in Visual Basic to iterate the collection. - If the method fails to match the regular expression pattern, it returns a object that is equal to . You can use the property to determine whether the match was successful. The following example provides an illustration. + If the method fails to match the regular expression pattern, it returns a object that is equal to . You can use the property to determine whether the match was successful. The following example provides an illustration. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Overview/Match1.cs" interactive="try-dotnet-method" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Match/Overview/Match1.vb" id="Snippet1"::: - If a pattern match is successful, the property contains the matched substring, the property indicates the zero-based starting position of the matched substring in the input string, and the property indicates the length of matched substring in the input string. + If a pattern match is successful, the property contains the matched substring, the property indicates the zero-based starting position of the matched substring in the input string, and the property indicates the length of matched substring in the input string. - Because a single match can involve multiple capturing groups, has a property that returns the . The instance itself is equivalent to the first object in the collection, at `Match.Groups[0]` (`Match.Groups(0)` in Visual Basic), which represents the entire match. You can access the captured groups in a match in the following ways: + Because a single match can involve multiple capturing groups, has a property that returns the . The instance itself is equivalent to the first object in the collection, at `Match.Groups[0]` (`Match.Groups(0)` in Visual Basic), which represents the entire match. You can access the captured groups in a match in the following ways: - You can iterate the members of the object by using a `foreach` (C#) or `For Each` (Visual Basic) construct. @@ -219,17 +219,17 @@ The following examples use the regular expression `Console\.Write(Line)?`. The r property provides access to information about those subexpression matches. For example, the regular expression pattern `(\d{3})-(\d{3}-\d{4})`, which matches North American telephone numbers, has two subexpressions. The first consists of the area code, which composes the first three digits of the telephone number. This group is captured by the first portion of the regular expression, `(\d{3})`. The second consists of the individual telephone number, which composes the last seven digits of the telephone number. This group is captured by the second portion of the regular expression, `(\d{3}-\d{4})`. These two groups can then be retrieved from the object that is returned by the property, as the following example shows. + A regular expression pattern can include subexpressions, which are defined by enclosing a portion of the regular expression pattern in parentheses. Every such subexpression forms a group. The property provides access to information about those subexpression matches. For example, the regular expression pattern `(\d{3})-(\d{3}-\d{4})`, which matches North American telephone numbers, has two subexpressions. The first consists of the area code, which composes the first three digits of the telephone number. This group is captured by the first portion of the regular expression, `(\d{3})`. The second consists of the individual telephone number, which composes the last seven digits of the telephone number. This group is captured by the second portion of the regular expression, `(\d{3}-\d{4})`. These two groups can then be retrieved from the object that is returned by the property, as the following example shows. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Groups/groups1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Match/Groups/groups1.vb" id="Snippet1"::: - The object returned by the property is a zero-based collection object that always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the property of the single object in the collection (the object at index 0) is set to `false` and the object's property is set to . If the regular expression engine can find a match, the first element of the object (the element at index 0) returned by the property contains a string that matches the entire regular expression pattern. Each subsequent element, from index one upward, represents a captured group, if the regular expression includes capturing groups. For more information, see the "Grouping Constructs and Regular Expression Objects" section of the [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions) article. + The object returned by the property is a zero-based collection object that always has at least one member. If the regular expression engine cannot find any matches in a particular input string, the property of the single object in the collection (the object at index 0) is set to `false` and the object's property is set to . If the regular expression engine can find a match, the first element of the object (the element at index 0) returned by the property contains a string that matches the entire regular expression pattern. Each subsequent element, from index one upward, represents a captured group, if the regular expression includes capturing groups. For more information, see the "Grouping Constructs and Regular Expression Objects" section of the [Grouping Constructs](/dotnet/standard/base-types/grouping-constructs-in-regular-expressions) article. ## Examples - The following example attempts to match a regular expression pattern against a sample string. The example uses the property to store information that is retrieved by the match for display to the console. + The following example attempts to match a regular expression pattern against a sample string. The example uses the property to store information that is retrieved by the match for display to the console. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/Match/Groups/snippet8.cs" id="Snippet8"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Match/Groups/snippet8.vb" id="Snippet8"::: diff --git a/xml/System.Text.RegularExpressions/MatchCollection.xml b/xml/System.Text.RegularExpressions/MatchCollection.xml index cfd2d06a9d9..a4a0f059578 100644 --- a/xml/System.Text.RegularExpressions/MatchCollection.xml +++ b/xml/System.Text.RegularExpressions/MatchCollection.xml @@ -107,13 +107,13 @@ ## Remarks The collection is immutable (read-only) and has no public constructor. The method returns a object. - The collection contains zero or more objects. If the match is successful, the collection is populated with one object for each match found in the input string. If the match is unsuccessful, the collection contains no objects, and its property equals zero. + The collection contains zero or more objects. If the match is successful, the collection is populated with one object for each match found in the input string. If the match is unsuccessful, the collection contains no objects, and its property equals zero. When applying a regular expression pattern to a particular input string, the regular expression engine uses either of two techniques to build the object: - Direct evaluation. - The object is populated all at once, with all matches resulting from a particular call to the method. This technique is used when the collection's property is accessed. It typically is the more expensive method of populating the collection and entails a greater performance hit. + The object is populated all at once, with all matches resulting from a particular call to the method. This technique is used when the collection's property is accessed. It typically is the more expensive method of populating the collection and entails a greater performance hit. - Lazy evaluation. @@ -301,14 +301,14 @@ object by retrieving the value of the collection's property causes the regular expression engine to populate the collection using direct evaluation. ln contrast, calling the method (or using the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. Direct evaluation can be a much more expensive method of building the collection than lazy evaluation. + Accessing individual members of the object by retrieving the value of the collection's property causes the regular expression engine to populate the collection using direct evaluation. ln contrast, calling the method (or using the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. Direct evaluation can be a much more expensive method of building the collection than lazy evaluation. Because the object is generally populated by using lazy evaluation, trying to determine the number of elements in the collection before it has been fully populated may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a single match exceeds that time-out interval. ## Examples - The following example uses the property to determine whether the call to the method found any matches. If not, it indicates that no matches were found. Otherwise, it enumerates the matches and displays their value and the position in the input string at which they were found. + The following example uses the property to determine whether the call to the method found any matches. If not, it indicates that no matches were found. Otherwise, it enumerates the matches and displays their value and the position in the input string at which they were found. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/MatchCollection/Count/countex1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/MatchCollection/Count/countex1.vb" id="Snippet1"::: @@ -373,7 +373,7 @@ ## Remarks Instead of calling the method to retrieve an enumerator that lets you iterate through the objects in the collection, you should use the group iteration construct (such as `foreach` in C# and `For Each`…`Next` in Visual Basic) provided by your programming language. - Iterating the members of the object using the method (or the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. This is analogous to repeatedly calling the method, and then adding the resulting match to the object. In contrast, the regular expression engine uses direct evaluation to populate the collection all at once when the property is accessed. This can be a much more expensive method of building the collection than lazy evaluation. + Iterating the members of the object using the method (or the `foreach` statement in C# and the `For Each`...`Next` statement in Visual Basic) causes the regular expression engine to populate the collection on an as needed basis using lazy evaluation. This is analogous to repeatedly calling the method, and then adding the resulting match to the object. In contrast, the regular expression engine uses direct evaluation to populate the collection all at once when the property is accessed. This can be a much more expensive method of building the collection than lazy evaluation. Because the object is generally populated by using lazy evaluation, trying to navigate to the next member of the collection may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find the next match exceeds that time-out interval. @@ -431,7 +431,7 @@ ## Remarks -A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. +A collection that is read-only does not allow the addition or removal of elements after the collection is created. Note that read-only in this context does not indicate whether individual elements of the collection can be modified, since the interface only supports addition and removal operations. For example, the property of an array that is cast or converted to an object returns `true`, even though individual array elements can be modified. ]]> @@ -486,7 +486,7 @@ A collection that is read-only does not allow the addition or removal of element ## Remarks > [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. ]]> @@ -547,16 +547,16 @@ A collection that is read-only does not allow the addition or removal of element property is an indexer; it is not explicitly referenced in code, but instead allows the collection to be accessed as if it were an array. + In C#, the property is an indexer; it is not explicitly referenced in code, but instead allows the collection to be accessed as if it were an array. - Typically, individual items in the object are accessed by their index only after the total number of items in the collection has been determined from the property. However, accessing the property causes the regular expression engine to use direct evaluation to build the collection all at once. This is typically more expensive than iterating the collection using the method, the C# `foreach` statement, or the Visual Basic `For Each`...`Next` statement. + Typically, individual items in the object are accessed by their index only after the total number of items in the collection has been determined from the property. However, accessing the property causes the regular expression engine to use direct evaluation to build the collection all at once. This is typically more expensive than iterating the collection using the method, the C# `foreach` statement, or the Visual Basic `For Each`...`Next` statement. Because the object is generally populated by using lazy evaluation, trying to navigate to a specific match may throw a exception. This exception can be thrown if a time-out value for matching operations is in effect, and the attempt to find a specific match exceeds that time-out interval. ## Examples - The following example parses the first sentence of Nathaniel Hawthorne's *House of the Seven Gables* and returns a object that contains all words that begin with either an uppercase or lowercase "h". The property is then used to retrieve each word and display it to the console. + The following example parses the first sentence of Nathaniel Hawthorne's *House of the Seven Gables* and returns a object that contains all words that begin with either an uppercase or lowercase "h". The property is then used to retrieve each word and display it to the console. :::code language="csharp" source="~/snippets/csharp/System.Text.RegularExpressions/MatchCollection/Item/RegEx_24804.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/MatchCollection/Item/RegEx_24804.vb" id="Snippet1"::: @@ -625,7 +625,7 @@ huge ## Remarks > [!WARNING] -> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. +> This member is not present in the Portable Class Library. If you are developing applications that target the Portable Class Library, use the property instead. ]]> @@ -859,7 +859,7 @@ huge ## Remarks -The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. +The returned provides the ability to iterate through the collection by exposing a property .You can use enumerators to read the data in a collection, but not to modify the collection. Initially, the enumerator is positioned before the first element in the collection. At this position, is undefined. Therefore, you must call the method to advance the enumerator to the first element of the collection before reading the value of . returns the same object until is called again as 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. If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined. @@ -1016,7 +1016,7 @@ If an object occurs multiple times in the list, the property. Visual Basic implements as a [default property](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. + 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](/dotnet/visual-basic/language-reference/modifiers/default), which provides the same indexing functionality. ]]>
@@ -1546,7 +1546,7 @@ This member is an explicit interface member implementation. It can be used only ## Remarks This property provides the ability to access a specific element in the collection by using the following syntax: `myCollection[index]`. - 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. + 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. ]]>
diff --git a/xml/System.Text.RegularExpressions/Regex.xml b/xml/System.Text.RegularExpressions/Regex.xml index b4d532da454..d240367e846 100644 --- a/xml/System.Text.RegularExpressions/Regex.xml +++ b/xml/System.Text.RegularExpressions/Regex.xml @@ -565,7 +565,7 @@ For more information about this API, see [Supplemental API remarks for Regex](/d ## Remarks The class maintains an internal cache of compiled regular expressions used in static method calls, such as or . 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. + 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. ]]>
@@ -2495,7 +2495,7 @@ Allows an to attempt to free resources and perfor ## Remarks The collection of group names contains the set of strings used to name capturing groups in the expression. Even if capturing groups are not explicitly named, they are automatically assigned numerical names ("0", "1", "2", "3", and so on). The "0" named group represents all text matched by the regular expression pattern. Numbered groups precede explicitly named groups in the collection, and named groups appear in the order in which they are defined in the regular expression pattern. - You can use the property on the array returned by this method to determine the number of groups in a regular expression. + You can use the property on the array returned by this method to determine the number of groups in a regular expression. @@ -2656,7 +2656,7 @@ Allows an to attempt to free resources and perfor 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. + 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. @@ -3801,7 +3801,7 @@ For more details about `startat`, see the Remarks section of 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 . + 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. @@ -3957,7 +3957,7 @@ For more details about `startat`, see the Remarks section of 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 . + 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. @@ -4059,7 +4059,7 @@ For more details about `startat`, see the Remarks section of 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 . + 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. @@ -4150,7 +4150,7 @@ For more details about `startat`, see the Remarks section of 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 . + 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. @@ -4256,7 +4256,7 @@ For more details about `startat`, see the Remarks section of 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 . + 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. @@ -4370,7 +4370,7 @@ For more details about `startat`, see the Remarks section of 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. + 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". @@ -4458,7 +4458,7 @@ For more details about `startat`, see the Remarks section of 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. + 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. @@ -4852,7 +4852,7 @@ For more details about `startat`, see the Remarks section of 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). + The 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. @@ -4918,9 +4918,9 @@ For more details about `startat`, see the Remarks section of 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. + The value of the 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. + Note that the property does not reflect inline options defined in the regular expression pattern itself. ]]>
@@ -5360,7 +5360,7 @@ For more details about `startat`, see the Remarks section of 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. + 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" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace3.vb" id="Snippet3"::: @@ -5374,7 +5374,7 @@ For more details about `startat`, see the Remarks section of property.| +|`(?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.| @@ -5787,7 +5787,7 @@ For more details about `startat`, see the Remarks section of 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. + 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" id="Snippet4"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace4.vb" id="Snippet4"::: @@ -5801,7 +5801,7 @@ For more details about `startat`, see the Remarks section of property.| +|`+ 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.| @@ -6108,7 +6108,7 @@ For more details about `startat`, see the Remarks section of 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. + 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" id="Snippet12"::: :::code language="vb" source="~/snippets/visualbasic/System.Text.RegularExpressions/Regex/Replace/replace12.vb" id="Snippet12"::: @@ -6122,7 +6122,7 @@ For more details about `startat`, see the Remarks section of property.| +|`+ 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.| diff --git a/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml b/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml index c2f4cdefc0e..7ce4791b411 100644 --- a/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml +++ b/xml/System.Text.RegularExpressions/RegexCompilationInfo.xml @@ -208,7 +208,7 @@ If `ispublic` is `true`, the compiled regular expression class is given public accessibility. That is, it can be instantiated from code that executes in any assembly. If `ispublic` is `false`, the compiled regular expression class is given `internal` (in C#) or `Friend` (in Visual Basic) accessibility. That is, it can be instantiated only from code that executes in the same assembly as the regular expression class. - The `matchTimeout` parameter defines the default time-out interval for the compiled regular expression. This value represents the approximate amount of time that a compiled regular expression object will execute a single matching operation before the operation times out and the regular expression engine throws a exception during its next timing check. For additional information about the time-out value, see the property. + The `matchTimeout` parameter defines the default time-out interval for the compiled regular expression. This value represents the approximate amount of time that a compiled regular expression object will execute a single matching operation before the operation times out and the regular expression engine throws a exception during its next timing check. For additional information about the time-out value, see the property. > [!IMPORTANT] > We recommend that you always set a default time-out value for a compiled regular expression. Consumers of your regular expression library can override that time-out value by passing a value that represents the new time-out interval to this constructor overload. @@ -300,7 +300,7 @@ property is `false`, the regular expression class defined by the current instance can be instantiated only by code that is executing in the assembly that contains the class. However, because the method generates an assembly that contains only compiled regular expressions and does not allow additional code to be added, there is generally no reason to assign this property a value of `false`. + If the property is `false`, the regular expression class defined by the current instance can be instantiated only by code that is executing in the assembly that contains the class. However, because the method generates an assembly that contains only compiled regular expressions and does not allow additional code to be added, there is generally no reason to assign this property a value of `false`. ]]> @@ -341,7 +341,7 @@ property defines the default time-out interval for the compiled regular expression. This value represents the approximate amount of time that a compiled regular expression will execute a single matching operation before the operation times out and the regular expression engine throws a exception during its next timing check. + The property defines the default time-out interval for the compiled regular expression. This value represents the approximate amount of time that a compiled regular expression will execute a single matching operation before the operation times out and the regular expression engine throws a exception during its next timing check. > [!IMPORTANT] > We recommend that you always set a default time-out value for a compiled regular expression. Consumers of your regular expression library can override that time-out value by passing a value that represents the new time-out interval to the compiled regular expression's class constructor. @@ -428,7 +428,7 @@ class is used to define a compiled regular expression, which is represented as a class derived from . The property defines the class name of the regular expression type, and the and properties together define its fully qualified name. + The class is used to define a compiled regular expression, which is represented as a class derived from . The property defines the class name of the regular expression type, and the and properties together define its fully qualified name. ]]> @@ -479,7 +479,7 @@ class is used to define a compiled regular expression, which is represented as a class derived from . The property defines the namespace that contains the compiled regular expression type, and the and properties together define its fully qualified name. + The class is used to define a compiled regular expression, which is represented as a class derived from . The property defines the namespace that contains the compiled regular expression type, and the and properties together define its fully qualified name. ]]> @@ -582,7 +582,7 @@ property can contain any valid regular expression. If the value of the property is not a syntactically correct regular expression pattern, the call to the method throws an . + The property can contain any valid regular expression. If the value of the property is not a syntactically correct regular expression pattern, the call to the method throws an . ]]> diff --git a/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml b/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml index 0790fedfdd6..33103ee4ca7 100644 --- a/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml +++ b/xml/System.Text.RegularExpressions/RegexMatchTimeoutException.xml @@ -77,9 +77,9 @@ The way in which an exception handler handles an exception depends on the cause of the exception: -- If the time-out results from excessive backtracking, your exception handler should abandon the attempt to match the input and inform the user that a time-out has occurred in the regular expression pattern-matching method. If possible, information about the regular expression pattern, which is available from the property, and the input that caused excessive backtracking, which is available from the property, should be logged so that the issue can be investigated and the regular expression pattern modified. Time-outs due to excessive backtracking are always reproducible. +- If the time-out results from excessive backtracking, your exception handler should abandon the attempt to match the input and inform the user that a time-out has occurred in the regular expression pattern-matching method. If possible, information about the regular expression pattern, which is available from the property, and the input that caused excessive backtracking, which is available from the property, should be logged so that the issue can be investigated and the regular expression pattern modified. Time-outs due to excessive backtracking are always reproducible. -- If the time-out results from setting the time-out threshold too low, you can increase the time-out interval and retry the matching operation. The current time-out interval is available from the property. When a exception is thrown, the regular expression engine maintains its state so that any future invocations return the same result, as if the exception did not occur. The recommended pattern is to wait for a brief, random time interval after the exception is thrown before calling the matching method again. This can be repeated several times. However, the number of repetitions should be small in case the time-out is caused by excessive backtracking. +- If the time-out results from setting the time-out threshold too low, you can increase the time-out interval and retry the matching operation. The current time-out interval is available from the property. When a exception is thrown, the regular expression engine maintains its state so that any future invocations return the same result, as if the exception did not occur. The recommended pattern is to wait for a brief, random time interval after the exception is thrown before calling the matching method again. This can be repeated several times. However, the number of repetitions should be small in case the time-out is caused by excessive backtracking. The example in the next section illustrates both techniques for handling a . @@ -151,7 +151,7 @@ class. This constructor initializes the property of the new instance to a system-supplied message that describes the error. This message is localized for the current system culture. + This is the parameterless constructor of the class. This constructor initializes the property of the new instance to a system-supplied message that describes the error. This message is localized for the current system culture. ]]> @@ -202,7 +202,7 @@ property. The string should be localized for the current culture. + The `message` string is assigned to the property. The string should be localized for the current culture. ]]> @@ -314,9 +314,9 @@ object's property. + Typically, you use this overload to handle an exception in a `try/catch` block. The `innerException` parameter should be a reference to the exception object handled in the `catch` block, or it can be `null`. This value is then assigned to the object's property. - The `message` string is assigned to the property. The string should be localized for the current culture. + The `message` string is assigned to the property. The string should be localized for the current culture. ]]> @@ -424,7 +424,7 @@ ## Remarks This property reflects the value of the `regexInput` parameter of the constructor. If this parameter is not explicitly initialized in a constructor call, its value is . - When the exception is thrown by the regular expression engine, the value of the property reflects the entire input string passed to the regular expression engine. It does not reflect a partial string, such as the substring that the engine searches in the call to a method such as . + When the exception is thrown by the regular expression engine, the value of the property reflects the entire input string passed to the regular expression engine. It does not reflect a partial string, such as the substring that the engine searches in the call to a method such as . ]]> diff --git a/xml/System.Text.RegularExpressions/RegexOptions.xml b/xml/System.Text.RegularExpressions/RegexOptions.xml index 10dc6a3b6a1..f1abe4d2254 100644 --- a/xml/System.Text.RegularExpressions/RegexOptions.xml +++ b/xml/System.Text.RegularExpressions/RegexOptions.xml @@ -73,7 +73,7 @@ - The and methods. - A `RegexOptions` value can also be supplied as a parameter to the constructor, or it can be assigned directly to the property. The resulting object is then used in the call to the method. + A `RegexOptions` value can also be supplied as a parameter to the constructor, or it can be assigned directly to the property. The resulting object is then used in the call to the method. Several options provided by members of the `RegexOptions` enumeration (in particular, by its `ExplicitCapture`, `IgnoreCase`, `Multiline`, and `Singleline` members) can instead be provided by using an inline option character in the regular expression pattern. For details, see [Regular Expression Options](/dotnet/standard/base-types/regular-expression-options). diff --git a/xml/System.Text/ASCIIEncoding.xml b/xml/System.Text/ASCIIEncoding.xml index 6db0de37130..9bebda5fc96 100644 --- a/xml/System.Text/ASCIIEncoding.xml +++ b/xml/System.Text/ASCIIEncoding.xml @@ -63,7 +63,7 @@ ## Remarks Encoding is the process of transforming a set of Unicode characters into a sequence of bytes. Decoding is the process of transforming a sequence of encoded bytes into a set of Unicode characters. - corresponds to the Windows code page 20127. Because ASCII is a 7-bit encoding, ASCII characters are limited to the lowest 128 Unicode characters, from U+0000 to U+007F. If you use the default encoder returned by the property or the constructor, characters outside that range are replaced with a question mark (?) before the encoding operation is performed. Because the class supports only a limited character set, the , , and classes are better suited for globalized applications. The following considerations can help you to decide whether to use : + corresponds to the Windows code page 20127. Because ASCII is a 7-bit encoding, ASCII characters are limited to the lowest 128 Unicode characters, from U+0000 to U+007F. If you use the default encoder returned by the property or the constructor, characters outside that range are replaced with a question mark (?) before the encoding operation is performed. Because the class supports only a limited character set, the , , and classes are better suited for globalized applications. The following considerations can help you to decide whether to use : - Some protocols require ASCII or a subset of ASCII. In these cases ASCII encoding is appropriate. @@ -76,7 +76,7 @@ Likewise, the method determines how many characters result in decoding a sequence of bytes, and the and methods perform the actual decoding. - Note that the default constructor by itself might not have the appropriate behavior for your application. You might want to consider setting the or property to or to prevent sequences with the 8th bit set. Custom behavior might also be appropriate for these cases. + Note that the default constructor by itself might not have the appropriate behavior for your application. You might want to consider setting the or property to or to prevent sequences with the 8th bit set. Custom behavior might also be appropriate for these cases. @@ -1803,7 +1803,7 @@ property to determine the size of a byte array for encoding operations and the size of a character array for decoding operations (for example, so that the size of the byte array is * the number of characters to be encoded), you should call the or method for encoding operations and the or method for decoding operations. These methods takes the object's replacement fallback strategy into account when calculating the required array size. + Instead of using the property to determine the size of a byte array for encoding operations and the size of a character array for decoding operations (for example, so that the size of the byte array is * the number of characters to be encoded), you should call the or method for encoding operations and the or method for decoding operations. These methods takes the object's replacement fallback strategy into account when calculating the required array size. ]]> diff --git a/xml/System.Text/CodePagesEncodingProvider.xml b/xml/System.Text/CodePagesEncodingProvider.xml index 84a6917ef52..1a18c74a507 100644 --- a/xml/System.Text/CodePagesEncodingProvider.xml +++ b/xml/System.Text/CodePagesEncodingProvider.xml @@ -52,19 +52,19 @@ The .NET Framework for the Windows desktop supports a large set of Unicode and code page encodings. .NET Core, on the other hand, supports only the following encodings: -- ASCII (code page 20127), which is returned by the property. +- ASCII (code page 20127), which is returned by the property. - ISO-8859-1 (code page 28591). -- UTF-7 (code page 65000), which is returned by the property. +- UTF-7 (code page 65000), which is returned by the property. -- UTF-8 (code page 65001), which is returned by the property. +- UTF-8 (code page 65001), which is returned by the property. -- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. +- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. - UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. -- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. +- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. - UTF-32BE (code page 12001), which is instantiated by calling an constructor that has a `bigEndian` parameter and providing a value of `true` in the method call. @@ -72,7 +72,7 @@ The class extends to make these code pages available to .NET Core. To use these additional code pages, you do the following: -- Retrieve a object from the static property. +- Retrieve a object from the static property. - Pass the object to the method. @@ -106,19 +106,19 @@ When no encoding provider is registered, `GetEncoding(0)` returns UTF-8 on all p The .NET Framework supports a large number of character encodings and code pages. You can get a complete list of encodings by calling the method, which is available in the .NET Framework. On the other hand, .NET Core only supports the following encodings by default: -- ASCII (code page 20127), which is returned by the property. +- ASCII (code page 20127), which is returned by the property. - ISO-8859-1 (code page 28591). -- UTF-7 (code page 65000), which is returned by the property. +- UTF-7 (code page 65000), which is returned by the property. -- UTF-8 (code page 65001), which is returned by the property. +- UTF-8 (code page 65001), which is returned by the property. -- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. +- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. - UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. -- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. +- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. - UTF-32BE (code page 12001), which is instantiated by calling an constructor that has a `bigEndian` parameter and providing a value of `true` in the method call. @@ -126,7 +126,7 @@ The .NET Framework supports a large number of character encodings and code pages - Add a reference to the *System.Text.Encoding.CodePages.dll* assembly to your project. -- Get the object from the static property. +- Get the object from the static property. - Pass the object to the method to make the encodings supplied by the object available to the common language runtime. @@ -289,25 +289,25 @@ For all other supported code page identifiers, this method returns the correspon The .NET Framework supports a large number of character encodings and code pages. You can get a complete list of encodings by calling the method, which is available in the .NET Framework. On the other hand, .NET Core only supports the following encodings by default: -- ASCII (code page 20127), which is returned by the property. +- ASCII (code page 20127), which is returned by the property. - ISO-8859-1 (code page 28591). -- UTF-7 (code page 65000), which is returned by the property. +- UTF-7 (code page 65000), which is returned by the property. -- UTF-8 (code page 65001), which is returned by the property. +- UTF-8 (code page 65001), which is returned by the property. -- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. +- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. - UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. -- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. +- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. - UTF-32BE (code page 12001), which is instantiated by calling an constructor that has a `bigEndian` parameter and providing a value of `true` in the method call. To retrieve an encoding that is present in the .NET Framework but not in .NET Core, you do the following: -- Get the object from the static property. +- Get the object from the static property. - Pass the object to the method to make the encodings supplied by the object available to the common language runtime. diff --git a/xml/System.Text/DecoderExceptionFallbackBuffer.xml b/xml/System.Text/DecoderExceptionFallbackBuffer.xml index fb867ef35db..1276a6f886b 100644 --- a/xml/System.Text/DecoderExceptionFallbackBuffer.xml +++ b/xml/System.Text/DecoderExceptionFallbackBuffer.xml @@ -45,13 +45,13 @@ Throws when an encoded input byte sequence cannot be converted to a decoded output character. This class cannot be inherited. - method, which throws . - - The class, which represents a data buffer used in a decoding operation, is the base class for the class. However, instead of a data buffer, the class represents a standard behavior in which an exception is thrown if a decoding operation fails. No actual data buffer exists, and the members designed to manipulate such a buffer do no significant work. - + method, which throws . + + The class, which represents a data buffer used in a decoding operation, is the base class for the class. However, instead of a data buffer, the class represents a standard behavior in which an exception is thrown if a decoding operation fails. No actual data buffer exists, and the members designed to manipulate such a buffer do no significant work. + ]]> @@ -136,15 +136,15 @@ An input array of bytes. The index position of a byte in the input. Throws when the input byte sequence cannot be decoded. The nominal return value is not used. - None. No value is returned because the method always throws an exception. - + None. No value is returned because the method always throws an exception. + The nominal return value is . A return value is defined, although it is unchanging, because this method implements an abstract method. - and methods call if they encounter an unknown byte in their input. In response, the method always throws and displays the input data. The method nominally indicates whether an exception is thrown if an input byte sequence cannot be decoded. - + and methods call if they encounter an unknown byte in their input. In response, the method always throws and displays the input data. The method nominally indicates whether an exception is thrown if an input byte sequence cannot be decoded. + ]]> This method always throws an exception that reports the value and index position of the input byte that cannot be decoded. @@ -188,15 +188,15 @@ Retrieves the next character in the exception data buffer. - The return value is always the Unicode character NULL (U+0000). - + The return value is always the Unicode character NULL (U+0000). + A return value is defined, although it is unchanging, because this method implements an abstract method. - has no actual exception data buffer, the method always returns the Unicode NULL character. - + has no actual exception data buffer, the method always returns the Unicode NULL character. + ]]> @@ -239,15 +239,15 @@ Causes the next call to to access the exception data buffer character position that is prior to the current position. - The return value is always . - + The return value is always . + A return value is defined, although it is unchanging, because this method implements an abstract method. - has no actual exception data buffer, the method always returns `false`. - + has no actual exception data buffer, the method always returns `false`. + ]]> @@ -289,15 +289,15 @@ Gets the number of characters in the current object that remain to be processed. - The return value is always zero. - + The return value is always zero. + A return value is defined, although it is unchanging, because this method implements an abstract method. - has no actual exception data buffer, the property always returns zero. - + has no actual exception data buffer, the property always returns zero. + ]]> diff --git a/xml/System.Text/DecoderFallback.xml b/xml/System.Text/DecoderFallback.xml index f06414161fd..9460cd7af04 100644 --- a/xml/System.Text/DecoderFallback.xml +++ b/xml/System.Text/DecoderFallback.xml @@ -91,7 +91,7 @@ - The method, which returns a class instance derived from . Depending on the type of fallback handler that you are developing, the implementation is responsible for performing the mapping or replacement, or for throwing the exception. -- The property, which returns the maximum number of characters that the fallback implementation can return. For an exception fallback handler, its value should be zero. +- The property, which returns the maximum number of characters that the fallback implementation can return. For an exception fallback handler, its value should be zero. For more information about encoding, decoding, and fallback strategies, see [Character Encoding in the .NET Framework](/dotnet/standard/base-types/character-encoding). diff --git a/xml/System.Text/DecoderFallbackBuffer.xml b/xml/System.Text/DecoderFallbackBuffer.xml index fe8c89fe71e..a7f8047e6d3 100644 --- a/xml/System.Text/DecoderFallbackBuffer.xml +++ b/xml/System.Text/DecoderFallbackBuffer.xml @@ -86,7 +86,7 @@ - The method, which tries to move the pointer to the previous position in the buffer and indicates whether the move was successful. An exception handler always returns `false`. -- The property, which indicates the number of remaining characters to be returned to the decoder. An exception fallback handler always returns zero. +- The property, which indicates the number of remaining characters to be returned to the decoder. An exception fallback handler always returns zero. ]]>
diff --git a/xml/System.Text/DecoderFallbackException.xml b/xml/System.Text/DecoderFallbackException.xml index 95ec69beb54..6cf52aa3c04 100644 --- a/xml/System.Text/DecoderFallbackException.xml +++ b/xml/System.Text/DecoderFallbackException.xml @@ -76,7 +76,7 @@ ## Examples The following code example demonstrates the and classes. - + :::code language="csharp" source="~/snippets/csharp/System.Text/DecoderExceptionFallback/Overview/fallDecExc.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/DecoderExceptionFallback/Overview/fallDecExc.vb" id="Snippet1"::: @@ -139,7 +139,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -193,7 +193,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -249,7 +249,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -307,7 +307,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -361,7 +361,7 @@ property to get the position in the input byte array of the byte that cannot be decoded. + The application uses the property to get the position in the input byte array of the byte that cannot be decoded. ]]> @@ -414,7 +414,7 @@ property to retrieve the input byte array that contains the byte that cannot be decoded. + The application uses the property to retrieve the input byte array that contains the byte that cannot be decoded. ]]> diff --git a/xml/System.Text/DecoderReplacementFallback.xml b/xml/System.Text/DecoderReplacementFallback.xml index 440fc4f7d98..765c47a6875 100644 --- a/xml/System.Text/DecoderReplacementFallback.xml +++ b/xml/System.Text/DecoderReplacementFallback.xml @@ -411,7 +411,7 @@ object is the value of its property. + The value of a object is the value of its property. ]]> diff --git a/xml/System.Text/DecoderReplacementFallbackBuffer.xml b/xml/System.Text/DecoderReplacementFallbackBuffer.xml index 18137ddcd42..b7d10139533 100644 --- a/xml/System.Text/DecoderReplacementFallbackBuffer.xml +++ b/xml/System.Text/DecoderReplacementFallbackBuffer.xml @@ -51,13 +51,13 @@ Represents a substitute output string that is emitted when the original input byte sequence cannot be decoded. This class cannot be inherited. - object provides a replacement string that is substituted for the output character. The replacement string initializes the value of the object, and the value of the object initializes the value of a object. The value of a object is called the replacement fallback buffer. The conversion operation uses the replacement fallback buffer to emit a replacement string instead of a decoded character, then continues to process the remainder of the input. - + object provides a replacement string that is substituted for the output character. The replacement string initializes the value of the object, and the value of the object initializes the value of a object. The value of a object is called the replacement fallback buffer. The conversion operation uses the replacement fallback buffer to emit a replacement string instead of a decoded character, then continues to process the remainder of the input. + ]]> @@ -149,11 +149,11 @@ if the replacement string is not empty; if the replacement string is empty. - and methods call if they encounter an unknown input byte sequence that cannot be decoded. If the return value of is `true`, the calling method can invoke the method to obtain each character of the fallback buffer. - + and methods call if they encounter an unknown input byte sequence that cannot be decoded. If the return value of is `true`, the calling method can invoke the method to obtain each character of the fallback buffer. + ]]> This method is called again before the method has read all the characters in the replacement fallback buffer. @@ -199,11 +199,11 @@ Retrieves the next character in the replacement fallback buffer. The next character in the replacement fallback buffer. - and methods call if they encounter an unknown surrogate pair or character in their input. If the return value of is `true`, the calling method can invoke to obtain each character of the replacement fallback buffer. - + and methods call if they encounter an unknown surrogate pair or character in their input. If the return value of is `true`, the calling method can invoke to obtain each character of the replacement fallback buffer. + ]]> @@ -290,11 +290,11 @@ Gets the number of characters in the replacement fallback buffer that remain to be processed. The number of characters in the replacement fallback buffer that have not yet been processed. - method returns `true` if the property is nonzero. - + method returns `true` if the property is nonzero. + ]]> @@ -344,11 +344,11 @@ Initializes all internal state information and data in the object. - method discards any persisted state information and data that govern the emitting of a replacement string. Unpredictable results occur if the decoding operation continues after the method is invoked. - + method discards any persisted state information and data that govern the emitting of a replacement string. Unpredictable results occur if the decoding operation continues after the method is invoked. + ]]> diff --git a/xml/System.Text/EncoderExceptionFallbackBuffer.xml b/xml/System.Text/EncoderExceptionFallbackBuffer.xml index 7109b04c982..f5cee29364f 100644 --- a/xml/System.Text/EncoderExceptionFallbackBuffer.xml +++ b/xml/System.Text/EncoderExceptionFallbackBuffer.xml @@ -45,13 +45,13 @@ Throws when an input character cannot be converted to an encoded output byte sequence. This class cannot be inherited. - method, which throws . - - The class, which represents a data buffer used in an encoding operation, is the base class for the class. However, instead of a data buffer, the class represents a standard behavior wherein an exception is thrown if an encoding operation fails. No actual data buffer exists, and the members designed to manipulate such a buffer do no significant work. - + method, which throws . + + The class, which represents a data buffer used in an encoding operation, is the base class for the class. However, instead of a data buffer, the class represents a standard behavior wherein an exception is thrown if an encoding operation fails. No actual data buffer exists, and the members designed to manipulate such a buffer do no significant work. + ]]> @@ -148,11 +148,11 @@ Throws an exception because the input character cannot be encoded. Parameters specify the value and index position of the character that cannot be converted. None. No value is returned because the method always throws an exception. - and methods call if they encounter an unknown character in their input. In response, always throws . - + and methods call if they encounter an unknown character in their input. In response, always throws . + ]]> @@ -206,11 +206,11 @@ Throws an exception because the input character cannot be encoded. Parameters specify the value and index position of the surrogate pair in the input, and the nominal return value is not used. None. No value is returned because the method always throws an exception. - and methods call if they encounter a surrogate pair in their input. In response, always throws an exception. - + and methods call if they encounter a surrogate pair in their input. In response, always throws an exception. + ]]> The character represented by and cannot be encoded. @@ -255,15 +255,15 @@ Retrieves the next character in the exception fallback buffer. - The return value is always the Unicode character, NULL (U+0000). - + The return value is always the Unicode character, NULL (U+0000). + A return value is defined, although it is unchanging, because this method implements an abstract method. - has no actual exception data buffer, the method always returns the Unicode NULL character. - + has no actual exception data buffer, the method always returns the Unicode NULL character. + ]]> @@ -306,15 +306,15 @@ Causes the next call to the method to access the exception data buffer character position that is prior to the current position. - The return value is always . - + The return value is always . + A return value is defined, although it is unchanging, because this method implements an abstract method. - has no actual exception data buffer, the method always returns `false`. - + has no actual exception data buffer, the method always returns `false`. + ]]> @@ -356,15 +356,15 @@ Gets the number of characters in the current object that remain to be processed. - The return value is always zero. - + The return value is always zero. + A return value is defined, although it is unchanging, because this method implements an abstract method. - has no actual exception data buffer, the property always returns zero. - + has no actual exception data buffer, the property always returns zero. + ]]> diff --git a/xml/System.Text/EncoderFallback.xml b/xml/System.Text/EncoderFallback.xml index ec65c2febfc..d782ef968ce 100644 --- a/xml/System.Text/EncoderFallback.xml +++ b/xml/System.Text/EncoderFallback.xml @@ -91,7 +91,7 @@ - The method, which returns a class instance derived from . Depending on the type of fallback handler that you are developing, the implementation is responsible for performing the mapping or replacement, or for throwing the exception. -- The property, which returns the maximum number of characters that the fallback implementation can return. For an exception fallback handler, its value should be zero. +- The property, which returns the maximum number of characters that the fallback implementation can return. For an exception fallback handler, its value should be zero. For more information about encoding, decoding, and fallback strategies, see [Character Encoding in the .NET Framework](/dotnet/standard/base-types/character-encoding). diff --git a/xml/System.Text/EncoderFallbackBuffer.xml b/xml/System.Text/EncoderFallbackBuffer.xml index 290a430e7e5..894949e512f 100644 --- a/xml/System.Text/EncoderFallbackBuffer.xml +++ b/xml/System.Text/EncoderFallbackBuffer.xml @@ -86,7 +86,7 @@ - The method, which tries to move the pointer to the previous position in the buffer and indicates whether the move was successful. An exception handler always returns `false`. -- The property, which indicates the number of remaining characters to be returned to the encoder. An exception fallback handler always returns zero. +- The property, which indicates the number of remaining characters to be returned to the encoder. An exception fallback handler always returns zero. ]]>
diff --git a/xml/System.Text/EncoderFallbackException.xml b/xml/System.Text/EncoderFallbackException.xml index b796cb87464..01b0cb937c1 100644 --- a/xml/System.Text/EncoderFallbackException.xml +++ b/xml/System.Text/EncoderFallbackException.xml @@ -76,7 +76,7 @@ ## Examples The following code example demonstrates the and classes. - + :::code language="csharp" source="~/snippets/csharp/System.Text/EncoderExceptionFallback/Overview/fallEncExc.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/EncoderExceptionFallback/Overview/fallEncExc.vb" id="Snippet1"::: @@ -139,7 +139,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -193,7 +193,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> @@ -249,7 +249,7 @@ property for this exception is set to COR_E_ARGUMENT (0x80070057). + The property for this exception is set to COR_E_ARGUMENT (0x80070057). ]]> diff --git a/xml/System.Text/EncoderReplacementFallback.xml b/xml/System.Text/EncoderReplacementFallback.xml index 43ec0558bda..c48d673cb5c 100644 --- a/xml/System.Text/EncoderReplacementFallback.xml +++ b/xml/System.Text/EncoderReplacementFallback.xml @@ -376,7 +376,7 @@ object is the value of its property. + The value of a object is the value of its property. ]]> @@ -429,7 +429,7 @@ object is the value of its property. + The value of a object is the value of its property. ]]> diff --git a/xml/System.Text/EncoderReplacementFallbackBuffer.xml b/xml/System.Text/EncoderReplacementFallbackBuffer.xml index 44f4bfb3cea..6197f574d79 100644 --- a/xml/System.Text/EncoderReplacementFallbackBuffer.xml +++ b/xml/System.Text/EncoderReplacementFallbackBuffer.xml @@ -45,13 +45,13 @@ Represents a substitute input string that is used when the original input character cannot be encoded. This class cannot be inherited. - object provides a replacement string that is substituted for the original input character. The replacement string initializes the value of the object, and the value of the object initializes the value of an object. The value of an object is called the replacement fallback buffer. The conversion operation encodes the replacement fallback buffer instead of the original input character, then continues to process the remainder of the input. - + object provides a replacement string that is substituted for the original input character. The replacement string initializes the value of the object, and the value of the object initializes the value of an object. The value of an object is called the replacement fallback buffer. The conversion operation encodes the replacement fallback buffer instead of the original input character, then continues to process the remainder of the input. + ]]> @@ -154,11 +154,11 @@ if the replacement string is not empty; if the replacement string is empty. - and methods call if they encounter an unknown character in their input. If the return value of is `true`, the calling method can invoke the method to obtain each character in the replacement fallback buffer. - + and methods call if they encounter an unknown character in their input. If the return value of is `true`, the calling method can invoke the method to obtain each character in the replacement fallback buffer. + ]]> This method is called again before the method has read all the characters in the replacement fallback buffer. @@ -212,18 +212,18 @@ if the replacement string is not empty; if the replacement string is empty. - and methods call if they encounter an unknown character in their input. If the return value of is `true`, the calling method can invoke the method to obtain each character in the replacement fallback buffer. - + and methods call if they encounter an unknown character in their input. If the return value of is `true`, the calling method can invoke the method to obtain each character in the replacement fallback buffer. + ]]> This method is called again before the method has read all the replacement string characters. - The value of is less than U+D800 or greater than U+D8FF. - - -or- - + The value of is less than U+D800 or greater than U+D8FF. + + -or- + The value of is less than U+DC00 or greater than U+DFFF. @@ -267,11 +267,11 @@ Retrieves the next character in the replacement fallback buffer. The next Unicode character in the replacement fallback buffer that the application can encode. - and methods call if they encounter an unknown surrogate pair or character in their input. If the return value of is `true`, the calling method can invoke to obtain each character in the replacement fallback buffer. - + and methods call if they encounter an unknown surrogate pair or character in their input. If the return value of is `true`, the calling method can invoke to obtain each character in the replacement fallback buffer. + ]]> @@ -358,11 +358,11 @@ Gets the number of characters in the replacement fallback buffer that remain to be processed. The number of characters in the replacement fallback buffer that have not yet been processed. - method returns `true` if the property is nonzero. - + method returns `true` if the property is nonzero. + ]]> @@ -412,11 +412,11 @@ Initializes all internal state information and data in this instance of . - method discards any persisted state information and data that govern emitting a replacement string. Unpredictable results occur if the encoding operation continues after the method is invoked. - + method discards any persisted state information and data that govern emitting a replacement string. Unpredictable results occur if the encoding operation continues after the method is invoked. + ]]> diff --git a/xml/System.Text/Encoding.xml b/xml/System.Text/Encoding.xml index c9a3099a445..8206ed1bd84 100644 --- a/xml/System.Text/Encoding.xml +++ b/xml/System.Text/Encoding.xml @@ -502,9 +502,9 @@ The following example demonstrates the effect of the ASCII encoding on character with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding; most other applications that need to describe an encoding should use its . + If you need an encoding for a body name, you should call with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding; most other applications that need to describe an encoding should use its . - In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. + In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. ## Examples The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. @@ -712,7 +712,7 @@ The following example demonstrates the effect of the ASCII encoding on character property uses replacement fallback and the Pi character is not part of the ASCII character set, the Pi character is replaced with a question mark, as the output from the example shows. + The following example converts a Unicode-encoded string to an ASCII-encoded string. Because the ASCII encoding object returned by the property uses replacement fallback and the Pi character is not part of the ASCII character set, the Pi character is replaced with a question mark, as the output from the example shows. :::code language="csharp" source="~/snippets/csharp/System.Text/Encoding/Overview/convert.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/Encoding/Overview/convert.vb" id="Snippet1"::: @@ -1006,7 +1006,7 @@ The returned 's and property varies between different .NET implementations: +The behavior of the property varies between different .NET implementations: - **In .NET Framework**: Returns the encoding that corresponds to the system's active code page. This is the same encoding returned by when called with a `codepage` argument of `0`. @@ -1140,7 +1140,7 @@ For more information about this API, see property is intended for display. To find a name that can be passed to the method, use the property. + The property is intended for display. To find a name that can be passed to the method, use the property. ## Examples The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. @@ -3600,7 +3600,7 @@ You can also supply a value of 0 for the `codepage` argument. The behavior varie - **No encoding provider registered**: Returns a , same as . -- ** registered**: +- ** registered**: - On **Windows**, returns the encoding that matches the system's active code page (same as .NET Framework behavior). - On **non-Windows platforms**, always returns a . @@ -3808,7 +3808,7 @@ You can also supply a value of 0 for the `codepage` argument. The behavior varie - **No encoding provider registered**: Returns a , same as . -- ** registered**: +- ** registered**: - On **Windows**, returns the encoding that matches the system's active code page (same as .NET Framework behavior). - On **non-Windows platforms**, always returns a . @@ -3817,7 +3817,7 @@ You can also supply a value of 0 for the `codepage` argument. The behavior varie > [!NOTE] > The ANSI code pages can be different on different computers and can change on a single computer, leading to data corruption. For this reason, if the active code page is an ANSI code page, encoding and decoding data using the default code page returned by `Encoding.GetEncoding(0)` is not recommended. For the most consistent results, you should use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page. - To get the encoding associated with the active code page, you can either supply a value of 0 for the `codepage` argument or, if your code is running on .NET Framework, retrieve the value of the property. To determine the current active code page, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework. + To get the encoding associated with the active code page, you can either supply a value of 0 for the `codepage` argument or, if your code is running on .NET Framework, retrieve the value of the property. To determine the current active code page, call the Windows [GetACP](/windows/win32/api/winnls/nf-winnls-getacp) function from .NET Framework. returns a cached instance with default settings. You should use the constructors of derived classes to get an instance with different settings. For example, the class provides a constructor that lets you enable error detection. @@ -4120,7 +4120,7 @@ In .NET 5 and later versions, the code page name `utf-7` is not supported. When using , you should allocate the output buffer based on the maximum size of the input buffer. If the output buffer is constrained in size, you might use the method. - Note that considers potential leftover surrogates from a previous decoder operation. Because of the decoder, passing a value of 1 to the method retrieves 2 for a single-byte encoding, such as ASCII. You should use the property if this information is necessary. + Note that considers potential leftover surrogates from a previous decoder operation. Because of the decoder, passing a value of 1 to the method retrieves 2 for a single-byte encoding, such as ASCII. You should use the property if this information is necessary. > [!NOTE] > `GetMaxByteCount(N)` is not necessarily the same value as `N* GetMaxByteCount(1)`. @@ -4726,11 +4726,11 @@ The goal is to save this file, then open and decode it as a binary stream. method with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding. + If you need an encoding for a header name, you should call the method with the property. Often the method retrieves a different encoding from the test encoding furnished in the call. Generally only email applications need to retrieve such an encoding. - In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. + In some cases, the value of the property corresponds to the international standard that defines that encoding. This doesn't mean that the implementation complies in full with that standard. - Note that returns the name to use to describe an encoding. The property defines a different encoding that might work better for an email application, for example. However, use of the property to define the encoding is not recommended. + Note that returns the name to use to describe an encoding. The property defines a different encoding that might work better for an email application, for example. However, use of the property to define the encoding is not recommended. ## Examples The following example retrieves the different names for each encoding and displays the encodings with one or more names that are different from . It displays but does not compare against it. @@ -5395,7 +5395,7 @@ The goal is to save this file, then open and decode it as a binary stream. Registering an encoding provider by using the method also affects the behavior of when passed an argument of `0`. This is particularly important in .NET Core and later versions where the default behavior for with `codepage` 0 is to return UTF-8: -- **If the registered provider is **: +- **If the registered provider is **: - On **Windows**, with `codepage` 0 returns the encoding that matches the system's active code page (same as .NET Framework behavior). - On **non-Windows platforms**, it still returns UTF-8. @@ -5864,9 +5864,9 @@ Starting with .NET Framework 4.6, .NET Framework includes one encoding provider, property is the same as the property. + The property is the same as the property. - Note that returns an IANA-registered name for the encoding. When its value is the name of a standard, the implementation of the encoding might not conform in full to that standard. The property defines a different encoding that might work better for email headers. However, most apps should use instead. + Note that returns an IANA-registered name for the encoding. When its value is the name of a standard, the implementation of the encoding might not conform in full to that standard. The property defines a different encoding that might work better for email headers. However, most apps should use instead. For more information on the IANA, go to [www.iana.org](https://www.iana.org/). diff --git a/xml/System.Text/EncodingInfo.xml b/xml/System.Text/EncodingInfo.xml index 8e23c49abec..08cb353f12b 100644 --- a/xml/System.Text/EncodingInfo.xml +++ b/xml/System.Text/EncodingInfo.xml @@ -66,8 +66,8 @@ ## Examples - The following example uses the method to retrieve an object for each encoding supported by the .NET Framework. It then displays the value of each encoding's , , and property and compares them with the corresponding names. - + The following example uses the method to retrieve an object for each encoding supported by the .NET Framework. It then displays the value of each encoding's , , and property and compares them with the corresponding names. + :::code language="csharp" source="~/snippets/csharp/System.Text/EncodingInfo/Overview/encodinginfo.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Text/EncodingInfo/Overview/encodinginfo.vb" id="Snippet1"::: @@ -211,7 +211,7 @@ property. Your applications should use for a name to pass to . + This property defines a display name that is the same as the name represented by the property. Your applications should use for a name to pass to . @@ -439,9 +439,9 @@ . This name is the same as the name represented by the property. When its value is the name of a standard, the actual implementation of the encoding may not conform in full to that standard. Your applications should use for a human-readable name. + This property defines the name that is appropriate for passing to . This name is the same as the name represented by the property. When its value is the name of a standard, the actual implementation of the encoding may not conform in full to that standard. Your applications should use for a human-readable name. - The method gets a complete list of supported encodings, uniquely distinguished by code page. If your application retrieves encodings using the property, note that some duplicate encodings are retrieved. For more about handling these duplicates, see the description of . + The method gets a complete list of supported encodings, uniquely distinguished by code page. If your application retrieves encodings using the property, note that some duplicate encodings are retrieved. For more about handling these duplicates, see the description of . For a list of supported names, see [Character Sets](https://www.iana.org/assignments/character-sets/character-sets.xhtml) on the [IANA website](https://www.iana.org). diff --git a/xml/System.Text/EncodingProvider.xml b/xml/System.Text/EncodingProvider.xml index 845efa0fcd9..3d66452b1d1 100644 --- a/xml/System.Text/EncodingProvider.xml +++ b/xml/System.Text/EncodingProvider.xml @@ -75,19 +75,19 @@ The .NET Framework supports a large number of character encodings and code pages. You can get a complete list of encodings available in the .NET Framework by calling the method. .NET Core, on the other hand, by default supports only the following encodings: -- ASCII (code page 20127), which is returned by the property. +- ASCII (code page 20127), which is returned by the property. - ISO-8859-1 (code page 28591). -- UTF-7 (code page 65000), which is returned by the property. +- UTF-7 (code page 65000), which is returned by the property. -- UTF-8 (code page 65001), which is returned by the property. +- UTF-8 (code page 65001), which is returned by the property. -- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. +- UTF-16 and UTF-16LE (code page 1200), which is returned by the property. - UTF-16BE (code page 1201), which is instantiated by calling the or constructor with a `bigEndian` value of `true`. -- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. +- UTF-32 and UTF-32LE (code page 12000), which is returned by the property. - UTF-32BE (code page 12001), which is instantiated by calling an constructor that has a `bigEndian` parameter and providing a value of `true` in the method call. diff --git a/xml/System.Text/StringBuilder.xml b/xml/System.Text/StringBuilder.xml index a360c7702df..5ad196f75b7 100644 --- a/xml/System.Text/StringBuilder.xml +++ b/xml/System.Text/StringBuilder.xml @@ -221,7 +221,7 @@ The following example shows how to call many of the methods defined by the property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + The `capacity` parameter defines the maximum number of characters that can be stored in the memory allocated by the current instance. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. The string value of this instance is set to . If `capacity` is zero, the implementation-specific default capacity is used. @@ -359,11 +359,11 @@ The following example shows how to call many of the methods defined by the property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + The `capacity` parameter defines the maximum number of characters that can be stored in the memory allocated by the current instance. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. If `capacity` is zero, the implementation-specific default capacity is used. - The `maxCapacity` property defines the maximum number of characters that the current instance can hold. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `maxCapacity` value, the object does not allocate additional memory, but instead throws an exception. + The `maxCapacity` property defines the maximum number of characters that the current instance can hold. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `maxCapacity` value, the object does not allocate additional memory, but instead throws an exception. @@ -441,7 +441,7 @@ The following example shows how to call many of the methods defined by the property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + The `capacity` parameter defines the maximum number of characters that can be stored in the memory allocated by the current instance. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. If `capacity` is zero, the implementation-specific default capacity is used. @@ -521,7 +521,7 @@ The following example shows how to call many of the methods defined by the property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. + The `capacity` parameter defines the maximum number of characters that can be stored in the memory allocated by the current instance. Its value is assigned to the property. If the number of characters to be stored in the current instance exceeds this `capacity` value, the object allocates additional memory to store them. If `capacity` is zero, the implementation-specific default capacity is used. @@ -4648,7 +4648,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th property. + The default line terminator is the current value of the property. The capacity of this instance is adjusted as needed. @@ -4734,7 +4734,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th property. + The default line terminator is the current value of the property. The capacity of this instance is adjusted as needed. @@ -4902,7 +4902,7 @@ The index of a format item is less than 0 (zero), or greater than or equal to th ## Examples - The following example demonstrates the property. + The following example demonstrates the property. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: @@ -5031,7 +5031,7 @@ The `index` parameter is the position of a character within the is a convenience method that is equivalent to setting the property of the current instance to 0 (zero). + is a convenience method that is equivalent to setting the property of the current instance to 0 (zero). ## Examples @@ -6991,7 +6991,7 @@ The existing characters are shifted to make room for the character sequence in t ## Remarks The length of a object is defined by its number of objects. - Like the property, the property indicates the length of the current string object. Unlike the property, which is read-only, the property allows you to modify the length of the string stored to the object. + Like the property, the property indicates the length of the current string object. Unlike the property, which is read-only, the property allows you to modify the length of the string stored to the object. If the specified length is less than the current length, the current object is truncated to the specified length. If the specified length is greater than the current length, the end of the string value of the current object is padded with the Unicode NULL character (U+0000). @@ -7000,7 +7000,7 @@ The existing characters are shifted to make room for the character sequence in t ## Examples - The following example demonstrates the property. + The following example demonstrates the property. :::code language="csharp" source="~/snippets/csharp/System.Text/StringBuilder/Capacity/cap.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Text/StringBuilder/Capacity/cap.fs" id="Snippet1"::: diff --git a/xml/System.Text/UTF32Encoding.xml b/xml/System.Text/UTF32Encoding.xml index bf180178a1d..3827c279826 100644 --- a/xml/System.Text/UTF32Encoding.xml +++ b/xml/System.Text/UTF32Encoding.xml @@ -1802,7 +1802,7 @@ You can instantiate a object whose method returns a valid BOM in the following ways: -- By retrieving the object returned by the property. +- By retrieving the object returned by the property. - By calling the parameterless constructor to instantiate a object. @@ -1986,7 +1986,7 @@ You can instantiate a object whose property is a valid BOM in the following ways: -- By retrieving the object returned by the property. +- By retrieving the object returned by the property. - By calling the parameterless constructor to instantiate a object. diff --git a/xml/System.Text/UTF8Encoding.xml b/xml/System.Text/UTF8Encoding.xml index c4448fb4248..89bb781e40c 100644 --- a/xml/System.Text/UTF8Encoding.xml +++ b/xml/System.Text/UTF8Encoding.xml @@ -2086,7 +2086,7 @@ You can instantiate a object whose method returns a valid BOM in the following ways: -- By retrieving the object returned by the property. +- By retrieving the object returned by the property. - By calling a constructor with a `encoderShouldEmitUTF8Identifier` parameter and setting its value set to `true`. @@ -2260,7 +2260,7 @@ You can instantiate a object whose `Preamble` is a valid BOM in the following ways: -- By retrieving the object returned by the property. +- By retrieving the object returned by the property. - By calling a constructor with an `encoderShouldEmitUTF8Identifier` parameter and setting its value set to `true`. diff --git a/xml/System.Text/UnicodeEncoding.xml b/xml/System.Text/UnicodeEncoding.xml index c47bb5acc1b..4b76b81dd0b 100644 --- a/xml/System.Text/UnicodeEncoding.xml +++ b/xml/System.Text/UnicodeEncoding.xml @@ -1956,7 +1956,7 @@ You can instantiate a object whose method returns a valid BOM in the following ways: -- By retrieving the object returned by the or property. +- By retrieving the object returned by the or property. - By calling the parameterless constructor to instantiate a object. @@ -2140,7 +2140,7 @@ You can instantiate a object whose is a valid BOM in the following ways: -- By retrieving the object returned by the or property. +- By retrieving the object returned by the or property. - By calling the parameterless constructor to instantiate a object. diff --git a/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml b/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml index f14b7e6fb90..f059357814c 100644 --- a/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml +++ b/xml/System.Threading.Tasks.Dataflow/ActionBlock`1.xml @@ -64,18 +64,18 @@ The type of data that this operates on. Provides a dataflow block that invokes a provided delegate for every data element received. - class to perform several computations using dataflow blocks, and returns the elapsed time required to perform the computations. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) article. - + +## Examples + The following example shows the use of the class to perform several computations using dataflow blocks, and returns the elapsed time required to perform the computations. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) article. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: + ]]> @@ -186,21 +186,21 @@ The options with which to configure this . Initializes a new instance of the class with the specified action and configuration options. - constructor to create a new object. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. - + constructor to create a new object. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: + ]]> - is . - - -or- - + is . + + -or- + is . @@ -239,10 +239,10 @@ Initializes a new instance of the class with the specified action and configuration options. To be added. - is . - - -or- - + is . + + -or- + is . @@ -281,19 +281,19 @@ Signals to the dataflow block that it shouldn't accept or produce any more messages and shouldn't consume any more postponed messages. - has been called on a dataflow block, that block will complete (so that its task will enter a final state) after it has processed all previously available data. This method will not block waiting for completion to occur, but will initiate the request. To wait for completion to occur, use the property. - - - -## Examples - The following example shows the use of the method to signal to the dataflow block that it shouldn't accept or produce any more messages nor consume any more postponed messages. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. - + has been called on a dataflow block, that block will complete (so that its task will enter a final state) after it has processed all previously available data. This method will not block waiting for completion to occur, but will initiate the request. To wait for completion to occur, use the property. + + + +## Examples + The following example shows the use of the method to signal to the dataflow block that it shouldn't accept or produce any more messages nor consume any more postponed messages. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: + ]]> @@ -333,19 +333,19 @@ Gets a object that represents the asynchronous operation and completion of the dataflow block. The completed task. - will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely after receiving a cancellation request. If the task completes in the state, its `Exception` property returns an exception that contains one or more exceptions that caused the block to fail. - - - -## Examples - The following example shows how to use the property to wait for all messages to propagate through the network. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. - + will transition to a completed state when the associated block has completed. It will transition to the state when the block completes its processing successfully according to the dataflow block's defined semantics. It will transition to the state when the dataflow block has completed processing prematurely due to an unhandled exception, and it will transition to the state when the dataflow block has completed processing prematurely after receiving a cancellation request. If the task completes in the state, its `Exception` property returns an exception that contains one or more exceptions that caused the block to fail. + + + +## Examples + The following example shows how to use the property to wait for all messages to propagate through the network. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: + ]]> @@ -382,11 +382,11 @@ Gets the number of input items waiting to be processed by this block. The number of input items waiting to be processed by this block. - does not include any items that are currently being processed by the block or any items that have already been processed by the block. - + does not include any items that are currently being processed by the block or any items that have already been processed by the block. + ]]> @@ -428,14 +428,14 @@ if the item is posted to the dataflow block; otherwise, . - method to post an item to the target dataflow block. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. - + method to post an item to the target dataflow block. This code example is part of a larger example provided for the [How to: Specify the Degree of Parallelism in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block) topic. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks.Dataflow/ActionBlock`1/dataflowdegreeofparallelism.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_degreeofparallelism/vb/dataflowdegreeofparallelism.vb" id="Snippet2"::: + ]]> @@ -478,11 +478,11 @@ The exception that caused the faulting. Causes the dataflow block to complete in a faulted state. - has been called on a dataflow block, that block will complete and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. - + has been called on a dataflow block, that block will complete and its task will enter a final state. Faulting a block, as with canceling a block, causes buffered messages (unprocessed input messages as well as unoffered output messages) to be lost. + ]]> @@ -533,17 +533,17 @@ to instruct the target to call synchronously during the call to , prior to returning , in order to consume the message; otherwise, . Offers a message to the dataflow block, and gives it the opportunity to consume or postpone the message. - The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. - - If the target would have otherwise postponed message, but source was , is returned. - - If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. - + The status of the offered message. If the message was accepted by the target, is returned, and the source should no longer use the offered message, because it is now owned by the target. If the message was postponed by the target, is returned as a notification that the target may later attempt to consume or reserve the message; in the meantime, the source still owns the message and may offer it to other blocks. + + If the target would have otherwise postponed message, but source was , is returned. + + If the target tried to accept the message but missed it due to the source delivering the message to another target or simply discarding it, is returned. + If the target chose not to accept the message, is returned. If the target chose not to accept the message and will never accept another message from this source, is returned. To be added. - is not valid. - + is not valid. + -or- may be only if provided with a non-null . @@ -580,11 +580,11 @@ Returns a string that represents the formatted name of this instance. A string that represents the formatted name of this instance. - . Uses the option. - + . Uses the option. + ]]> diff --git a/xml/System.Threading.Tasks.Dataflow/DataflowBlock.xml b/xml/System.Threading.Tasks.Dataflow/DataflowBlock.xml index acaf6f33882..ec69917504d 100644 --- a/xml/System.Threading.Tasks.Dataflow/DataflowBlock.xml +++ b/xml/System.Threading.Tasks.Dataflow/DataflowBlock.xml @@ -37,11 +37,11 @@ Provides a set of static (Shared in Visual Basic) methods for working with dataflow blocks. - @@ -205,22 +205,22 @@ The second source. The handler to execute on data from the second source. Monitors two dataflow sources, invoking the provided handler for whichever source makes data available first. - A that represents the asynchronous choice. If both sources are completed prior to the choice completing, the resulting task will be canceled. When one of the sources has data available and successfully propagates it to the choice, the resulting task will complete when the handler completes; if the handler throws an exception, the task will end in the state and will contain the unhandled exception. Otherwise, the task will end with its set to either 0 or 1 to represent the first or second source, respectively. - + A that represents the asynchronous choice. If both sources are completed prior to the choice completing, the resulting task will be canceled. When one of the sources has data available and successfully propagates it to the choice, the resulting task will complete when the handler completes; if the handler throws an exception, the task will end in the state and will contain the unhandled exception. Otherwise, the task will end with its set to either 0 or 1 to represent the first or second source, respectively. + This method will only consume an element from one of the two data sources, never both. To be added. - The is . - - -or- - - The is . - - -or- - - The is . - - -or- - + The is . + + -or- + + The is . + + -or- + + The is . + + -or- + The is . @@ -288,22 +288,22 @@ Monitors two dataflow sources, invoking the provided handler for whichever source makes data available first. A that represents the asynchronous choice. If both sources are completed prior to the choice completing, or if the provided as part of is canceled prior to the choice completing, the resulting task will be canceled. When one of the sources has data available and successfully propagates it to the choice, the resulting task will complete when the handler completes; if the handler throws an exception, the task will end in the state and will contain the unhandled exception. Otherwise, the task will end with its set to either 0 or 1 to represent the first or second source, respectively. To be added. - The is . - - -or- - - The is . - - -or- - - The is . - - -or- - - The is . - - -or- - + The is . + + -or- + + The is . + + -or- + + The is . + + -or- + + The is . + + -or- + The is . @@ -380,30 +380,30 @@ The third source. The handler to execute on data from the third source. Monitors three dataflow sources, invoking the provided handler for whichever source makes data available first. - A that represents the asynchronous choice. If all sources are completed prior to the choice completing, the resulting task will be canceled. When one of the sources has data available and successfully propagates it to the choice, the resulting task will complete when the handler completes; if the handler throws an exception, the task will end in the state and will contain the unhandled exception. Otherwise, the task will end with its set to the 0-based index of the source. - + A that represents the asynchronous choice. If all sources are completed prior to the choice completing, the resulting task will be canceled. When one of the sources has data available and successfully propagates it to the choice, the resulting task will complete when the handler completes; if the handler throws an exception, the task will end in the state and will contain the unhandled exception. Otherwise, the task will end with its set to the 0-based index of the source. + This method will only consume an element from one of the data sources, never more than one. To be added. - The is . - - -or- - - The is . - - -or- - - The is . - - -or- - - The is . - - -or- - - The is . - - -or- - + The is . + + -or- + + The is . + + -or- + + The is . + + -or- + + The is . + + -or- + + The is . + + -or- + The is . @@ -482,34 +482,34 @@ The handler to execute on data from the third source. The options with which to configure this choice. Monitors three dataflow sources, invoking the provided handler for whichever source makes data available first. - A that represents the asynchronous choice. If all sources are completed prior to the choice completing, or if the provided as part of is canceled prior to the choice completing, the resulting task will be canceled. When one of the sources has data available and successfully propagates it to the choice, the resulting task will complete when the handler completes; if the handler throws an exception, the task will end in the state and will contain the unhandled exception. Otherwise, the task will end with its set to the 0-based index of the source. - + A that represents the asynchronous choice. If all sources are completed prior to the choice completing, or if the provided as part of is canceled prior to the choice completing, the resulting task will be canceled. When one of the sources has data available and successfully propagates it to the choice, the resulting task will complete when the handler completes; if the handler throws an exception, the task will end in the state and will contain the unhandled exception. Otherwise, the task will end with its set to the 0-based index of the source. + This method will only consume an element from one of the data sources, never more than one. If cancellation is requested after an element has been received, the cancellation request will be ignored, and the relevant handler will be allowed to execute. To be added. - The is . - - -or- - - The is . - - -or- - - The is . - - -or- - - The is . - - -or- - - The is . - - -or- - - The is . - - -or- - + The is . + + -or- + + The is . + + -or- + + The is . + + -or- + + The is . + + -or- + + The is . + + -or- + + The is . + + -or- + The is . @@ -571,27 +571,27 @@ Encapsulates a target and a source into a single propagator. The encapsulated target and source. - method requires two existing blocks: a target block (an instance of a class that implements ) and a source block (an instance of a class that implements ). creates a new instance of an internal class that connects the interface members to the `target` parameter and the interface members to the `source` parameter. Both and derive from . Block completion is explicitly passed from sources to targets. Therefore, the and methods are connected to the target while the property is connected to the source. You must ensure that when the target half completes, the source half gets completed in the most appropriate manner; for example: - - `target.Completion.ContinueWith(completion => source.Complete());` - - Or, if you want to propagate the completion type, you can use this more sophisticated code: - -``` -target.Completion.ContinueWith(completion => { if (completion.IsFaulted) - -((IDataflowBlock)batchBlock).Fault(completion.Exception); -else -batchBlock.Complete(); -}); - -``` - - You must also explicitly provide the message propagation from target to source. The benefit of this explicit connection is that it gives you the freedom to perform any unconstrained processing between the two encapsulated blocks. You may do that either by encoding the necessary processing into the blocks' delegates (if the blocks take delegates), or by embedding a sub-network of blocks between them. The easier way is to use a block that takes delegates; for example, use , , (if applicable), or a custom block. - + method requires two existing blocks: a target block (an instance of a class that implements ) and a source block (an instance of a class that implements ). creates a new instance of an internal class that connects the interface members to the `target` parameter and the interface members to the `source` parameter. Both and derive from . Block completion is explicitly passed from sources to targets. Therefore, the and methods are connected to the target while the property is connected to the source. You must ensure that when the target half completes, the source half gets completed in the most appropriate manner; for example: + + `target.Completion.ContinueWith(completion => source.Complete());` + + Or, if you want to propagate the completion type, you can use this more sophisticated code: + +``` +target.Completion.ContinueWith(completion => { if (completion.IsFaulted) + +((IDataflowBlock)batchBlock).Fault(completion.Exception); +else +batchBlock.Complete(); +}); + +``` + + You must also explicitly provide the message propagation from target to source. The benefit of this explicit connection is that it gives you the freedom to perform any unconstrained processing between the two encapsulated blocks. You may do that either by encoding the necessary processing into the blocks' delegates (if the blocks take delegates), or by embedding a sub-network of blocks between them. The easier way is to use a block that takes delegates; for example, use , , (if applicable), or a custom block. + ]]> @@ -645,10 +645,10 @@ batchBlock.Complete(); Links the to the specified . An that, upon calling , will unlink the source from the target. To be added. - The is . - - -or- - + The is . + + -or- + The is . @@ -703,14 +703,14 @@ batchBlock.Complete(); Links the to the specified using the specified filter. An that, upon calling , will unlink the source from the target. To be added. - The is . - - -or- - - The is . - - -or- - + The is . + + -or- + + The is . + + -or- + The is . @@ -767,18 +767,18 @@ batchBlock.Complete(); Links the to the specified using the specified filter. An that, upon calling , will unlink the source from the target. To be added. - The is null (Nothing in Visual Basic). - - -or- - - The is null (Nothing in Visual Basic). - - -or- - - The is null (Nothing in Visual Basic). - - -or- - + The is null (Nothing in Visual Basic). + + -or- + + The is null (Nothing in Visual Basic). + + -or- + + The is null (Nothing in Visual Basic). + + -or- + The is null (Nothing in Visual Basic). @@ -873,8 +873,8 @@ batchBlock.Complete(); Specifies the type of data contained in the source. The source to monitor. Provides a that asynchronously monitors the source for available output. - A that informs of whether and when more output is available. If, when the task completes, its is , more output is available in the source (though another consumer of the source may retrieve the data). - + A that informs of whether and when more output is available. If, when the task completes, its is , more output is available in the source (though another consumer of the source may retrieve the data). + If it returns , more output is not and will never be available, due to the source completing prior to output being available. To be added. @@ -981,11 +981,11 @@ batchBlock.Complete(); if the item was accepted by the target block; otherwise, . - will return from as soon as it has stored the posted item into its input queue). From the perspective of the block's processing, `Post` is asynchronous. For target blocks that support postponing offered messages, or for blocks that may do more processing in their `Post` implementation, consider using , which will return immediately and will enable the target to postpone the posted message and later consume it after `SendAsync` returns. - + will return from as soon as it has stored the posted item into its input queue). From the perspective of the block's processing, `Post` is asynchronous. For target blocks that support postponing offered messages, or for blocks that may do more processing in their `Post` implementation, consider using , which will return immediately and will enable the target to postpone the posted message and later consume it after `SendAsync` returns. + ]]> @@ -1091,11 +1091,11 @@ batchBlock.Complete(); Synchronously receives a value from a specified source and provides a token to cancel the operation. The received value. - @@ -1153,18 +1153,18 @@ batchBlock.Complete(); Synchronously receives a value from a specified source, observing an optional time-out period. The received value. - - is a negative number other than -1 milliseconds, which represents an infinite time-out period. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out period. + + -or- + is greater than Int32.MaxValue. is . @@ -1223,19 +1223,19 @@ batchBlock.Complete(); Synchronously receives a value from a specified source, providing a token to cancel the operation and observing an optional time-out interval. The received value. - The is . - is a negative number other than -1 milliseconds, which represents an infinite time-out period. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out period. + + -or- + is greater than Int32.MaxValue. No item could be received from the source. The specified time-out expired before an item was received from the source. @@ -1443,10 +1443,10 @@ batchBlock.Complete(); is . - is a negative number other than -1 milliseconds, which represents an infinite time-out period. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out period. + + -or- + is greater than Int32.MaxValue. @@ -1504,10 +1504,10 @@ batchBlock.Complete(); is . - is a negative number other than -1 milliseconds, which represents an infinite time-out period. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out period. + + -or- + is greater than Int32.MaxValue. The cancellation token was canceled. This exception is stored into the returned task. @@ -1613,8 +1613,8 @@ batchBlock.Complete(); The item being offered to the target. The cancellation token with which to request cancellation of the send operation. Asynchronously offers a message to the target message block, allowing for postponement. - A that represents the asynchronous send. If the target accepts and consumes the offered element during the call to SendAsync, upon return from the call the resulting will be completed and its Result property will return true. If the target declines the offered element during the call, upon return from the call the resulting will be completed and its Result property will return false. If the target postpones the offered element, the element will be buffered until such time that the target consumes or releases it, at which point the Task will complete, with its Result indicating whether the message was consumed. If the target never attempts to consume or release the message, the returned task will never complete. - + A that represents the asynchronous send. If the target accepts and consumes the offered element during the call to SendAsync, upon return from the call the resulting will be completed and its Result property will return true. If the target declines the offered element during the call, upon return from the call the resulting will be completed and its Result property will return false. If the target postpones the offered element, the element will be buffered until such time that the target consumes or releases it, at which point the Task will complete, with its Result indicating whether the message was consumed. If the target never attempts to consume or release the message, the returned task will never complete. + If cancellation is requested before the target has successfully consumed the sent data, the returned task will complete in the Canceled state and the data will no longer be available to the target. To be added. The is null (Nothing in Visual Basic). @@ -1678,13 +1678,13 @@ batchBlock.Complete(); if an item could be received; otherwise, . - diff --git a/xml/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair.xml b/xml/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair.xml index f8b396a68c5..4eb7e6b8c7a 100644 --- a/xml/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair.xml +++ b/xml/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair.xml @@ -71,14 +71,14 @@ Provides task schedulers that coordinate to execute tasks while ensuring that concurrent tasks may run concurrently and exclusive tasks never do. - class. Readers run on the concurrent part of the scheduler. The writer runs on the exclusive part of the scheduler. This code example is part of a larger example provided for the [How to: Specify a Task Scheduler in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block) article. - + class. Readers run on the concurrent part of the scheduler. The writer runs on the exclusive part of the scheduler. This code example is part of a larger example provided for the [How to: Specify a Task Scheduler in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block) article. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair/form1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb" id="Snippet4"::: + ]]> @@ -133,14 +133,14 @@ Initializes a new instance of the class. - constructor to create a new object. This code example is part of a larger example provided for the [How to: Specify a Task Scheduler in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block) article. - + constructor to create a new object. This code example is part of a larger example provided for the [How to: Specify a Task Scheduler in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block) article. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair/form1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb" id="Snippet4"::: + ]]> @@ -329,11 +329,11 @@ Informs the scheduler pair that it should not accept any more tasks. - is optional. It is necessary only if you're relying on the property for notification that all processing has been completed. - + is optional. It is necessary only if you're relying on the property for notification that all processing has been completed. + ]]> @@ -426,14 +426,14 @@ Gets a that can be used to schedule tasks to this pair that may run concurrently with other tasks on this pair. An object that can be used to schedule tasks concurrently. - property to run a reader. This code example is part of a larger example provided for the [How to: Specify a Task Scheduler in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block) article. - + property to run a reader. This code example is part of a larger example provided for the [How to: Specify a Task Scheduler in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block) article. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair/form1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb" id="Snippet4"::: + ]]> @@ -481,14 +481,14 @@ Gets a that can be used to schedule tasks to this pair that must run exclusively with regards to other tasks on this pair. An object that can be used to schedule tasks that do not run concurrently with other tasks. - property to run a writer. This code example is part of a larger example provided for the [How to: Specify a Task Scheduler in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block) article. - + property to run a writer. This code example is part of a larger example provided for the [How to: Specify a Task Scheduler in a Dataflow Block](/dotnet/standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block) article. + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/ConcurrentExclusiveSchedulerPair/form1.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpldataflow_writerreaderswinforms/vb/writerreaderswinforms/form1.vb" id="Snippet4"::: + ]]> diff --git a/xml/System.Threading.Tasks/Parallel.xml b/xml/System.Threading.Tasks/Parallel.xml index 6a570a91b00..8958b013a01 100644 --- a/xml/System.Threading.Tasks/Parallel.xml +++ b/xml/System.Threading.Tasks/Parallel.xml @@ -147,12 +147,12 @@ ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/break1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/break1.vb" id="Snippet2"::: - Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. ]]> diff --git a/xml/System.Threading.Tasks/ParallelLoopState.xml b/xml/System.Threading.Tasks/ParallelLoopState.xml index d6dafca46e9..86ad5065de9 100644 --- a/xml/System.Threading.Tasks/ParallelLoopState.xml +++ b/xml/System.Threading.Tasks/ParallelLoopState.xml @@ -62,23 +62,23 @@ - Prevent any iterations with an index greater than the current index from executing by calling the method. This does not affect iterations that have already begun execution. -- Determine whether an exception has occurred in any loop iteration by retrieving the value of the property. +- Determine whether an exception has occurred in any loop iteration by retrieving the value of the property. -- Determine whether any iteration of the loop has called the method by retrieving the value of the property. You can use this property to return from iterations of the loop that started before the call to the method but are still executing. +- Determine whether any iteration of the loop has called the method by retrieving the value of the property. You can use this property to return from iterations of the loop that started before the call to the method but are still executing. -- Determine whether any iteration of the loop has called the or method or has thrown an exception by retrieving the value of the property. +- Determine whether any iteration of the loop has called the or method or has thrown an exception by retrieving the value of the property. -- Exit from a long-running iteration whose index is greater than the index of an iteration in which Break was called by retrieving the value of the property. +- Exit from a long-running iteration whose index is greater than the index of an iteration in which Break was called by retrieving the value of the property. ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/break1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/break1.vb" id="Snippet2"::: - Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. ]]> @@ -129,11 +129,11 @@ ## Remarks indicates that no iterations after the current iteration should be run. It effectively cancels any additional iterations of the loop. However, it does not stop any iterations that have already begun execution. For example, if is called from the 100th iteration of a parallel loop iterating from 0 to 1,000, all iterations less than 100 should still be run, but the iterations from 101 through to 1000 that have not yet started are not executed. - For long-running iterations that may already be executing, sets the property to the current iteration's index if the current index is less than the current value of . To stop iterations whose index is greater than the lowest break iteration from competing execution, you should do the following: + For long-running iterations that may already be executing, sets the property to the current iteration's index if the current index is less than the current value of . To stop iterations whose index is greater than the lowest break iteration from competing execution, you should do the following: -1. Check whether the property is `true`. +1. Check whether the property is `true`. -2. Exit from the iteration if its index is greater than the property value. +2. Exit from the iteration if its index is greater than the property value. The example provides an illustration. @@ -142,12 +142,12 @@ ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. As the output from the example shows, no iterations whose index is greater than the property value start after the call to the method. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/break1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/break1.vb" id="Snippet2"::: - Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + Because iterations of the loop are still likely to be executing when the method is called, each iteration calls the property to check whether another iteration has called the method. If the property value is `true`, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. ]]> @@ -241,7 +241,7 @@ property to determine whether any iterations of the loop that began execution before the call to the method are still executing. You can then use the value of the property to determine whether they should return immediately or execute normally. + For long-running iterations of the loop, you can retrieve the value of the property to determine whether any iterations of the loop that began execution before the call to the method are still executing. You can then use the value of the property to determine whether they should return immediately or execute normally. @@ -299,18 +299,18 @@ ## Remarks It is possible for multiple iterations of a parallel loop to call the method. If they do, this value is the smallest index of an iteration that called . If no iteration of the loop called , this property returns `null`. Note that the property value is unaffected by calls to the method. - In long-running iterations in which all iterations after the iteration that calls the method need not run, the property is used to terminate iterations that began execution before the call to the method. To stop iterations whose index is greater than the lowest break iteration from competing execution, you should do the following: + In long-running iterations in which all iterations after the iteration that calls the method need not run, the property is used to terminate iterations that began execution before the call to the method. To stop iterations whose index is greater than the lowest break iteration from competing execution, you should do the following: -1. Check whether the property is `true`. +1. Check whether the property is `true`. -2. Exit from the iteration if its index is greater than the property value. +2. Exit from the iteration if its index is greater than the property value. The example provides an illustration. ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. This prevents iterations whose index is greater than the property value from starting after the call to the method, but it does not affect any iterations that have already begun executing. To prevent these from completing, each iteration calls the method to check whether another iteration has called the method. If so, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. This prevents iterations whose index is greater than the property value from starting after the call to the method, but it does not affect any iterations that have already begun executing. To prevent these from completing, each iteration calls the method to check whether another iteration has called the method. If so, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/break1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/break1.vb" id="Snippet2"::: @@ -366,7 +366,7 @@ property is set to `true` under any of the following conditions: + The property is set to `true` under any of the following conditions: - An iteration of the loop calls or . @@ -376,12 +376,12 @@ When this property is `true`, the class will proactively attempt to prohibit additional iterations of the loop from starting execution. However, there may be cases where it is unable to prevent additional iterations from starting. - It may also be the case that a long-running iteration has already begun execution. In such cases, iterations may explicitly check the property and cease execution if the property returns `true`. + It may also be the case that a long-running iteration has already begun execution. In such cases, iterations may explicitly check the property and cease execution if the property returns `true`. ## Examples - The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. This prevents iterations whose index is greater than the property value from starting after the call to the method, but it does not affect any iterations that have already begun executing. To prevent these from completing, each iteration calls the method to check whether another iteration has called the method. If so, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. + The following example executes up to 100 iterations of a loop in parallel. Each iteration pauses for a random interval from 1 to 1,000 milliseconds. A randomly generated value determines on which iteration of the loop the method is called. This prevents iterations whose index is greater than the property value from starting after the call to the method, but it does not affect any iterations that have already begun executing. To prevent these from completing, each iteration calls the method to check whether another iteration has called the method. If so, the iteration checks the value of the property and, if it is greater than the current iteration's index value, returns immediately. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Parallel/For/break1.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Parallel/For/break1.vb" id="Snippet2"::: @@ -437,7 +437,7 @@ ## Remarks Calling the method indicates that any iterations of the loop that have not yet started need not be run. It effectively cancels any additional iterations of the loop. However, it does not stop any iterations that have already begun execution. - Calling the method causes the property to return `true` for any iteration of the loop that is still executing. This is particularly useful for long-running iterations, which can check the property and exit early if its value is `true`. + Calling the method causes the property to return `true` for any iteration of the loop that is still executing. This is particularly useful for long-running iterations, which can check the property and exit early if its value is `true`. is typically employed in search-based algorithms, where once a result is found, no other iterations need be executed. diff --git a/xml/System.Threading.Tasks/ParallelOptions.xml b/xml/System.Threading.Tasks/ParallelOptions.xml index c6e2a3be676..5c6c55a9dd6 100644 --- a/xml/System.Threading.Tasks/ParallelOptions.xml +++ b/xml/System.Threading.Tasks/ParallelOptions.xml @@ -196,7 +196,7 @@ By default, methods on the class attempt property affects the number of concurrent operations run by method calls that are passed this instance. A positive property value limits the number of concurrent operations to the set value. If it is -1, there is no limit on the number of concurrently running operations (with the exception of the method, where -1 means ). + The property affects the number of concurrent operations run by method calls that are passed this instance. A positive property value limits the number of concurrent operations to the set value. If it is -1, there is no limit on the number of concurrently running operations (with the exception of the method, where -1 means ). By default, and will utilize however many threads the underlying scheduler provides, so changing from the default only limits how many concurrent tasks will be used. diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index b1c53752af0..28d853e7c1c 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -738,7 +738,7 @@ To retrieve the object's data, cast it back to the original type. property is set to . To create a task that returns a value and runs to completion, call the method. + This property returns a task whose property is set to . To create a task that returns a value and runs to completion, call the method. Repeated attempts to retrieve this property value may not always return the same instance. @@ -2525,7 +2525,7 @@ End Sub is a `static` (`Shared` in Visual Basic) property that is used to get the identifier of the currently executing task from the code that the task is executing. It differs from the property, which returns the identifier of a particular instance. If you attempt to retrieve the value from outside the code that a task is executing, the property returns `null`. + is a `static` (`Shared` in Visual Basic) property that is used to get the identifier of the currently executing task from the code that the task is executing. It differs from the property, which returns the identifier of a particular instance. If you attempt to retrieve the value from outside the code that a task is executing, the property returns `null`. Note that although collisions are very rare, task identifiers are not guaranteed to be unique. @@ -2769,7 +2769,7 @@ End Sub > The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). ## Examples - The following example launches a task that includes a call to the method with a one second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . + The following example launches a task that includes a call to the method with a one second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay3.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay3.fs" id="Snippet3"::: @@ -2847,7 +2847,7 @@ End Sub ## Examples - The following example launches a task that includes a call to the method with a 1.5 second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . + The following example launches a task that includes a call to the method with a 1.5 second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay4.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay4.fs" id="Snippet4"::: @@ -3141,7 +3141,7 @@ Task t Status: RanToCompletion, Result: 42 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). + Tasks that throw unhandled exceptions store the resulting exception and propagate it wrapped in a 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). ]]> @@ -3207,7 +3207,7 @@ Task t Status: RanToCompletion, Result: 42 > [!NOTE] > Starting with .NET Framework 4.5, the method provides the easiest way to create a object with default configuration values. - The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. + The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Factory/factory1.fs" id="Snippet1"::: @@ -3376,7 +3376,7 @@ Task t Status: RanToCompletion, Result: 42 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. + This method creates a 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. ]]> @@ -3442,12 +3442,12 @@ Task t Status: RanToCompletion, Result: 42 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. The example provides an illustration. + This method creates a 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. The example provides an illustration. ## Examples - The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a faulted task if a particular subdirectory does not exist. + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a faulted task if a particular subdirectory does not exist. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.fs" id="Snippet1"::: @@ -3519,14 +3519,14 @@ Task t Status: RanToCompletion, Result: 42 ## Remarks -This method creates a object whose property is `result` and whose property is . The method is commonly used when the return value of a task is immediately known without executing a longer code path. The example provides an illustration. +This method creates a object whose property is `result` and whose property is . The method is commonly used when the return value of a task is immediately known without executing a longer code path. The example provides an illustration. -To create a `Task` object that does not return a value, retrieve the `Task` object from the property. +To create a `Task` object that does not return a value, retrieve the `Task` object from the property. Starting in .NET 6, for some `TResult` types and some result values, this method may return a cached singleton object rather than allocating a new object. ## Examples - The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a task whose property is zero (0) if a directory has no files. + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a task whose property is zero (0) if a directory has no files. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.fs" id="Snippet1"::: @@ -3645,7 +3645,7 @@ This method is intended for compiler use rather than use directly in code. ## Remarks Task IDs are assigned on-demand and do not necessarily represent the order in which task instances are created. Note that although collisions are very rare, task identifiers are not guaranteed to be unique. - To get the task ID of the currently executing task from within code that task is executing, use the property. + To get the task ID of the currently executing task from within code that task is executing, use the property. ]]> @@ -3708,7 +3708,7 @@ This method is intended for compiler use rather than use directly in code. - The task acknowledged the cancellation request on its already signaled by calling the method on the . > [!IMPORTANT] -> Retrieving the value of the property does not block the calling thread until the task has completed. +> Retrieving the value of the property does not block the calling thread until the task has completed. ]]> @@ -3772,7 +3772,7 @@ This method is intended for compiler use rather than use directly in code. ## Remarks > [!IMPORTANT] -> Retrieving the value of the property does not block the calling thread until the task has completed. +> Retrieving the value of the property does not block the calling thread until the task has completed. ]]> @@ -3876,10 +3876,10 @@ This method is intended for compiler use rather than use directly in code. is `true`, the task's is equal to , and its property will be non-null. + If is `true`, the task's is equal to , and its property will be non-null. > [!IMPORTANT] -> Retrieving the value of the property does not block the calling thread until the task has completed. +> Retrieving the value of the property does not block the calling thread until the task has completed. ]]> @@ -3957,7 +3957,7 @@ This method is intended for compiler use rather than use directly in code. - Its cancellation token is . -- Its property value is . +- Its property value is . - It uses the default task scheduler. @@ -4116,7 +4116,7 @@ This method is intended for compiler use rather than use directly in code. The method is a simpler alternative to the method. It creates a task with the following default values: -- Its property value is . +- Its property value is . - It uses the default task scheduler. @@ -4354,7 +4354,7 @@ This method is intended for compiler use rather than use directly in code. - Its cancellation token is . -- Its property value is . +- Its property value is . - It uses the default task scheduler. @@ -4527,7 +4527,7 @@ This method is intended for compiler use rather than use directly in code. The method is a simpler alternative to the method. It creates a task with the following default values: -- Its property value is . +- Its property value is . - It uses the default task scheduler. @@ -4542,7 +4542,7 @@ This method is intended for compiler use rather than use directly in code. :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run7.fs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/.ctor/Run7.vb" id="Snippet7"::: - Instead of using the property to examine exceptions, the example iterates all tasks to determine which have completed successfully and which have been cancelled. For those that have completed, it displays the value returned by the task. + Instead of using the property to examine exceptions, the example iterates all tasks to determine which have completed successfully and which have been cancelled. For those that have completed, it displays the value returned by the task. Because cancellation is cooperative, each task can decide how to respond to cancellation. The following example is like the first, except that, once the token is cancelled, tasks return the number of iterations they've completed rather than throw an exception. @@ -4886,14 +4886,14 @@ This method is intended for compiler use rather than use directly in code. property does not block the calling thread until the task has completed. + Retrieving the value of the property does not block the calling thread until the task has completed. For more information and an example, see [Chaining Tasks by Using Continuation Tasks](/dotnet/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks) and [How to: Cancel a Task and Its Children](/dotnet/standard/parallel-programming/how-to-cancel-a-task-and-its-children). ## Examples - The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example then examines the property of each task to indicate whether it completed successfully or was cancelled. For those that completed, it displays the value returned by the task. + The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example then examines the property of each task to indicate whether it completed successfully or was cancelled. For those that completed, it displays the value returned by the task. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run7.cs" id="Snippet7"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run7.fs" id="Snippet7"::: @@ -5147,7 +5147,7 @@ This member is an explicit interface member implementation. It can be used only - The task completes successfully. -- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. +- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. - The interval defined by `millisecondsTimeout` elapses. In this case, the current thread resumes execution and the method returns `false`. @@ -5303,7 +5303,7 @@ This member is an explicit interface member implementation. It can be used only - The task completes successfully. -- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. +- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. - The interval defined by `timeout` elapses. In this case, the current thread resumes execution and the method returns `false`. @@ -5389,7 +5389,7 @@ This member is an explicit interface member implementation. It can be used only - The task completes successfully. -- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. +- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. - The `cancellationToken` cancellation token is canceled. In this case, the call to the method throws an . @@ -6558,7 +6558,7 @@ An exception was thrown during ## Examples - The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. + The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/WhenAll4.cs" id="Snippet4"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/WhenAll4.fs" id="Snippet4"::: @@ -6704,7 +6704,7 @@ An exception was thrown during ## Examples - The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is converted to an array and passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. + The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is converted to an array and passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/WhenAll3.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/WhenAll3.fs" id="Snippet3"::: @@ -6777,13 +6777,13 @@ An exception was thrown during method does not block the calling thread. However, a call to the returned property does block the calling thread. + The call to method does not block the calling thread. However, a call to the returned property does block the calling thread. If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. - If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The property of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's property will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. + If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The property of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's property will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. If the `tasks` argument contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. The returned `TResult[]` will be an array of 0 elements. @@ -6945,7 +6945,7 @@ An exception was thrown during method does not block the calling thread. However, a call to the returned property does block the calling thread. + The call to method does not block the calling thread. However, a call to the returned property does block the calling thread. If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. diff --git a/xml/System.Threading.Tasks/TaskCanceledException.xml b/xml/System.Threading.Tasks/TaskCanceledException.xml index e42946a3a9f..51d0668e4c6 100644 --- a/xml/System.Threading.Tasks/TaskCanceledException.xml +++ b/xml/System.Threading.Tasks/TaskCanceledException.xml @@ -127,7 +127,7 @@ property of the new instance to a system-supplied message that describes the error. This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error. This message takes into account the current system culture. The following table shows the initial property values for an instance of : @@ -372,7 +372,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Threading.Tasks/TaskCompletionSource`1.xml b/xml/System.Threading.Tasks/TaskCompletionSource`1.xml index e9101e7c745..6d263d57094 100644 --- a/xml/System.Threading.Tasks/TaskCompletionSource`1.xml +++ b/xml/System.Threading.Tasks/TaskCompletionSource`1.xml @@ -242,7 +242,7 @@ created by this instance and accessible through its property will be instantiated using the specified `creationOptions`. + The created by this instance and accessible through its property will be instantiated using the specified `creationOptions`. ]]> @@ -651,7 +651,7 @@ that is controlled by this instance. When you create a object, the property of this object returns + This property enables a consumer to access the that is controlled by this instance. When you create a object, the property of this object returns The , , , and methods (and their "Try" variants) on this instance all result in the relevant state transitions on this underlying Task. diff --git a/xml/System.Threading.Tasks/TaskFactory.xml b/xml/System.Threading.Tasks/TaskFactory.xml index 858e0fb31ca..d9edc18fb8f 100644 --- a/xml/System.Threading.Tasks/TaskFactory.xml +++ b/xml/System.Threading.Tasks/TaskFactory.xml @@ -90,15 +90,15 @@ - Create a task that starts when all the tasks in an array have completed by calling the method. - The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. + The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/Overview/program.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_factories/vb/factories_vb.vb" id="Snippet1"::: - In most cases, you do not have to instantiate a new instance. Instead, you can use the property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. + In most cases, you do not have to instantiate a new instance. Instead, you can use the property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. ## Examples - The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. + The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Factory/factory1.vb" id="Snippet1"::: @@ -581,7 +581,7 @@ ## Remarks The method executes the `continuationAction` delegate when all tasks in the `tasks` array have completed, regardless of their completion status. - Exceptions thrown by tasks in the `tasks` array are not available to the continuation task through structured exception handling. You can determine which exceptions were thrown by examining the property of each task in the `tasks` array. To use structured exception handling to handle exceptions thrown by tasks in the `tasks` array, call the method. + Exceptions thrown by tasks in the `tasks` array are not available to the continuation task through structured exception handling. You can determine which exceptions were thrown by examining the property of each task in the `tasks` array. To use structured exception handling to handle exceptions thrown by tasks in the `tasks` array, call the method. @@ -591,7 +591,7 @@ :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory/ContinueWhenAll/continuewhenall1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskFactory/ContinueWhenAll/continuewhenall1.vb" id="Snippet1"::: - The call to the continuation task's method does not allow it to handle exceptions thrown by the antecedent tasks, so the example examines the property of each antecedent task to determine whether the task succeeded. + The call to the continuation task's method does not allow it to handle exceptions thrown by the antecedent tasks, so the example examines the property of each antecedent task to determine whether the task succeeded. ]]> @@ -5548,7 +5548,7 @@ The NotOn\* and OnlyOn\* , ## Remarks The property value is used to schedule all tasks, unless another scheduler is explicitly specified during calls to this factory's methods. - If this property value is `null`, the value of the property is used. + If this property value is `null`, the value of the property is used. ]]> diff --git a/xml/System.Threading.Tasks/TaskFactory`1.xml b/xml/System.Threading.Tasks/TaskFactory`1.xml index af787655b1f..d0a5f6a2663 100644 --- a/xml/System.Threading.Tasks/TaskFactory`1.xml +++ b/xml/System.Threading.Tasks/TaskFactory`1.xml @@ -98,15 +98,15 @@ - Create a task that starts when all the tasks in an array have completed by calling the or method. - The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. + The static property returns a default object. You can also call one of the class constructors to configure the objects that the class creates. The following example configures a new object to create tasks that have a specified cancellation token, task creation options, continuation options, and a customized task scheduler. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskFactory`1/Overview/factoriestresult.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl_factories/vb/factoriestresult.vb" id="Snippet2"::: - In most cases, you do not have to instantiate a new instance. Instead, you can use the static property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. + In most cases, you do not have to instantiate a new instance. Instead, you can use the static property, which returns a factory object that uses default values. You can then call its methods to start new tasks or define task continuations. For an illustration, see the example. ## Examples - The following example uses the static property to make two calls to the method. The first task returns a string array that is populated with the names of files in the user's MyDocuments directory, while the second returns a string array that is populated with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the arrays returned by the two tasks after they have completed execution. + The following example uses the static property to make two calls to the method. The first task returns a string array that is populated with the names of files in the user's MyDocuments directory, while the second returns a string array that is populated with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the arrays returned by the two tasks after they have completed execution. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory2.cs" id="Snippet2"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/Factory/factory2.vb" id="Snippet2"::: diff --git a/xml/System.Threading.Tasks/TaskSchedulerException.xml b/xml/System.Threading.Tasks/TaskSchedulerException.xml index 175bda079cc..f842b001d07 100644 --- a/xml/System.Threading.Tasks/TaskSchedulerException.xml +++ b/xml/System.Threading.Tasks/TaskSchedulerException.xml @@ -126,7 +126,7 @@ property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "DefaultMessageDisplayedByParameterlessCtorWriterMustSupply" This message takes into account the current system culture. The following table shows the initial property values for an instance of . @@ -364,7 +364,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Threading.Tasks/TaskStatus.xml b/xml/System.Threading.Tasks/TaskStatus.xml index c622ed32e0f..75604f5d62f 100644 --- a/xml/System.Threading.Tasks/TaskStatus.xml +++ b/xml/System.Threading.Tasks/TaskStatus.xml @@ -62,12 +62,12 @@ property returns a member of the enumeration to indicate the task's current status. + The property returns a member of the enumeration to indicate the task's current status. ## Examples - The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example then examines the property of each task to indicate whether the task has completed successfully or been cancelled. For those that have completed, it displays the value returned by the task. + The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example then examines the property of each task to indicate whether the task has completed successfully or been cancelled. For those that have completed, it displays the value returned by the task. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run7.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/.ctor/Run7.vb" id="Snippet7"::: diff --git a/xml/System.Threading.Tasks/Task`1.xml b/xml/System.Threading.Tasks/Task`1.xml index 5f95fd098a8..b5a287df83a 100644 --- a/xml/System.Threading.Tasks/Task`1.xml +++ b/xml/System.Threading.Tasks/Task`1.xml @@ -88,14 +88,14 @@ class represents a single operation that returns a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](https://learn.microsoft.com/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap) first introduced in .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. + The class represents a single operation that returns a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](https://learn.microsoft.com/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap) first introduced in .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. instances may be created in a variety of ways. The most common approach, which is available starting with .NET Framework 4.5, is to call the static or method. These methods provide a simple way to start a task by using default values and without acquiring 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/TaskTResult/Overview/run1.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskTResult/Overview/run1.vb" id="Snippet6"::: - An alternative, and the most common way to start a task in .NET Framework 4, is to call the static or method. The property returns a object, and the property returns a object. Overloads of their `StartNew` method let you pass arguments, define task creation options, and specify a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. + An alternative, and the most common way to start a task in .NET Framework 4, is to call the static or method. The property returns a object, and the property returns a object. Overloads of their `StartNew` method let you pass arguments, define task creation options, and specify 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/TaskTResult/Overview/startnew1.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskTResult/Overview/startnew1.vb" id="Snippet7"::: @@ -2398,7 +2398,7 @@ For operations that do not return a value, you use the [!NOTE] > Starting with .NET Framework 4.5, the method provides the easiest way to create a object with default configuration values. - The following example uses the static property to make three calls to the method. The first starts a `Task` object, which executes a lambda expression that returns 1. The second starts a `Task` object, which executes a lambda expression that instantiates a new `Test` instance. The third starts a `Task` object, which enumerates the files in the C:\Users\Public\Pictures\Sample Pictures\ directory. (Note that successful execution of the example requires that the directory exist and that it contain files. + The following example uses the static property to make three calls to the method. The first starts a `Task` object, which executes a lambda expression that returns 1. The second starts a `Task` object, which executes a lambda expression that instantiates a new `Test` instance. The third starts a `Task` object, which enumerates the files in the C:\Users\Public\Pictures\Sample Pictures\ directory. (Note that successful execution of the example requires that the directory exist and that it contain files. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task`1/Factory/returnavalue10.cs" id="Snippet10"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Misc/tpl/vb/10_returnavalue.vb" id="Snippet10"::: @@ -2527,12 +2527,12 @@ This method is intended for compiler use rather than use directly in code. ## Remarks Accessing the property's get accessor blocks the calling thread until the asynchronous operation is complete; it is equivalent to calling the method. - Once the result of an operation is available, it is stored and is returned immediately on subsequent calls to the property. Note that, if an exception occurred during the operation of the task, or if the task has been cancelled, the property does not return a value. Instead, attempting to access the property value throws an exception. + Once the result of an operation is available, it is stored and is returned immediately on subsequent calls to the property. Note that, if an exception occurred during the operation of the task, or if the task has been cancelled, the property does not return a value. Instead, attempting to access the property value throws an exception. ## Examples - The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. If the directory contains files, it executes a lambda expression that instantiates a object for each file in the directory and retrieves the value of its property. If a directory contains no files, it simply calls the method to create a task whose property is zero (0). When the tasks finish, the total number of bytes in all a directory's files is available from the property. + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. If the directory contains files, it executes a lambda expression that instantiates a object for each file in the directory and retrieves the value of its property. If a directory contains no files, it simply calls the method to create a task whose property is zero (0). When the tasks finish, the total number of bytes in all a directory's files is available from the property. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.vb" id="Snippet1"::: diff --git a/xml/System.Threading/AbandonedMutexException.xml b/xml/System.Threading/AbandonedMutexException.xml index 63fd69443ae..073ca86e46e 100644 --- a/xml/System.Threading/AbandonedMutexException.xml +++ b/xml/System.Threading/AbandonedMutexException.xml @@ -81,7 +81,7 @@ ## Examples - The following code example executes a thread that abandons five mutexes, demonstrating their effects on the , , and methods. The value of the property is displayed for the call. + The following code example executes a thread that abandons five mutexes, demonstrating their effects on the , , and methods. The value of the property is displayed for the call. > [!NOTE] > The call to the method is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. @@ -146,7 +146,7 @@ property of the new instance to a system-supplied message that describes the error, such as "The wait completed due to an abandoned mutex." This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "The wait completed due to an abandoned mutex." This message takes into account the current system culture. The following table shows the initial property values for an instance of . @@ -272,7 +272,7 @@ property of the new instance to a system-supplied message that describes the error, such as "The wait completed due to an abandoned mutex." This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "The wait completed due to an abandoned mutex." This message takes into account the current system culture. The following table shows the initial property values for an instance of initialized with this constructor. @@ -404,7 +404,7 @@ ## Remarks The content of `message` is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 initialized with this constructor. @@ -540,7 +540,7 @@ ## Remarks The content of `message` is a text string intended to inform the user about the exception. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 initialized with this constructor. @@ -659,7 +659,7 @@ ## Examples - The following code example executes a thread that abandons five mutexes. The abandoned mutexes are used to demonstrate the effects on the , , and method calls. The value of the property is displayed for the call. + The following code example executes a thread that abandons five mutexes. The abandoned mutexes are used to demonstrate the effects on the , , and method calls. The value of the property is displayed for the call. > [!NOTE] > The call to is interrupted by one of the abandoned mutexes. The other abandoned mutex could still cause an to be thrown by subsequent wait methods. diff --git a/xml/System.Threading/ApartmentState.xml b/xml/System.Threading/ApartmentState.xml index b290b298c02..12056908b05 100644 --- a/xml/System.Threading/ApartmentState.xml +++ b/xml/System.Threading/ApartmentState.xml @@ -61,7 +61,7 @@ ## Remarks An apartment is a logical container within a process for objects sharing the same thread access requirements. All objects in the same apartment can receive calls from any thread in the apartment. The .NET Framework does not use apartments, and managed objects are responsible for using all shared resources in a thread-safe manner themselves. - Because COM classes use apartments, the common language runtime needs to create and initialize an apartment when calling a COM object in a COM interop situation. A managed thread can create and enter a single-threaded apartment (STA) that allows only one thread, or a multithreaded apartment (MTA) that contains one or more threads. You can control the type of apartment created by setting the property of the thread to one of the values of the enumeration. Because a given thread can only initialize a COM apartment once, you cannot change the apartment type after the first call to the unmanaged code. + Because COM classes use apartments, the common language runtime needs to create and initialize an apartment when calling a COM object in a COM interop situation. A managed thread can create and enter a single-threaded apartment (STA) that allows only one thread, or a multithreaded apartment (MTA) that contains one or more threads. You can control the type of apartment created by setting the property of the thread to one of the values of the enumeration. Because a given thread can only initialize a COM apartment once, you cannot change the apartment type after the first call to the unmanaged code. For more information, see , [Managed and Unmanaged Threading](/previous-versions/dotnet/netframework-4.0/5s8ee185(v=vs.100)), and [Advanced COM Interoperability](/previous-versions/dotnet/netframework-4.0/bd9cdfyx(v=vs.100)). diff --git a/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml b/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml index e14fed37b5e..8dd1fe7a4d2 100644 --- a/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml +++ b/xml/System.Threading/AsyncLocalValueChangedArgs`1.xml @@ -60,11 +60,11 @@ The type of the data. The class that provides data change information to instances that register for change notifications. - objects receives change notifications when it is instantiated by calling its constructor. - + objects receives change notifications when it is instantiated by calling its constructor. + ]]> @@ -193,11 +193,11 @@ if the value changed because of a change of execution context; otherwise, . - property is changed explicitly. - + property is changed explicitly. + ]]> diff --git a/xml/System.Threading/AsyncLocal`1.xml b/xml/System.Threading/AsyncLocal`1.xml index c29b81e246c..32f9479125b 100644 --- a/xml/System.Threading/AsyncLocal`1.xml +++ b/xml/System.Threading/AsyncLocal`1.xml @@ -62,21 +62,21 @@ The type of the ambient data. Represents ambient data that is local to a given asynchronous control flow, such as an asynchronous method. - instances can be used to persist data across threads. - - The class also provides optional notifications when the value associated with the current thread changes, either because it was explicitly changed by setting the property, or implicitly changed when the thread encountered an `await` or other context transition. - - - -## Examples - The following example uses the class to persist a string value across an asynchronous flow. It also contrasts the use of with . - + instances can be used to persist data across threads. + + The class also provides optional notifications when the value associated with the current thread changes, either because it was explicitly changed by setting the property, or implicitly changed when the thread encountered an `await` or other context transition. + + + +## Examples + The following example uses the class to persist a string value across an asynchronous flow. It also contrasts the use of with . + :::code language="csharp" source="~/snippets/csharp/System.Threading/AsyncLocalT/Overview/Example1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading/AsyncLocalT/Overview/Example1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Threading/AsyncLocalT/Overview/Example1.vb" id="Snippet1"::: + ]]> @@ -181,11 +181,11 @@ The delegate that is called whenever the current value changes on any thread. Instantiates an local instance that receives change notifications. - >`. - + ]]> diff --git a/xml/System.Threading/BarrierPostPhaseException.xml b/xml/System.Threading/BarrierPostPhaseException.xml index 55570cd9071..4ddf6420fd2 100644 --- a/xml/System.Threading/BarrierPostPhaseException.xml +++ b/xml/System.Threading/BarrierPostPhaseException.xml @@ -120,7 +120,7 @@ property of the new instance to a system-supplied message that describes the error, such as "The postPhaseAction failed with an exception." This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "The postPhaseAction failed with an exception." This message takes into account the current system culture. The following table shows the initial property values for an instance of . @@ -366,7 +366,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Threading/CancellationToken.xml b/xml/System.Threading/CancellationToken.xml index fc4237cb042..2b458fedc2b 100644 --- a/xml/System.Threading/CancellationToken.xml +++ b/xml/System.Threading/CancellationToken.xml @@ -87,23 +87,23 @@ Propagates notification that operations should be canceled. - enables cooperative cancellation between threads, thread pool work items, or objects. You create a cancellation token by instantiating a object, which manages cancellation tokens retrieved from its property. You then pass the cancellation token to any number of threads, tasks, or operations that should receive notice of cancellation. The token cannot be used to initiate cancellation. When the owning object calls , the property on every copy of the cancellation token is set to `true`. The objects that receive the notification can respond in whatever manner is appropriate. - - For more information and code examples see [Cancellation in Managed Threads](/dotnet/standard/threading/cancellation-in-managed-threads). - - - -## Examples - The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. - + enables cooperative cancellation between threads, thread pool work items, or objects. You create a cancellation token by instantiating a object, which manages cancellation tokens retrieved from its property. You then pass the cancellation token to any number of threads, tasks, or operations that should receive notice of cancellation. The token cannot be used to initiate cancellation. When the owning object calls , the property on every copy of the cancellation token is set to `true`. The objects that receive the notification can respond in whatever manner is appropriate. + + For more information and code examples see [Cancellation in Managed Threads](/dotnet/standard/threading/cancellation-in-managed-threads). + + + +## Examples + The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. + To handle the possible cancellation of the operation, the example instantiates a object that generates a cancellation token that's passed to a object. In turn, the object passes the cancellation token to each of the tasks responsible for collecting readings for a particular instrument. The method is called to ensure that the mean is computed only after all readings have been gathered successfully. If a task has not completed because it was cancelled, the method throws an exception. - + :::code language="csharp" source="~/snippets/csharp/System.Threading/CancellationToken/Overview/cancel1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/Overview/cancel1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/Overview/cancel1.vb" id="Snippet1"::: + ]]> All public and protected members of are thread-safe and may be used concurrently from multiple threads. @@ -154,13 +154,13 @@ To handle the possible cancellation of the operation, the example instantiates a The canceled state for the token. Initializes the . - and will be `false`. - - If `canceled` is `true`, both and will be `true`. - + and will be `false`. + + If `canceled` is `true`, both and will be `true`. + ]]> Cancellation @@ -217,13 +217,13 @@ To handle the possible cancellation of the operation, the example instantiates a if this token is capable of being in the canceled state; otherwise, . - returns `false`, it is guaranteed that the token will never transition into a canceled state, meaning that will never return `true`. A cancellation token that cannot be canceled is returned by the static property. - - You can optionally use this property to determine whether a cancellation token can be canceled before examining the value of the property to determine whether it has been canceled. - + returns `false`, it is guaranteed that the token will never transition into a canceled state, meaning that will never return `true`. A cancellation token that cannot be canceled is returned by the static property. + + You can optionally use this property to determine whether a cancellation token can be canceled before examining the value of the property to determine whether it has been canceled. + ]]> Cancellation @@ -296,10 +296,10 @@ To handle the possible cancellation of the operation, the example instantiates a if is a and if the two instances are equal; otherwise, . See the Remarks section for more information. - . @@ -367,10 +367,10 @@ Two cancellation tokens are equal if any one of the following conditions is true if the instances are equal; otherwise, . See the Remarks section for more information. - . @@ -480,25 +480,25 @@ Two cancellation tokens are equal if any one of the following conditions is true if cancellation has been requested for this token; otherwise, . - on the token's associated . - - If this property is `true`, it only guarantees that cancellation has been requested. It does not guarantee that every registered handler has finished executing, nor that cancellation requests have finished propagating to all registered handlers. Additional synchronization may be required, particularly in situations where related objects are being canceled concurrently. - - - -## Examples - The following is a simple example that executes a server process until the property returns `true`. - + on the token's associated . + + If this property is `true`, it only guarantees that cancellation has been requested. It does not guarantee that every registered handler has finished executing, nor that cancellation requests have finished propagating to all registered handlers. Additional synchronization may be required, particularly in situations where related objects are being canceled concurrently. + + + +## Examples + The following is a simple example that executes a server process until the property returns `true`. + :::code language="csharp" source="~/snippets/csharp/System.Threading/CancellationToken/IsCancellationRequested/cancellation.cs" id="Snippet12"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/IsCancellationRequested/cancelthreads.vb" id="Snippet12"::: - - The example instantiates a object, which controls access to the cancellation token. It then defines two thread procedures. The first is defined as a lambda expression that pools the keyboard and, when the "C" key is pressed, calls to set the cancellation token to the cancelled state. The second is a parameterized method, `ServerClass.StaticMethod`, that executes a loop until the property is `true`. - - The main thread then starts the two threads and blocks until the thread that executes the `ServerClass.StaticMethod` method terminates. - + :::code language="vb" source="~/snippets/visualbasic/System.Threading/CancellationToken/IsCancellationRequested/cancelthreads.vb" id="Snippet12"::: + + The example instantiates a object, which controls access to the cancellation token. It then defines two thread procedures. The first is defined as a lambda expression that pools the keyboard and, when the "C" key is pressed, calls to set the cancellation token to the cancelled state. The second is a parameterized method, `ServerClass.StaticMethod`, that executes a loop until the property is `true`. + + The main thread then starts the two threads and blocks until the thread that executes the `ServerClass.StaticMethod` method terminates. + ]]> Cancellation @@ -554,15 +554,15 @@ Two cancellation tokens are equal if any one of the following conditions is true Returns an empty value. An empty cancellation token. - property is `false`. - - You can also use the C# [default(CancellationToken)](/dotnet/csharp/language-reference/keywords/default) statement to create an empty cancellation token. + property is `false`. + + You can also use the C# [default(CancellationToken)](/dotnet/csharp/language-reference/keywords/default) statement to create an empty cancellation token. Two empty cancellation tokens are always equal. - + ]]> Cancellation @@ -619,10 +619,10 @@ Two cancellation tokens are equal if any one of the following conditions is true if the instances are equal; otherwise, See the Remarks section for more information. - . @@ -686,10 +686,10 @@ Two cancellation tokens are equal if any one of the following conditions is true if the instances are not equal; otherwise, . - method. +For the definition of equality, see the method. ]]> An associated has been disposed. @@ -756,15 +756,15 @@ For the definition of equality, see the Registers a delegate that will be called when this is canceled.
The instance that can be used to unregister the callback. - is captured along with the delegate and will be used when executing it. + is captured along with the delegate and will be used when executing it. The current is not captured. - + ]]> The associated has been disposed. @@ -824,15 +824,15 @@ For the definition of equality, see the Registers a delegate that will be called when this is canceled. The instance that can be used to unregister the callback. - is captured along with the delegate and will be used when executing it. + is captured along with the delegate and will be used when executing it. If `useSynchronizationContext` is `true`, the current , if one exists, is also captured along with the delegate and will be used when executing it. Otherwise, is not captured. - + ]]> The associated has been disposed. @@ -960,15 +960,15 @@ is captured along with the delegate and is used when executing it. The current < Registers a delegate that will be called when this is canceled. The instance that can be used to unregister the callback. - is captured along with the delegate and will be used when executing it. + is captured along with the delegate and will be used when executing it. The current is not captured. - + ]]> The associated has been disposed. @@ -1038,15 +1038,15 @@ is captured along with the delegate and is used when executing it. The current < Registers a delegate that will be called when this is canceled. The instance that can be used to unregister the callback. - is captured along with the delegate and will be used when executing it. + is captured along with the delegate and will be used when executing it. If `useSynchronizationContext` is `true`, the current , if one exists, is also captured along with the delegate and will be used when executing it. Otherwise, is not captured. - + ]]> The associated has been disposed. @@ -1106,24 +1106,24 @@ is captured along with the delegate and is used when executing it. The current < Throws a if this token has had cancellation requested. - The token has had cancellation requested. @@ -1238,13 +1238,13 @@ generates is propagated out of this method call. The delegate to execute when the is canceled. The state to pass to the when the delegate is invoked. This may be . Registers a delegate that is called when this is canceled. - An object that can + An object that can be used to unregister the callback. is not captured or flowed to the callback's invocation. ]]> @@ -1302,11 +1302,11 @@ The is not captured or flowed Gets a that is signaled when the token is canceled. A that is signaled when the token is canceled. - to be instantiated. It is preferable to only use this property when necessary, and to then dispose the associated instance at the earliest opportunity (disposing the source will dispose of this allocated handle). The handle should not be closed or disposed directly. - + to be instantiated. It is preferable to only use this property when necessary, and to then dispose the associated instance at the earliest opportunity (disposing the source will dispose of this allocated handle). The handle should not be closed or disposed directly. + ]]> The associated has been disposed. diff --git a/xml/System.Threading/CancellationTokenSource.xml b/xml/System.Threading/CancellationTokenSource.xml index a1cd1c5b778..83e936e3058 100644 --- a/xml/System.Threading/CancellationTokenSource.xml +++ b/xml/System.Threading/CancellationTokenSource.xml @@ -80,7 +80,7 @@ ## Remarks Starting with the .NET Framework 4, the .NET Framework uses a unified model for cooperative cancellation of asynchronous or long-running synchronous operations that involves two objects: -- A object, which provides a cancellation token through its property and sends a cancellation message by calling its or method. +- A object, which provides a cancellation token through its property and sends a cancellation message by calling its or method. - A object, which indicates whether cancellation is requested. @@ -88,11 +88,11 @@ - Instantiate a object, which manages and sends cancellation notification to the individual cancellation tokens. -- Pass the token returned by the property to each task or thread that listens for cancellation. +- Pass the token returned by the property to each task or thread that listens for cancellation. - Call the method from operations that receive the cancellation token. Provide a mechanism for each task or thread to respond to a cancellation request. Whether you choose to cancel an operation, and exactly how you do it, depends on your application logic. -- Call the method to provide notification of cancellation. This sets the property on every copy of the cancellation token to `true`. +- Call the method to provide notification of cancellation. This sets the property on every copy of the cancellation token to `true`. - Call the method when you are finished with the object. @@ -386,18 +386,18 @@ Communicates a request for cancellation. - is notified of the cancellation and transitions to a state where returns true. -The associated is notified of the cancellation and transitions to a state where returns true. - Any callbacks or cancelable operations registered with the are executed, if they haven't already been executed by a previous call to . Subsequent calls to won't execute the same callback again unless reregistered. (Avoid multiple calls to , because the intent of such code is often unclear.) -Callbacks are executed synchronously in LIFO order. +Callbacks are executed synchronously in LIFO order. We recommend that cancelable operations and callbacks registered with not throw exceptions. - + This overload of Cancel aggregates any exceptions thrown into an , such that one callback throwing an exception will not prevent other registered callbacks from being executed. Calling this method has the same effect as calling [`Cancel(false)`](xref:System.Threading.CancellationTokenSource.Cancel(System.Boolean)). @@ -466,21 +466,21 @@ To handle the possible cancellation of the operation, the example instantiates a if exceptions should immediately propagate; otherwise, . Communicates a request for cancellation, and specifies whether remaining callbacks and cancelable operations should be processed if an exception occurs. - is notified of the cancellation and transitions to a state where returns `true`. -The associated is notified of the cancellation and transitions to a state where returns `true`. - Any callbacks or cancelable operations registered with the are executed, if they haven't already been executed by a previous call to . Subsequent calls to won't execute the same callback again unless reregistered. (Avoid multiple calls to , because the intent of such code is often unclear.) Callbacks are executed synchronously in LIFO order. - -We recommend that cancelable operations and callbacks registered with not throw exceptions. - -If `throwOnFirstException` is `true`, an exception will immediately propagate out of the call to , preventing the remaining callbacks and cancelable operations from being processed. -If `throwOnFirstException` is `false`, this overload aggregates any exceptions thrown into an , such that one callback throwing an exception will not prevent other registered callbacks from being executed. +We recommend that cancelable operations and callbacks registered with not throw exceptions. + +If `throwOnFirstException` is `true`, an exception will immediately propagate out of the call to , preventing the remaining callbacks and cancelable operations from being processed. + +If `throwOnFirstException` is `false`, this overload aggregates any exceptions thrown into an , such that one callback throwing an exception will not prevent other registered callbacks from being executed. ]]> diff --git a/xml/System.Threading/CountdownEvent.xml b/xml/System.Threading/CountdownEvent.xml index 49dad543cbc..9732118bccc 100644 --- a/xml/System.Threading/CountdownEvent.xml +++ b/xml/System.Threading/CountdownEvent.xml @@ -496,7 +496,7 @@ does not raise an event when the countdown has reached zero. Instead, the property equals zero, and the property equals `true`. + The does not raise an event when the countdown has reached zero. Instead, the property equals zero, and the property equals `true`. ]]> diff --git a/xml/System.Threading/HostExecutionContext.xml b/xml/System.Threading/HostExecutionContext.xml index cb5f8e217ee..3830adbe977 100644 --- a/xml/System.Threading/HostExecutionContext.xml +++ b/xml/System.Threading/HostExecutionContext.xml @@ -60,11 +60,11 @@ Encapsulates and propagates the host execution context across threads. - is part of a larger . The host context migrates, or flows, with the execution context. - + is part of a larger . The host context migrates, or flows, with the execution context. + ]]> @@ -114,11 +114,11 @@ Initializes a new instance of the class. - property value is `null`. - + property value is `null`. + ]]> @@ -163,11 +163,11 @@ An object representing the host execution context state. Initializes a new instance of the class using the specified state. - is included with the . The `state` represents a safe handle containing the `IUnknown` pointer for the host. - + is included with the . The `state` represents a safe handle containing the `IUnknown` pointer for the host. + ]]> @@ -218,11 +218,11 @@ Creates a copy of the current host execution context. A object representing the host context for the current thread. - method call. - + method call. + ]]> @@ -278,16 +278,16 @@ Releases all resources used by the current instance of the class. - . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - - For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + + For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + > [!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. - +> 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. + ]]> Cleaning Up Unmanaged Resources @@ -335,15 +335,15 @@ to release both managed and unmanaged resources; to release only unmanaged resources. When overridden in a derived class, releases the unmanaged resources used by the , and optionally releases the managed resources. - method overload and the finalizer. invokes this protected method with the `disposing` parameter set to `true`. The finalizer 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. - - This method can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed in an earlier call. - + method overload and the finalizer. invokes this protected method with the `disposing` parameter set to `true`. The finalizer 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. + + This method can be called multiple times by other objects. When overriding this method, be careful not to reference objects that have been previously disposed in an earlier call. + ]]> @@ -388,11 +388,11 @@ Gets or sets the state of the host execution context. An object representing the host execution context state. - property value represents a safe handle containing the `IUnknown` pointer for the host. - + property value represents a safe handle containing the `IUnknown` pointer for the host. + ]]>
diff --git a/xml/System.Threading/HostExecutionContextManager.xml b/xml/System.Threading/HostExecutionContextManager.xml index 32e677f1013..adefb7bdf4d 100644 --- a/xml/System.Threading/HostExecutionContextManager.xml +++ b/xml/System.Threading/HostExecutionContextManager.xml @@ -51,11 +51,11 @@ Provides the functionality that allows a common language runtime host to participate in the flow, or migration, of the execution context. - has a reference to a in its property, then the common language runtime calls the manager every time a call to the method occurs, to allow the host to participate in the flow of the execution context. - + has a reference to a in its property, then the common language runtime calls the manager every time a call to the method occurs, to allow the host to participate in the flow of the execution context. + ]]> @@ -144,11 +144,11 @@ Captures the host execution context from the current thread. A object representing the host execution context of the current thread. - is created using a safe handle containing the `IUnknown` pointer for the host executing the current thread. - + is created using a safe handle containing the `IUnknown` pointer for the host executing the current thread. + ]]>
@@ -205,22 +205,22 @@ The previous context state to revert to. Restores the host execution context to its prior state. - method. - + method. + ]]> - is . - - -or- - - was not created on the current thread. - - -or- - + is . + + -or- + + was not created on the current thread. + + -or- + is not the last state for the .
@@ -273,20 +273,20 @@ Sets the current host execution context to the specified host execution context. An object for restoring the to its previous state. - method sets the host execution context for the current . A that has been used as the argument to another method call cannot be passed in as the parameter for this method. Instead, use the method to create a copy of a object and then use the copy to set the host execution context. - - Call the method using the object returned by this method to restore the to its previous state. - + method sets the host execution context for the current . A that has been used as the argument to another method call cannot be passed in as the parameter for this method. Instead, use the method to create a copy of a object and then use the copy to set the host execution context. + + Call the method using the object returned by this method to restore the to its previous state. + ]]> - was not acquired through a capture operation. - - -or- - + was not acquired through a capture operation. + + -or- + has been the argument to a previous method call.
diff --git a/xml/System.Threading/LazyThreadSafetyMode.xml b/xml/System.Threading/LazyThreadSafetyMode.xml index a6dbca61f42..ab8e633287f 100644 --- a/xml/System.Threading/LazyThreadSafetyMode.xml +++ b/xml/System.Threading/LazyThreadSafetyMode.xml @@ -58,9 +58,9 @@ ## Remarks Use this enumeration to specify the `mode` parameter of constructors. The effects of all constructors on thread synchronization can be described in terms of this enumeration, whether or not they have `mode` parameters. - A instance is initialized either by a user-specified initialization method or by the parameterless constructor for `T`. The initialization method is specified by the `valueFactory` parameter of a constructor. The method returns an instance of `T`, which is the type that is lazily instantiated by the instance of . If a constructor does not have a `valueFactory` parameter, the parameterless constructor for `T` is used to initialize the instance. In either case, initialization occurs the first time you call the property. + A instance is initialized either by a user-specified initialization method or by the parameterless constructor for `T`. The initialization method is specified by the `valueFactory` parameter of a constructor. The method returns an instance of `T`, which is the type that is lazily instantiated by the instance of . If a constructor does not have a `valueFactory` parameter, the parameterless constructor for `T` is used to initialize the instance. In either case, initialization occurs the first time you call the property. - In addition to specifying the thread safety of a instance, this enumeration affects exception caching. When exceptions are cached for a instance, you get only one chance to initialize the instance. If an exception is thrown the first time you call the property, that exception is cached and rethrown on all subsequent calls to the property. The advantage of caching exceptions is that any two threads always get the same result, even when errors occur. + In addition to specifying the thread safety of a instance, this enumeration affects exception caching. When exceptions are cached for a instance, you get only one chance to initialize the instance. If an exception is thrown the first time you call the property, that exception is cached and rethrown on all subsequent calls to the property. The advantage of caching exceptions is that any two threads always get the same result, even when errors occur. When you specify the PublicationOnly mode, exceptions are never cached. When you specify None or ExecutionAndPublication, caching depends on whether you specify an initialization method or allow the parameterless constructor for `T` to be used. Specifying an initialization method enables exception caching for these two modes. The initialization method can be very simple. For example, it might call the parameterless constructor for `T`: `new Lazy(() => new Contents(), mode)` in C#, or `New Lazy(Of Contents)(Function() New Contents())` in Visual Basic. If you use a constructor that does not specify an initialization method, exceptions that are thrown by the parameterless constructor for `T` are not cached. The following table summarizes exception caching behavior. diff --git a/xml/System.Threading/LockRecursionException.xml b/xml/System.Threading/LockRecursionException.xml index 75786d59868..135234acb6f 100644 --- a/xml/System.Threading/LockRecursionException.xml +++ b/xml/System.Threading/LockRecursionException.xml @@ -146,7 +146,7 @@ property of the new instance to a system-supplied message that describes the error, such as "Recursive read lock acquisitions not allowed in this mode." This message takes the current system culture into account. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "Recursive read lock acquisitions not allowed in this mode." This message takes the current system culture into account. The following table shows the initial property values for an instance of . @@ -208,7 +208,7 @@ property of the new exception with the `message` parameter. The content of `message` is intended to be understood by humans. The caller of this constructor must make sure that this string has been localized for the current system culture. + This constructor initializes the property of the new exception with the `message` parameter. The content of `message` is intended to be understood by humans. The caller of this constructor must make sure that this string has been localized for the current system culture. The following table shows the initial property values for an instance of . @@ -336,7 +336,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Threading/LockRecursionPolicy.xml b/xml/System.Threading/LockRecursionPolicy.xml index 54e333d6f74..dc4f0047b6a 100644 --- a/xml/System.Threading/LockRecursionPolicy.xml +++ b/xml/System.Threading/LockRecursionPolicy.xml @@ -47,27 +47,27 @@ Specifies whether a lock can be entered multiple times by the same thread. - class does not allow a thread to enter the lock in write mode if it already entered the lock in read mode, regardless of the lock policy setting, in order to reduce the chance of deadlocks. - - Currently only one lock uses this enumeration: - -- . For more information, see the property. - - - -## Examples - The following example shows two exception scenarios, one that depends on the setting and one that does not. - - In the first scenario, the thread enters the lock in read mode and then tries to enter read mode recursively. If the is created by using the parameterless constructor, which sets recursion policy to NoRecursion, an exception is thrown. If SupportsRecursion is used to create the , no exception is thrown. - - In the second scenario, the thread enters the lock in read mode and then tries to enter the lock in write mode. is thrown regardless of the lock recursion policy. - + class does not allow a thread to enter the lock in write mode if it already entered the lock in read mode, regardless of the lock policy setting, in order to reduce the chance of deadlocks. + + Currently only one lock uses this enumeration: + +- . For more information, see the property. + + + +## Examples + The following example shows two exception scenarios, one that depends on the setting and one that does not. + + In the first scenario, the thread enters the lock in read mode and then tries to enter read mode recursively. If the is created by using the parameterless constructor, which sets recursion policy to NoRecursion, an exception is thrown. If SupportsRecursion is used to create the , no exception is thrown. + + In the second scenario, the thread enters the lock in read mode and then tries to enter the lock in write mode. is thrown regardless of the lock recursion policy. + :::code language="csharp" source="~/snippets/csharp/System.Threading/LockRecursionPolicy/Overview/example1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading/LockRecursionPolicy/Overview/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Threading/LockRecursionPolicy/Overview/source.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Threading/Overlapped.xml b/xml/System.Threading/Overlapped.xml index 68d34cd3c57..0917cb58c9c 100644 --- a/xml/System.Threading/Overlapped.xml +++ b/xml/System.Threading/Overlapped.xml @@ -56,13 +56,13 @@ Provides a managed representation of a Win32 OVERLAPPED structure, including methods to transfer information from an instance to a structure. - and methods transfer information from an object to a structure that can be passed to Windows API functions for asynchronous file I/O. The method transfers information from a structure to an instance of the class. - - Changes to the properties of an object affect its associated structure, and vice versa. - + and methods transfer information from an object to a structure that can be passed to Windows API functions for asynchronous file I/O. The method transfers information from a structure to an instance of the class. + + Changes to the properties of an object affect its associated structure, and vice versa. + ]]> @@ -182,13 +182,13 @@ An object that implements the interface and provides status information on the I/O operation. Initializes a new instance of the class with the specified file position, the 32-bit integer handle to an event that is signaled when the I/O operation is complete, and an interface through which to return the results of the operation. - property to get the handle of any managed synchronization event that derives from the class. - - Your implementation of provides status information on the I/O operation. Pass it to the constructor in the `ar` parameter, and retrieve it later with the property. If a callback method is specified for the or method, the callback can retrieve your by unpacking the structure it receives. - + property to get the handle of any managed synchronization event that derives from the class. + + Your implementation of provides status information on the I/O operation. Pass it to the constructor in the `ar` parameter, and retrieve it later with the property. If a callback method is specified for the or method, the callback can retrieve your by unpacking the structure it receives. + ]]>
@@ -239,13 +239,13 @@ An object that implements the interface and provides status information on the I/O operation. Initializes a new instance of the class with the specified file position, the handle to an event that is signaled when the I/O operation is complete, and an interface through which to return the results of the operation. - class, use the property to get a object, and then call the method. - - Your implementation of provides status information on the I/O operation. Pass it to the constructor in the `ar` parameter, and retrieve it later with the property. If a callback method is specified for the or method, the callback can retrieve your by unpacking the structure it receives. - + class, use the property to get a object, and then call the method. + + Your implementation of provides status information on the I/O operation. Pass it to the constructor in the `ar` parameter, and retrieve it later with the property. If a callback method is specified for the or method, the callback can retrieve your by unpacking the structure it receives. + ]]>
@@ -347,13 +347,13 @@ Gets or sets the 32-bit integer handle to a synchronization event that is signaled when the I/O operation is complete. An value representing the handle of the synchronization event. - property instead. - - Use the property to get the handle of any managed synchronization event that derives from the class. - + property instead. + + Use the property to get the handle of any managed synchronization event that derives from the class. + ]]>
@@ -403,11 +403,11 @@ Gets or sets the handle to the synchronization event that is signaled when the I/O operation is complete. An representing the handle of the event. - class, use the property to get a object, and then call the method. - + class, use the property to get a object, and then call the method. + ]]>
@@ -464,11 +464,11 @@ A pointer to the structure to be freed. Frees the unmanaged memory associated with a native overlapped structure allocated by the method. - method exactly once on every pointer you receive from the method. If you don't call the method, you will leak memory. If you call the method more than once, memory will be corrupted. - + method exactly once on every pointer you receive from the method. If you don't call the method, you will leak memory. If you call the method more than once, memory will be corrupted. + ]]> @@ -642,14 +642,14 @@ Packs the current instance into a structure, specifying the delegate to be invoked when the asynchronous I/O operation is complete. An unmanaged pointer to a structure. - structure is fixed in physical memory until is called. - + structure is fixed in physical memory until is called. + > [!IMPORTANT] -> The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. - +> The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. + ]]> The current has already been packed. @@ -720,16 +720,16 @@ Packs the current instance into a structure, specifying a delegate that is invoked when the asynchronous I/O operation is complete and a managed object that serves as a buffer. An unmanaged pointer to a structure. - structure is fixed in physical memory until is called. - - The buffer or buffers specified in `userData` must be the same as those passed to the unmanaged operating system function that performs the asynchronous I/O. - + structure is fixed in physical memory until is called. + + The buffer or buffers specified in `userData` must be the same as those passed to the unmanaged operating system function that performs the asynchronous I/O. + > [!NOTE] -> The runtime pins the buffer or buffers specified in `userData` for the duration of the I/O operation. If the application domain is unloaded, the runtime keeps the memory pinned until the I/O operation completes. - +> The runtime pins the buffer or buffers specified in `userData` for the duration of the I/O operation. If the application domain is unloaded, the runtime keeps the memory pinned until the I/O operation completes. + ]]> The current has already been packed. @@ -794,11 +794,11 @@ Unpacks the specified unmanaged structure into a managed object. An object containing the information unpacked from the native structure. - structure is not freed from physical memory until you call the method. - + structure is not freed from physical memory until you call the method. + ]]> @@ -888,16 +888,16 @@ Packs the current instance into a structure specifying the delegate to invoke when the asynchronous I/O operation is complete. Does not propagate the calling stack. An unmanaged pointer to a structure. - structure is fixed in physical memory until is called. - - The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. - + structure is fixed in physical memory until is called. + + The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. + > [!CAUTION] -> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. The method does not propagate the calling stack. Malicious code might be able to exploit this to avoid permission checks. - +> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. The method does not propagate the calling stack. Malicious code might be able to exploit this to avoid permission checks. + ]]> The current has already been packed. @@ -968,18 +968,18 @@ Packs the current instance into a structure, specifying the delegate to invoke when the asynchronous I/O operation is complete and the managed object that serves as a buffer. Does not propagate the calling stack. An unmanaged pointer to a structure. - structure is fixed in physical memory until is called. - - The buffer or buffers specified in `userData` must be the same as those passed to the unmanaged operating system function that performs the asynchronous I/O. - - The runtime pins the buffer or buffers specified in`userData` for the duration of the I/O operation. If the application domain is unloaded, the runtime keeps the memory pinned until the I/O operation completes. - + structure is fixed in physical memory until is called. + + The buffer or buffers specified in `userData` must be the same as those passed to the unmanaged operating system function that performs the asynchronous I/O. + + The runtime pins the buffer or buffers specified in`userData` for the duration of the I/O operation. If the application domain is unloaded, the runtime keeps the memory pinned until the I/O operation completes. + > [!CAUTION] -> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. The method does not propagate the calling stack. Malicious code might be able to exploit this to avoid permission checks. - +> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. The method does not propagate the calling stack. Malicious code might be able to exploit this to avoid permission checks. + ]]> The caller does not have the required permission. diff --git a/xml/System.Threading/ReaderWriterLock.xml b/xml/System.Threading/ReaderWriterLock.xml index 9925589c711..c35adee1d05 100644 --- a/xml/System.Threading/ReaderWriterLock.xml +++ b/xml/System.Threading/ReaderWriterLock.xml @@ -576,7 +576,7 @@ ## Examples - The following code example shows how to use the method and the property to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. + The following code example shows how to use the method and the property to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. This code is part of a larger example provided for the class. @@ -1396,7 +1396,7 @@ ## Examples - The following code example shows how to use the property and the method to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. + The following code example shows how to use the property and the method to determine whether another thread acquired the writer lock on the protected resource since the current thread last held the writer lock. This code is part of a larger example provided for the class. diff --git a/xml/System.Threading/ReaderWriterLockSlim.xml b/xml/System.Threading/ReaderWriterLockSlim.xml index 26269cd29ea..5a2253f9acf 100644 --- a/xml/System.Threading/ReaderWriterLockSlim.xml +++ b/xml/System.Threading/ReaderWriterLockSlim.xml @@ -112,7 +112,7 @@ that is initialized with this constructor does not allow recursion. That is, the property returns . + A that is initialized with this constructor does not allow recursion. That is, the property returns . For more information about recursion policy and its effects, see the enumeration and the class. @@ -277,7 +277,7 @@ ## Examples - The following example shows how to use the property to generate an event log entry if the number of threads in read mode exceeds a threshold. + The following example shows how to use the property to generate an event log entry if the number of threads in read mode exceeds a threshold. :::code language="csharp" source="~/snippets/csharp/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.vb" id="Snippet1"::: @@ -858,7 +858,7 @@ ## Examples - The following example shows how to use the property to generate an assert if the current thread has entered read mode unexpectedly. + The following example shows how to use the property to generate an assert if the current thread has entered read mode unexpectedly. :::code language="csharp" source="~/snippets/csharp/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.vb" id="Snippet1"::: @@ -919,7 +919,7 @@ ## Examples - The following example shows how to use the property to generate an assert if the current thread has entered upgradeable mode unexpectedly. + The following example shows how to use the property to generate an assert if the current thread has entered upgradeable mode unexpectedly. :::code language="csharp" source="~/snippets/csharp/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.vb" id="Snippet1"::: @@ -980,7 +980,7 @@ ## Examples - The following example shows how to use the property to generate an assert if the current thread has entered write mode unexpectedly. + The following example shows how to use the property to generate an assert if the current thread has entered write mode unexpectedly. :::code language="csharp" source="~/snippets/csharp/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.vb" id="Snippet1"::: @@ -1747,7 +1747,7 @@ ## Examples - The following example shows how to use the property to generate an event log entry if the number of threads that are blocked, waiting to enter read mode, exceeds a threshold. + The following example shows how to use the property to generate an event log entry if the number of threads that are blocked, waiting to enter read mode, exceeds a threshold. :::code language="csharp" source="~/snippets/csharp/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.vb" id="Snippet1"::: @@ -1813,7 +1813,7 @@ ## Examples - The following example shows how to use the property to generate an event log entry if the number of threads that are blocked, waiting to enter upgradeable mode, exceeds a threshold. + The following example shows how to use the property to generate an event log entry if the number of threads that are blocked, waiting to enter upgradeable mode, exceeds a threshold. :::code language="csharp" source="~/snippets/csharp/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.vb" id="Snippet1"::: @@ -1879,7 +1879,7 @@ ## Examples - The following example shows how to use the property to generate an event log entry if the number of threads that are blocked, waiting to enter write mode, exceeds a threshold. + The following example shows how to use the property to generate an event log entry if the number of threads that are blocked, waiting to enter write mode, exceeds a threshold. :::code language="csharp" source="~/snippets/csharp/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ReaderWriterLockSlim/CurrentReadCount/source.vb" id="Snippet1"::: diff --git a/xml/System.Threading/SemaphoreFullException.xml b/xml/System.Threading/SemaphoreFullException.xml index 09387e11ad4..0ca48b24608 100644 --- a/xml/System.Threading/SemaphoreFullException.xml +++ b/xml/System.Threading/SemaphoreFullException.xml @@ -158,7 +158,7 @@ property of the new instance to a system-supplied message that describes the error, such as "Adding the given count to the semaphore would cause it to exceed its maximum count." This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "Adding the given count to the semaphore would cause it to exceed its maximum count." This message takes into account the current system culture. The following table shows the initial property values for an instance of the class. @@ -351,7 +351,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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. ]]> diff --git a/xml/System.Threading/SemaphoreSlim.xml b/xml/System.Threading/SemaphoreSlim.xml index 913a42626fa..4413088c053 100644 --- a/xml/System.Threading/SemaphoreSlim.xml +++ b/xml/System.Threading/SemaphoreSlim.xml @@ -85,10 +85,10 @@ SemaphoreSlim.Wait() SemaphoreSlim.Release() ``` - When all threads have released the semaphore, the count is at the maximum value specified when the semaphore was created. The semaphore's count is available from the property. + When all threads have released the semaphore, the count is at the maximum value specified when the semaphore was created. The semaphore's count is available from the property. > [!IMPORTANT] -> The class doesn't enforce thread or task identity on calls to the , , and methods. In addition, if the constructor is used to instantiate the object, the property can increase beyond the value set by the constructor. It is the programmer's responsibility to ensure that calls to or methods are appropriately paired with calls to methods. +> The class doesn't enforce thread or task identity on calls to the , , and methods. In addition, if the constructor is used to instantiate the object, the property can increase beyond the value set by the constructor. It is the programmer's responsibility to ensure that calls to or methods are appropriately paired with calls to methods. ## Examples The following example creates a semaphore with a maximum count of three threads and an initial count of zero threads. The example starts five tasks, all of which block waiting for the semaphore. The main thread calls the overload to increase the semaphore count to its maximum, which allows three tasks to enter the semaphore. Each time the semaphore is released, the previous semaphore count is displayed. Console messages track semaphore use. The simulated work interval is increased slightly for each thread to make the output easier to read. @@ -156,7 +156,7 @@ SemaphoreSlim.Release() object instantiated by calling this constructor doesn't throw a exception if a call to the method increases the value of the property beyond `initialCount`. This occurs if there are more calls to methods than there are to or methods. To set the maximum number of concurrent requests to enter the semaphore that can be granted, call the constructor. + The `initialCount` parameter defines the number of concurrent requests to enter the semaphore that can be granted. However, it doesn't define the maximum number of requests that can be granted concurrently. A object instantiated by calling this constructor doesn't throw a exception if a call to the method increases the value of the property beyond `initialCount`. This occurs if there are more calls to methods than there are to or methods. To set the maximum number of concurrent requests to enter the semaphore that can be granted, call the constructor. ]]> @@ -306,7 +306,7 @@ SemaphoreSlim.Release() property is set by the call to the class constructor. It is decremented by each call to the or method, and incremented by each call to the method. + The initial value of the property is set by the call to the class constructor. It is decremented by each call to the or method, and incremented by each call to the method. ]]> @@ -491,7 +491,7 @@ SemaphoreSlim.Release() method increments the property by one. If the value of the property is zero before this method is called, the method also allows one thread or task blocked by a call to the or method to enter the semaphore. + A call to the method increments the property by one. If the value of the property is zero before this method is called, the method also allows one thread or task blocked by a call to the or method to enter the semaphore. ]]> @@ -547,7 +547,7 @@ SemaphoreSlim.Release() method increments the property by `releaseCount`. If the value of the property is zero before this method is called, the method also allows `releaseCount` threads or tasks blocked by a call to the or method to enter the semaphore. + A call to the method increments the property by `releaseCount`. If the value of the property is zero before this method is called, the method also allows `releaseCount` threads or tasks blocked by a call to the or method to enter the semaphore. ]]> @@ -618,7 +618,7 @@ SemaphoreSlim.Release() property by one. + If a thread or task is able to enter the semaphore, it decrements the property by one. ]]> @@ -684,12 +684,12 @@ If the timeout is set to -1 milliseconds, the method waits indefinitely. If the timeout is set to zero milliseconds, the method doesn't block. It tests the state of the wait handle and returns immediately. -If a thread or task is able to enter the semaphore, it decrements the property by one. +If a thread or task is able to enter the semaphore, it decrements the property by one. If a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: - The thread or task doesn't enter the semaphore. -- The property isn't decremented. +- The property isn't decremented. ]]> @@ -751,9 +751,9 @@ If a thread or task is blocked when calling property by one. + If a thread or task is able to enter the semaphore, it decrements the property by one. - If `cancellationToken` is cancelled, the thread or task doesn't enter the semaphore, and the property isn't decremented. Instead, the method throws an exception. + If `cancellationToken` is cancelled, the thread or task doesn't enter the semaphore, and the property isn't decremented. Instead, the method throws an exception. ]]> @@ -826,12 +826,12 @@ If the timeout is set to -1 milliseconds, the method waits indefinitely. If the timeout is set to zero milliseconds, the method doesn't block. It tests the state of the wait handle and returns immediately. -If a thread or task is able to enter the semaphore, it decrements the property by one. +If a thread or task is able to enter the semaphore, it decrements the property by one. If a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: - The thread or task doesn't enter the semaphore. -- The property isn't decremented. +- The property isn't decremented. ]]>
@@ -905,12 +905,12 @@ If the timeout is set to -1 milliseconds, the method waits indefinitely. If the timeout is set to zero milliseconds, the method doesn't block. It tests the state of the wait handle and returns immediately. -If a thread or task is able to enter the semaphore, it decrements the property by one. +If a thread or task is able to enter the semaphore, it decrements the property by one. If `cancellationToken` is cancelled, or if a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: - The thread or task doesn't enter the semaphore. -- The property isn't decremented. +- The property isn't decremented. If `cancellationToken` is cancelled, the method throws an exception. @@ -988,12 +988,12 @@ If the timeout is set to -1 milliseconds, the method waits indefinitely. If the timeout is set to zero milliseconds, the method doesn't block. It tests the state of the wait handle and returns immediately. -If a thread or task is able to enter the semaphore, it decrements the property by one. +If a thread or task is able to enter the semaphore, it decrements the property by one. If `cancellationToken` is cancelled, or if a thread or task is blocked when calling and the timeout interval specified by `millisecondsTimeout` expires: - The thread or task doesn't enter the semaphore. -- The property isn't decremented. +- The property isn't decremented. If `cancellationToken` is cancelled, the method throws an exception. diff --git a/xml/System.Threading/SynchronizationLockException.xml b/xml/System.Threading/SynchronizationLockException.xml index cb4b6d25807..5a6f08499a8 100644 --- a/xml/System.Threading/SynchronizationLockException.xml +++ b/xml/System.Threading/SynchronizationLockException.xml @@ -320,7 +320,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Threading/Thread.xml b/xml/System.Threading/Thread.xml index 610f6198209..a0e90c17016 100644 --- a/xml/System.Threading/Thread.xml +++ b/xml/System.Threading/Thread.xml @@ -502,7 +502,7 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ If `Abort` is called on a thread that has not been started, the thread will abort when is called. If `Abort` is called on a thread that is blocked or is sleeping, the thread is interrupted and then aborted. - If `Abort` is called on a thread that has been suspended, a is thrown in the thread that called , and is added to the property of the thread being aborted. A is not thrown in the suspended thread until is called. + If `Abort` is called on a thread that has been suspended, a is thrown in the thread that called , and is added to the property of the thread being aborted. A is not thrown in the suspended thread until is called. If `Abort` is called on a managed thread while it is executing unmanaged code, a `ThreadAbortException` is not thrown until the thread returns to managed code. @@ -595,7 +595,7 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ If `Abort` is called on a thread that has not been started, the thread will abort when is called. If `Abort` is called on a thread that is blocked or is sleeping, the thread is interrupted and then aborted. - If `Abort` is called on a thread that has been suspended, a is thrown in the thread that called , and is added to the property of the thread being aborted. A is not thrown in the suspended thread until is called. + If `Abort` is called on a thread that has been suspended, a is thrown in the thread that called , and is added to the property of the thread being aborted. A is not thrown in the suspended thread until is called. If `Abort` is called on a managed thread while it is executing unmanaged code, a `ThreadAbortException` is not thrown until the thread returns to managed code. @@ -849,7 +849,7 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ property is obsolete.** The non-obsolete alternatives are the method to retrieve the apartment state and the method to set the apartment state. +**The property is obsolete.** The non-obsolete alternatives are the method to retrieve the apartment state and the method to set the apartment state. > [!IMPORTANT] > New threads are initialized as if their apartment state has not been set before they're started. The main application thread is initialized to by default. @@ -1096,13 +1096,13 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR object that is returned by this property, together with its associated objects, determine the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons. See the class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads and application domains. See the property to learn how a thread's default culture is determined, and how users set culture information for their computers. + The object that is returned by this property, together with its associated objects, determine the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons. See the class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads and application domains. See the property to learn how a thread's default culture is determined, and how users set culture information for their computers. > [!IMPORTANT] > The property doesn't work reliably when used with any thread other than the current thread. In .NET Framework, reading the property is reliable, although setting it for a thread other than the current thread is not. On .NET Core, an is thrown if a thread attempts to read or write the property on a different thread. > We recommend that you use the property to retrieve and set the current culture. - Beginning with the .NET Framework 4, you can set the property to a neutral culture. This is because the behavior of the class has changed: When it represents a neutral culture, its property values (in particular, the , , , , and properties) now reflect the specific culture that is associated with the neutral culture. In earlier versions of the .NET Framework, the property threw a exception when a neutral culture was assigned. + Beginning with the .NET Framework 4, you can set the property to a neutral culture. This is because the behavior of the class has changed: When it represents a neutral culture, its property values (in particular, the , , , , and properties) now reflect the specific culture that is associated with the neutral culture. In earlier versions of the .NET Framework, the property threw a exception when a neutral culture was assigned. ## Examples The following example shows the threading statement that allows the user interface of a Windows Forms application to display in the culture that is set in Control Panel. Additional code is needed. @@ -1248,7 +1248,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR property to display information about the thread on which it is running. + The following example creates a task that in turn creates 20 child tasks. The application itself, as well as each task, calls the `ShowThreadInformation` method, which uses the property to display information about the thread on which it is running. :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/CurrentThread/currentthread2.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/CurrentThread/currentthread2.fs" id="Snippet1"::: @@ -1315,13 +1315,13 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads and application domains. See the property to learn how a thread's default UI culture is determined. + The UI culture specifies the resources an application needs to support user input and output, and by default is the same as the operating system culture. See the class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads and application domains. See the property to learn how a thread's default UI culture is determined. > [!IMPORTANT] > The property doesn't work reliably when used with any thread other than the current thread. In .NET Framework, reading the property is reliable, although setting it for a thread other than the current thread is not. On .NET Core, an is thrown if a thread attempts to read or write the property on a different thread. > We recommend that you use the property to retrieve and set the current culture. - The returned by this property can be a neutral culture. Neutral cultures should not be used with formatting methods such as , , and . Use the method to get a specific culture, or use the property. + The returned by this property can be a neutral culture. Neutral cultures should not be used with formatting methods such as , , and . Use the method to get a specific culture, or use the property. ## Examples The following example determines whether the language of the current thread's UI culture is French. If it is not, it sets the UI culture of the current thread to English (United States). @@ -1801,7 +1801,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR method and the method, replaces the property. + This method, along with the method and the method, replaces the property. ## Examples The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. @@ -2186,7 +2186,7 @@ The value is not guaranteed to be a zero-based processor number. property if you need a unique identifier for a managed thread. + The hash code is not guaranteed to be unique. Use the property if you need a unique identifier for a managed thread. ]]> @@ -2446,13 +2446,13 @@ The value is not guaranteed to be a zero-based processor number. ## Remarks A thread is either a background thread or a foreground thread. Background threads are identical to foreground threads, except that background threads do not prevent a process from terminating. Once all foreground threads belonging to a process have terminated, the common language runtime ends the process. Any remaining background threads are stopped and do not complete. - By default, the following threads execute in the foreground (that is, their property returns `false`): + By default, the following threads execute in the foreground (that is, their property returns `false`): - The primary thread (or main application thread). - All threads created by calling a class constructor. - By default, the following threads execute in the background (that is, their property returns `true`): + By default, the following threads execute in the background (that is, their property returns `true`): - Thread pool threads, which are a pool of worker threads maintained by the runtime. You can configure the thread pool and schedule work on thread pool threads by using the class. @@ -2823,9 +2823,9 @@ The value is not guaranteed to be a zero-based processor number. property value serves to uniquely identify that thread within its process. + A thread's property value serves to uniquely identify that thread within its process. - The value of the property does not vary over time, even if unmanaged code that hosts the common language runtime implements the thread as a fiber. + The value of the property does not vary over time, even if unmanaged code that hosts the common language runtime implements the thread as a fiber. ]]> @@ -2941,9 +2941,9 @@ The value is not guaranteed to be a zero-based processor number. property is `null`, you can determine whether a name has already been explicitly assigned to the thread by comparing it with `null`. + In .NET 5 and earlier versions, this property is write-once. In these versions, because the default value of a thread's property is `null`, you can determine whether a name has already been explicitly assigned to the thread by comparing it with `null`. - The string assigned to the property can include any Unicode character. + The string assigned to the property can include any Unicode character. ]]> @@ -3235,7 +3235,7 @@ The value is not guaranteed to be a zero-based processor number. > [!NOTE] > The main application thread is initialized to by default. The only way to set the apartment state of the main application thread to is to apply the attribute to the entry point method. - The method, along with the method and the method, replaces the property. + The method, along with the method and the method, replaces the property. ## Examples The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. @@ -4132,7 +4132,7 @@ When you call the `Suspend` method on a thread, the system notes that a thread s property provides more specific information than the property. + The property provides more specific information than the property. > [!IMPORTANT] > Thread state is only of interest in debugging scenarios. Your code should never use thread state to synchronize the activities of threads. @@ -4206,7 +4206,7 @@ When you call the `Suspend` method on a thread, the system notes that a thread s > [!NOTE] > The main application thread is initialized to by default. The only way to set the apartment state of the main application thread to is to apply the attribute to the entry point method. - The method, along with the method and the method, replaces the property. + The method, along with the method and the method, replaces the property. ## Examples The following code example demonstrates the , , and methods. The code example creates a thread. Before the thread is started, displays the initial state and changes the state to . The method then returns `false` when attempting to change the state to because the apartment state is already set. If the same operation had been attempted with , would have been thrown. diff --git a/xml/System.Threading/ThreadAbortException.xml b/xml/System.Threading/ThreadAbortException.xml index 5ae622d9514..b64b03857aa 100644 --- a/xml/System.Threading/ThreadAbortException.xml +++ b/xml/System.Threading/ThreadAbortException.xml @@ -75,11 +75,11 @@ uses `HRESULT COR_E_THREADABORTED`, which has the value `0x80131530`. > [!NOTE] -> The value of the inherited property is always `null`. +> The value of the inherited property is always `null`. ## Examples The following example demonstrates aborting a thread. The thread that receives the `ThreadAbortException` uses the method to cancel the abort request and continue executing. - + :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadAbortException/Overview/threadabex.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ThreadAbortException/Overview/threadabex.vb" id="Snippet1"::: diff --git a/xml/System.Threading/ThreadInterruptedException.xml b/xml/System.Threading/ThreadInterruptedException.xml index 67c241d8e77..391942a2ea5 100644 --- a/xml/System.Threading/ThreadInterruptedException.xml +++ b/xml/System.Threading/ThreadInterruptedException.xml @@ -74,7 +74,7 @@ ## Examples The following code example shows the behavior of a running thread when it is interrupted and subsequently gets blocked. - + :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/Interrupt/source.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/Thread/Interrupt/source.vb" id="Snippet1"::: @@ -314,7 +314,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Threading/ThreadLocal`1.xml b/xml/System.Threading/ThreadLocal`1.xml index 11f95dd4716..9a19d8f5d8c 100644 --- a/xml/System.Threading/ThreadLocal`1.xml +++ b/xml/System.Threading/ThreadLocal`1.xml @@ -80,14 +80,14 @@ Specifies the type of data stored per-thread. Provides thread-local storage of data. - : - + : + :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadLocalT/Overview/threadlocal.cs" id="Snippet01"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading/ThreadLocalT/Overview/threadlocal.vb" id="Snippet01"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Threading/ThreadLocalT/Overview/threadlocal.vb" id="Snippet01"::: + ]]> With the exception of , all public and protected members of are thread-safe and may be used concurrently from multiple threads. The value returned for the and properties is specific for the thread on which the property is accessed. @@ -150,13 +150,13 @@ Initializes the instance. - is accessed for the first time. - - This constructor is equivalent to calling the constructor with a value of `false` for the `trackAllValues` argument. - + is accessed for the first time. + + This constructor is equivalent to calling the constructor with a value of `false` for the `trackAllValues` argument. + ]]> @@ -205,11 +205,11 @@ to track all values set on the instance and expose them through the property; otherwise. When set to , a value stored from a given thread will be available through even after that thread has exited. Initializes the instance and specifies whether all values are accessible from any thread. - property to retrieve all values throws an exception. - + property to retrieve all values throws an exception. + ]]> @@ -304,11 +304,11 @@ to track all values set on the instance and expose them through the property; otherwise. When set to , a value stored from a given thread will be available through even after that thread has exited. Initializes the instance with the specified function and a flag that indicates whether all values are accessible from any thread. - property to retrieve all values throws an exception. - + property to retrieve all values throws an exception. + ]]> @@ -369,16 +369,16 @@ Releases all resources used by the current instance of the class. - . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. - - For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). - + . The `Dispose` method leaves the in an unusable state. After calling `Dispose`, you must release all references to the so the garbage collector can reclaim the memory that the was occupying. + + For more information, see [Cleaning Up Unmanaged Resources](/dotnet/standard/garbage-collection/unmanaged) and [Implementing a Dispose Method](/dotnet/standard/garbage-collection/implementing-dispose). + > [!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. - +> 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. + ]]> @@ -429,11 +429,11 @@ A Boolean value that indicates whether this method is being called due to a call to . Releases the resources used by this instance. - , this method is not thread-safe. - + , this method is not thread-safe. + ]]> @@ -574,11 +574,11 @@ Creates and returns a string representation of this instance for the current thread. The result of calling on the . - directly. - + directly. + ]]> The instance has been disposed. @@ -636,9 +636,9 @@ Gets or sets the value of this instance for the current thread. Returns an instance of the object that this ThreadLocal is responsible for initializing. - will initialize it. If a value factory was supplied during the construction, initialization will happen by invoking the function to retrieve the initial value for . Otherwise, the default value of `T` will be used. diff --git a/xml/System.Threading/ThreadPool.xml b/xml/System.Threading/ThreadPool.xml index 5dac9ac397a..31f599ebbb0 100644 --- a/xml/System.Threading/ThreadPool.xml +++ b/xml/System.Threading/ThreadPool.xml @@ -647,7 +647,7 @@ You can place data required by the queued method in the instance fields of the c > [!NOTE] > Visual Basic users can omit the constructor, and simply use the `AddressOf` operator when passing the callback method to . Visual Basic automatically calls the correct delegate constructor. -The property value is propagated to worker threads queued using the method. +The property value is propagated to worker threads queued using the method. ]]> @@ -1285,7 +1285,7 @@ The following example uses the property. In addition, you cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the corresponding minimum number of worker threads or I/O completion threads. To determine the minimum thread pool size, call the method. + You cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the number of processors on the computer. To determine how many processors are present, retrieve the value of the property. In addition, you cannot set the maximum number of worker threads or I/O completion threads to a number smaller than the corresponding minimum number of worker threads or I/O completion threads. To determine the minimum thread pool size, call the method. If the common language runtime is hosted, for example by Internet Information Services (IIS) or SQL Server, the host can limit or prevent changes to the thread pool size. diff --git a/xml/System.Threading/ThreadPriority.xml b/xml/System.Threading/ThreadPriority.xml index 608d2c635ad..e01f172337b 100644 --- a/xml/System.Threading/ThreadPriority.xml +++ b/xml/System.Threading/ThreadPriority.xml @@ -56,25 +56,25 @@ Specifies the scheduling priority of a . - defines the set of all possible values for a thread priority. Thread priorities specify the relative priority of one thread versus another. - - Every thread has an assigned priority. Threads created within the runtime are initially assigned the `Normal` priority, while threads created outside the runtime retain their previous priority when they enter the runtime. You can get and set the priority of a thread by accessing its property. - - Threads are scheduled for execution based on their priority. The scheduling algorithm used to determine the order of thread execution varies with each operating system. The operating system can also adjust the thread priority dynamically as the user interface's focus is moved between the foreground and the background. - - The priority of a thread does not affect the thread's state; the state of the thread must be before the operating system can schedule it. - - - -## Examples - The following code example shows the result of changing the priority of a thread. Three threads are created, the priority of one thread is set to BelowNormal, and the priority of a second is set to AboveNormal. Each thread increments a variable in a `while` loop and runs for a set time. - + defines the set of all possible values for a thread priority. Thread priorities specify the relative priority of one thread versus another. + + Every thread has an assigned priority. Threads created within the runtime are initially assigned the `Normal` priority, while threads created outside the runtime retain their previous priority when they enter the runtime. You can get and set the priority of a thread by accessing its property. + + Threads are scheduled for execution based on their priority. The scheduling algorithm used to determine the order of thread execution varies with each operating system. The operating system can also adjust the thread priority dynamically as the user interface's focus is moved between the foreground and the background. + + The priority of a thread does not affect the thread's state; the state of the thread must be before the operating system can schedule it. + + + +## Examples + The following code example shows the result of changing the priority of a thread. Three threads are created, the priority of one thread is set to BelowNormal, and the priority of a second is set to AboveNormal. Each thread increments a variable in a `while` loop and runs for a set time. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/Priority/Example1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading/Thread/Priority/Example1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/System.Threading/Thread/Priority/Example1.vb" id="Snippet1"::: + ]]> diff --git a/xml/System.Threading/ThreadStartException.xml b/xml/System.Threading/ThreadStartException.xml index e789ef138b5..aead3924e82 100644 --- a/xml/System.Threading/ThreadStartException.xml +++ b/xml/System.Threading/ThreadStartException.xml @@ -59,11 +59,11 @@ The exception that is thrown when a failure occurs in a managed thread after the underlying operating system thread has been started, but before the thread is ready to execute user code. - property provides information about the reason for the failure. - + property provides information about the reason for the failure. + ]]> diff --git a/xml/System.Threading/ThreadState.xml b/xml/System.Threading/ThreadState.xml index 564f92d93c2..eeeaea076c0 100644 --- a/xml/System.Threading/ThreadState.xml +++ b/xml/System.Threading/ThreadState.xml @@ -61,40 +61,40 @@ Specifies the execution states of a . - state, while external, or unmanaged, threads that come into the runtime are already in the state. A thread is transitioned from the state into the state by calling . Once a thread leaves the state as the result of a call to , it can never return to the state. + , and another thread calls on the blocked thread, the blocked thread will be in both the and states at the same time. In this case, as soon as the thread returns from the call to or is interrupted, it will receive the to begin aborting. Not all combinations of `ThreadState` values are valid; for example, a thread cannot be in both the and states. +## Remarks + The `ThreadState` enumeration defines a set of all possible execution states for threads. It's of interest only in a few debugging scenarios. Your code should never use the thread state to synchronize the activities of threads. + + Once a thread is created, it's in at least one of the states until it terminates. Threads created within the common language runtime are initially in the state, while external, or unmanaged, threads that come into the runtime are already in the state. A thread is transitioned from the state into the state by calling . Once a thread leaves the state as the result of a call to , it can never return to the state. + + A thread can be in more than one state at a given time. For example, if a thread is blocked on a call to , and another thread calls on the blocked thread, the blocked thread will be in both the and states at the same time. In this case, as soon as the thread returns from the call to or is interrupted, it will receive the to begin aborting. Not all combinations of `ThreadState` values are valid; for example, a thread cannot be in both the and states. + + A thread can never leave the state. - A thread can never leave the state. - > [!IMPORTANT] -> There are two thread state enumerations: and . - - The following table shows the actions that cause a change of state. - -|Action|ThreadState| -|------------|-----------------| -|A thread is created within the common language runtime.|| -|Another thread calls the method on the new thread, and the call returns.

The method does not return until the new thread has started running. There is no way to know at what point the new thread will start running, during the call to .|| -|The thread calls || -|The thread calls on another object.|| -|The thread calls on another thread.|| -|Another thread calls || -|Another thread calls || -|The thread responds to a request.|| -|Another thread calls || -|Another thread calls || -|The thread responds to an request.|| -|A thread is terminated.|| - - In addition to the states noted above, there is also the state, which indicates whether the thread is running in the background or foreground. For more information, see [Foreground and Background Threads](/dotnet/standard/threading/foreground-and-background-threads). - - The property of a thread provides the current state of a thread. Applications must use a bit mask to determine whether a thread is running. Since the value for is zero (0), test whether a thread is running by the following code: +> There are two thread state enumerations: and . + + The following table shows the actions that cause a change of state. + +|Action|ThreadState| +|------------|-----------------| +|A thread is created within the common language runtime.|| +|Another thread calls the method on the new thread, and the call returns.

The method does not return until the new thread has started running. There is no way to know at what point the new thread will start running, during the call to .|| +|The thread calls || +|The thread calls on another object.|| +|The thread calls on another thread.|| +|Another thread calls || +|Another thread calls || +|The thread responds to a request.|| +|Another thread calls || +|Another thread calls || +|The thread responds to an request.|| +|A thread is terminated.|| + + In addition to the states noted above, there is also the state, which indicates whether the thread is running in the background or foreground. For more information, see [Foreground and Background Threads](/dotnet/standard/threading/foreground-and-background-threads). + + The property of a thread provides the current state of a thread. Applications must use a bit mask to determine whether a thread is running. Since the value for is zero (0), test whether a thread is running by the following code: ```csharp (myThread.ThreadState & (ThreadState.Stopped | ThreadState.Unstarted)) == 0 @@ -103,7 +103,7 @@ ```vb (myThread.ThreadState And (ThreadState.Stopped Or ThreadState.Unstarted)) = 0 ``` - + ]]>
diff --git a/xml/System.Threading/ThreadStateException.xml b/xml/System.Threading/ThreadStateException.xml index 1a5a3ba2146..6157fc0c15b 100644 --- a/xml/System.Threading/ThreadStateException.xml +++ b/xml/System.Threading/ThreadStateException.xml @@ -81,7 +81,7 @@ ## Examples The following example demonstrates an error that causes the system to throw a `ThreadStateException`. - + :::code language="csharp" source="~/snippets/csharp/System.Threading/ThreadStateException/Overview/threadstex.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading/ThreadStateException/Overview/threadstex.vb" id="Snippet1"::: @@ -335,7 +335,7 @@ In main. Attempting to restart myThread. 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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 . diff --git a/xml/System.Threading/WaitHandle.xml b/xml/System.Threading/WaitHandle.xml index 0f19bcb82b6..e703a7172f9 100644 --- a/xml/System.Threading/WaitHandle.xml +++ b/xml/System.Threading/WaitHandle.xml @@ -103,7 +103,7 @@ > [!IMPORTANT] > This type implements the interface. When you have finished using the type or a type derived from it, 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. - implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. + implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. @@ -467,9 +467,9 @@ Application code does not call this method; it is automatically invoked during g property does not close the previous handle. This can result in a leaked handle. + Assigning a new value to the property does not close the previous handle. This can result in a leaked handle. - Do not use this property in the .NET Framework version 2.0 or later; use the property instead. Setting this property to a valid handle also sets the property, but setting it to can result in a leaked handle. + Do not use this property in the .NET Framework version 2.0 or later; use the property instead. Setting this property to a valid handle also sets the property, but setting it to can result in a leaked handle. ]]> @@ -521,7 +521,7 @@ Application code does not call this method; it is automatically invoked during g property. + Used internally to initialize the property. ]]> @@ -590,9 +590,9 @@ Application code does not call this method; it is automatically invoked during g property, the previous handle will be closed when the previous object is collected. Do not manually close the handle, because this results in an when the attempts to close the handle. + When you assign a new value to the property, the previous handle will be closed when the previous object is collected. Do not manually close the handle, because this results in an when the attempts to close the handle. - implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native handle operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. + implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native handle operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. ]]> diff --git a/xml/System.Threading/WaitHandleCannotBeOpenedException.xml b/xml/System.Threading/WaitHandleCannotBeOpenedException.xml index c317d3d6812..b282e55faa9 100644 --- a/xml/System.Threading/WaitHandleCannotBeOpenedException.xml +++ b/xml/System.Threading/WaitHandleCannotBeOpenedException.xml @@ -131,7 +131,7 @@ property of the new instance to a system-supplied message that describes the error, such as "No handle of the given name exists." This message takes into account the current system culture. + This constructor initializes the property of the new instance to a system-supplied message that describes the error, such as "No handle of the given name exists." This message takes into account the current system culture. The following table shows the initial property values for an instance of . @@ -313,7 +313,7 @@ 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. + An exception that is thrown as a direct result of a previous exception should include a reference to the previous exception in the 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. ]]> diff --git a/xml/System.Threading/WaitHandleExtensions.xml b/xml/System.Threading/WaitHandleExtensions.xml index d56d7b1b18e..dde7a2aea05 100644 --- a/xml/System.Threading/WaitHandleExtensions.xml +++ b/xml/System.Threading/WaitHandleExtensions.xml @@ -64,11 +64,11 @@ Provides convenience methods to for working with a safe handle for a wait handle. - class includes two extension methods that allow you to create a safe handle for a wait handle and to retrieve the native operating system handle from a safe handle. - + class includes two extension methods that allow you to create a safe handle for a wait handle and to retrieve the native operating system handle from a safe handle. + ]]> @@ -125,11 +125,11 @@ Gets the safe handle for a native operating system wait handle. The safe wait handle that wraps the native operating system wait handle. - is an extension method that is equivalent to retrieving the value of the property. - + is an extension method that is equivalent to retrieving the value of the property. + ]]> @@ -197,11 +197,11 @@ The safe handle to wrap the operating system handle. Sets a safe handle for a native operating system wait handle. - is an extension method that is equivalent to assigning a value to the property. - + is an extension method that is equivalent to assigning a value to the property. + ]]> diff --git a/xml/System.Timers/ElapsedEventArgs.xml b/xml/System.Timers/ElapsedEventArgs.xml index 0c256c388a5..9a384042467 100644 --- a/xml/System.Timers/ElapsedEventArgs.xml +++ b/xml/System.Timers/ElapsedEventArgs.xml @@ -53,8 +53,8 @@ object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. - + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventArgs/Overview/timer1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/timer1.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Timers/ElapsedEventArgs/Overview/timer1.vb" id="Snippet1"::: @@ -138,12 +138,12 @@ event is raised on a thread, so the event-handling method might run on one thread at the same time that a call to the method runs on another thread. This might result in the event being raised after the method is called. This race condition cannot be prevented simply by comparing the property with the time when the method is called, because the event-handling method might already be executing when the method is called, or might begin executing between the moment when the method is called and the moment when the stop time is saved. If it is critical to prevent the thread that calls the method from proceeding while the event-handling method is still executing, use a more robust synchronization mechanism such as the class or the method. Code that uses the method can be found in the example for the method. + The event is raised on a thread, so the event-handling method might run on one thread at the same time that a call to the method runs on another thread. This might result in the event being raised after the method is called. This race condition cannot be prevented simply by comparing the property with the time when the method is called, because the event-handling method might already be executing when the method is called, or might begin executing between the moment when the method is called and the moment when the stop time is saved. If it is critical to prevent the thread that calls the method from proceeding while the event-handling method is still executing, use a more robust synchronization mechanism such as the class or the method. Code that uses the method can be found in the example for the method. ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventArgs/Overview/timer1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/timer1.fs" id="Snippet1"::: diff --git a/xml/System.Timers/ElapsedEventHandler.xml b/xml/System.Timers/ElapsedEventHandler.xml index f5d51176b0b..22f1c403793 100644 --- a/xml/System.Timers/ElapsedEventHandler.xml +++ b/xml/System.Timers/ElapsedEventHandler.xml @@ -70,8 +70,8 @@ ## Examples - The following code example sets up an event handler for the event, creates a timer, and starts the timer. The event handler has the same signature as the delegate. The event handler displays the property each time it is raised. - + The following code example sets up an event handler for the event, creates a timer, and starts the timer. The event handler has the same signature as the delegate. The event handler displays the property each time it is raised. + :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventHandler/Overview/source.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventHandler/Overview/source.fs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Timers/ElapsedEventHandler/Overview/source.vb" id="Snippet1"::: diff --git a/xml/System.Timers/Timer.xml b/xml/System.Timers/Timer.xml index 46a899237c6..73ab6865daf 100644 --- a/xml/System.Timers/Timer.xml +++ b/xml/System.Timers/Timer.xml @@ -67,7 +67,7 @@ component is a server-based timer that raises an event in your application after the number of milliseconds in the property has elapsed. You can configure the object to raise the event just once or repeatedly using the property. Typically, a object is declared at the class level so that it stays in scope as long as it is needed. You can then handle its event to provide regular processing. For example, suppose you have a critical server that must be kept running 24 hours a day, 7 days a week. You could create a service that uses a object to periodically check the server and ensure that the system is up and running. If the system is not responding, the service could attempt to restart the server or notify an administrator. + The component is a server-based timer that raises an event in your application after the number of milliseconds in the property has elapsed. You can configure the object to raise the event just once or repeatedly using the property. Typically, a object is declared at the class level so that it stays in scope as long as it is needed. You can then handle its event to provide regular processing. For example, suppose you have a critical server that must be kept running 24 hours a day, 7 days a week. You could create a service that uses a object to periodically check the server and ensure that the system is up and running. If the system is not responding, the service could attempt to restart the server or notify an administrator. > [!IMPORTANT] > The class is not available for all .NET implementations and versions, such as .NET Standard 1.6 and lower versions. @@ -77,10 +77,10 @@ The server-based class is designed for use with worker threads in a multithreaded environment. Server timers can move among threads to handle the raised event, resulting in more accuracy than Windows timers in raising the event on time. - The component raises the event, based on the value (in milliseconds) of the property. You can handle this event to perform the processing you need. For example, suppose that you have an online sales application that continuously posts sales orders to a database. The service that compiles the instructions for shipping operates on a batch of orders rather than processing each order individually. You could use a to start the batch processing every 30 minutes. + The component raises the event, based on the value (in milliseconds) of the property. You can handle this event to perform the processing you need. For example, suppose that you have an online sales application that continuously posts sales orders to a database. The service that compiles the instructions for shipping operates on a batch of orders rather than processing each order individually. You could use a to start the batch processing every 30 minutes. > [!IMPORTANT] -> The System.Timers.Timer class has the same resolution as the system clock. This means that the event will fire at an interval defined by the resolution of the system clock if the property is less than the resolution of the system clock. For more information, see the property. +> The System.Timers.Timer class has the same resolution as the system clock. This means that the event will fire at an interval defined by the resolution of the system clock if the property is less than the resolution of the system clock. For more information, see the property. > [!NOTE] > The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). @@ -93,14 +93,14 @@ :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/AsyncHandlerEx1.fs" id="Snippet3"::: :::code language="vb" source="~/snippets/visualbasic/System.Timers/ElapsedEventArgs/Overview/AsyncHandlerEx1.vb" id="Snippet3"::: - If the property is `null`, the event is raised on a thread. If processing of the event lasts longer than , the event might be raised again on another thread. In this situation, the event handler should be reentrant. + If the property is `null`, the event is raised on a thread. If processing of the event lasts longer than , the event might be raised again on another thread. In this situation, the event handler should be reentrant. > [!NOTE] -> The event-handling method might run on one thread at the same time that another thread calls the method or sets the property to `false`. This might result in the event being raised after the timer is stopped. The example code for the method shows one way to avoid this race condition. +> The event-handling method might run on one thread at the same time that another thread calls the method or sets the property to `false`. This might result in the event being raised after the timer is stopped. The example code for the method shows one way to avoid this race condition. - Even if is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. + Even if is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. - If you use the class with a user interface element, such as a form or control, without placing the timer on that user interface element, assign the form or control that contains the to the property, so that the event is marshaled to the user interface thread. + If you use the class with a user interface element, such as a form or control, without placing the timer on that user interface element, assign the form or control that contains the to the property, so that the event is marshaled to the user interface thread. For a list of default property values for an instance of , see the constructor. @@ -113,7 +113,7 @@ > - (.NET Framework only): an ASP.NET component that performs asynchronous or synchronous web page postbacks at a regular interval. ## Examples - The following example instantiates a `System.Timers.Timer` object that fires its event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a `System.Timers.Timer` object that fires its event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventArgs/Overview/timer2a.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/timer2a.fs" id="Snippet2"::: @@ -190,7 +190,7 @@ ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventArgs/Overview/timer1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/timer1.fs" id="Snippet1"::: @@ -247,12 +247,12 @@ property of the new timer instance, but does not enable the timer. + This constructor sets the property of the new timer instance, but does not enable the timer. ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventArgs/Overview/AsyncHandlerEx1.cs" id="Snippet3"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/AsyncHandlerEx1.fs" id="Snippet3"::: @@ -356,7 +356,7 @@ ## Remarks If is `false`, the method must be called in order to start the count again. - Resetting the interval affects when the event is raised. For example, if you set the interval to 5 seconds and then set the property to `true`, the count starts at the time is set. If you reset the interval to 10 seconds when the count is 3 seconds, the event is raised for the first time 13 seconds after the property was set to `true`. + Resetting the interval affects when the event is raised. For example, if you set the interval to 5 seconds and then set the property to `true`, the count starts at the time is set. If you reset the interval to 10 seconds when the count is 3 seconds, the event is raised for the first time 13 seconds after the property was set to `true`. @@ -581,21 +581,21 @@ event is raised if the property is `true` and the time interval (in milliseconds) defined by the property elapses. If the property is `true`, the event is raised repeatedly at an interval defined by the property; otherwise, the event is raised only once, the first time the value elapses. + The event is raised if the property is `true` and the time interval (in milliseconds) defined by the property elapses. If the property is `true`, the event is raised repeatedly at an interval defined by the property; otherwise, the event is raised only once, the first time the value elapses. If is set after the has started, the count is reset. For example, if you set the interval to 5 seconds and then set to `true`, the count starts at the time is set. If you reset the interval to 10 seconds when count is 3 seconds, the event is raised for the first time 13 seconds after was set to `true`. - If the property is `null`,the event is raised on a thread. If the processing of the event lasts longer than , the event might be raised again on another thread. In this situation, the event handler should be reentrant. + If the property is `null`,the event is raised on a thread. If the processing of the event lasts longer than , the event might be raised again on another thread. In this situation, the event handler should be reentrant. > [!NOTE] -> The event-handling method might run on one thread at the same time that another thread calls the method or sets the property to `false`. This might result in the event being raised after the timer is stopped. The example code for the method shows one way to avoid this race condition. +> The event-handling method might run on one thread at the same time that another thread calls the method or sets the property to `false`. This might result in the event being raised after the timer is stopped. The example code for the method shows one way to avoid this race condition. - Even if is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. + Even if is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. The component catches and suppresses all exceptions thrown by event handlers for the event. This behavior is subject to change in future releases of .NET Framework. ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventArgs/Overview/timer1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/timer1.fs" id="Snippet1"::: @@ -676,17 +676,17 @@ Setting to `true` is the same as calling , while setting to `false` is the same as calling . > [!NOTE] -> The signal to raise the event is always queued for execution on a thread. This might result in the event being raised after the property is set to `false`. The code example for the method shows one way to work around this race condition. +> The signal to raise the event is always queued for execution on a thread. This might result in the event being raised after the property is set to `false`. The code example for the method shows one way to work around this race condition. If is set to `true` and is set to `false`, the raises the event only once, the first time the interval elapses. - If the interval is set after the has started, the count is reset. For example, if you set the interval to 5 seconds and then set the property to `true`, the count starts at the time is set. If you reset the interval to 10 seconds when count is 3 seconds, the event is raised for the first time 13 seconds after was set to `true`. + If the interval is set after the has started, the count is reset. For example, if you set the interval to 5 seconds and then set the property to `true`, the count starts at the time is set. If you reset the interval to 10 seconds when count is 3 seconds, the event is raised for the first time 13 seconds after was set to `true`. > [!NOTE] -> Some visual designers, such as those in Microsoft Visual Studio, set the property to `true` when inserting a new . +> Some visual designers, such as those in Microsoft Visual Studio, set the property to `true` when inserting a new . ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventArgs/Overview/timer1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/timer1.fs" id="Snippet1"::: @@ -827,7 +827,7 @@ property to determine the frequency at which the event is fired. Because the class depends on the system clock, it has the same resolution as the system clock. This means that the event will fire at an interval defined by the resolution of the system clock if the property is less than the resolution of the system clock. The following example sets the property to 5 milliseconds. When run on a Windows system whose system clock has a resolution of approximately 15 milliseconds, the event fires approximately every 15 milliseconds rather than every 5 milliseconds. + You use the property to determine the frequency at which the event is fired. Because the class depends on the system clock, it has the same resolution as the system clock. This means that the event will fire at an interval defined by the resolution of the system clock if the property is less than the resolution of the system clock. The following example sets the property to 5 milliseconds. When run on a Windows system whose system clock has a resolution of approximately 15 milliseconds, the event fires approximately every 15 milliseconds rather than every 5 milliseconds. > [!NOTE] > The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). @@ -838,17 +838,17 @@ If your app requires greater resolution than that offered by the class or the system clock, use the high-resolution multimedia timers; see [How to: Use the High-Resolution Timer](https://msdn.microsoft.com/library/aa964692.aspx). - If the interval is set after the has started, the count is reset. For example, if you set the interval to 5 seconds and then set the property to `true`, the count starts at the time is set. If you reset the interval to 10 seconds when count is 3 seconds, the event is raised for the first time 13 seconds after was set to `true`. + If the interval is set after the has started, the count is reset. For example, if you set the interval to 5 seconds and then set the property to `true`, the count starts at the time is set. If you reset the interval to 10 seconds when count is 3 seconds, the event is raised for the first time 13 seconds after was set to `true`. If is set to `true` and is set to `false`, the raises the event only once, the first time the interval elapses. is then set to `false`. > [!NOTE] -> If and are both set to `false`, and the timer has previously been enabled, setting the property causes the event to be raised once, as if the property had been set to `true`. To set the interval without raising the event, you can temporarily set the property to `true`, set the property to the desired time interval, and then immediately set the property back to `false`. +> If and are both set to `false`, and the timer has previously been enabled, setting the property causes the event to be raised once, as if the property had been set to `true`. To set the interval without raising the event, you can temporarily set the property to `true`, set the property to the desired time interval, and then immediately set the property back to `false`. ## Examples - The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. + The following example instantiates a object that fires its event every two seconds (2000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventArgs/Overview/timer1.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/timer1.fs" id="Snippet1"::: @@ -1039,7 +1039,7 @@ > The signal to raise the event is always queued for execution on a thread, so the event-handling method might run on one thread at the same time that a call to the method runs on another thread. This might result in the event being raised after the method is called. The second code example in the Examples section shows one way to work around this race condition. ## Examples - The following example instantiates a `System.Timers.Timer` object that fires its event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. When the user presses the Enter key, the application calls the method before terminating the application. + The following example instantiates a `System.Timers.Timer` object that fires its event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the property each time it is raised. When the user presses the Enter key, the application calls the method before terminating the application. :::code language="csharp" source="~/snippets/csharp/System.Timers/ElapsedEventArgs/Overview/timer2a.cs" id="Snippet2"::: :::code language="fsharp" source="~/snippets/fsharp/System.Timers/ElapsedEventArgs/Overview/timer2a.fs" id="Snippet2"::: @@ -1131,12 +1131,12 @@ When the event is handled by a visual Windows Forms component, such as a button, accessing the component through the system-thread pool might result in an exception or just might not work. Avoid this effect by setting to a Windows Forms component, which causes the method that handles the event to be called on the same thread that the component was created on. > [!NOTE] -> Even if the property is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. +> Even if the property is not `null`, events can occur after the or method has been called or after the property has been set to `false`, because the signal to raise the event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the event to ignore subsequent events. - If the is used inside Visual Studio in a Windows Forms designer, is automatically set 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`. + If the is used inside Visual Studio in a Windows Forms designer, is automatically set 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`. ## Examples - The following example is a Windows Forms app that serves as a very simple text file editor. When the text in the text box has not been saved, the app asks the user at one-minute intervals whether they want to save the contents of the text box. To do this, the property is set to one minute (60,000 milliseconds), and the property is set to the object. + The following example is a Windows Forms app that serves as a very simple text file editor. When the text in the text box has not been saved, the app asks the user at one-minute intervals whether they want to save the contents of the text box. To do this, the property is set to one minute (60,000 milliseconds), and the property is set to the object. :::code language="csharp" source="~/snippets/csharp/System.Timers/Timer/SynchronizingObject/Form1.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/System.Timers/Timer/SynchronizingObject/Form1.vb" id="Snippet1"::: diff --git a/xml/System.Transactions/CommittableTransaction.xml b/xml/System.Transactions/CommittableTransaction.xml index a26fc789b80..ecc9760dd39 100644 --- a/xml/System.Transactions/CommittableTransaction.xml +++ b/xml/System.Transactions/CommittableTransaction.xml @@ -68,7 +68,7 @@ > [!NOTE] > We recommend that you create implicit transactions using the class, so that the ambient transaction context is automatically managed for you. You should also use the and classes for applications that require the use of the same transaction across multiple function calls or multiple thread calls. For more information on this model, see the [Implementing An Implicit Transaction Using Transaction Scope](/dotnet/framework/data/transactions/implementing-an-implicit-transaction-using-transaction-scope) topic. - Creating a does not automatically set the ambient transaction, which is the transaction your code executes in. You can get or set the ambient transaction by calling the static property of the global object. For more information on ambient transactions, see the " Managing Transaction Flow using TransactionScopeOption" section of the [Implementing An Implicit Transaction Using Transaction Scope](/dotnet/framework/data/transactions/implementing-an-implicit-transaction-using-transaction-scope) topic. If the ambient transaction is not set, any operation on a resource manager is not part of that transaction. You need to explicitly set and reset the ambient transaction to ensure that resource managers operate under the right transaction context. + Creating a does not automatically set the ambient transaction, which is the transaction your code executes in. You can get or set the ambient transaction by calling the static property of the global object. For more information on ambient transactions, see the " Managing Transaction Flow using TransactionScopeOption" section of the [Implementing An Implicit Transaction Using Transaction Scope](/dotnet/framework/data/transactions/implementing-an-implicit-transaction-using-transaction-scope) topic. If the ambient transaction is not set, any operation on a resource manager is not part of that transaction. You need to explicitly set and reset the ambient transaction to ensure that resource managers operate under the right transaction context. Until a has been committed, all the resources involved with the transaction are still locked. @@ -400,7 +400,7 @@ You should call this method in the callback delegate specified as a parameter to the method, when you have finished any cleanup work associated with the asynchronous commitment. You can also call this method early without waiting for the delegate. If, by the time you call this method, the transaction has not completed, this method waits for its completion. > [!CAUTION] -> The property returned by `asyncResult` is always `false`, even if the operation completed synchronously. +> The property returned by `asyncResult` is always `false`, even if the operation completed synchronously. and block until the first phase of transaction processing is complete. The first phase ends after all resource managers and enlistments in the transaction have voted on the transaction outcome and the has durably decided to commit or abort the transaction. The second phase of processing is always asynchronous. Therefore, there is no guarantee that data just committed from within a given transaction will be immediately available afterwards when not using another transaction to view this data. diff --git a/xml/System.Transactions/IEnlistmentNotification.xml b/xml/System.Transactions/IEnlistmentNotification.xml index cce2b76946e..ef1bcd15867 100644 --- a/xml/System.Transactions/IEnlistmentNotification.xml +++ b/xml/System.Transactions/IEnlistmentNotification.xml @@ -237,7 +237,7 @@ ## Remarks The transaction manager calls this method of an enlisted resource manager during the phase 1 of a commitment, when it asks participants whether they can commit the transaction. - When you are implementing a durable resource manager, you should log your prepare record during this phase. The record should contain all the necessary information to perform recovery. This includes the property, which is passed to the transaction manager in the method during recovery. For more information on recovery, see [Performing Recovery](https://msdn.microsoft.com/library/d342c5c7-da64-4a4c-8e63-b52f4fbf2691). + When you are implementing a durable resource manager, you should log your prepare record during this phase. The record should contain all the necessary information to perform recovery. This includes the property, which is passed to the transaction manager in the method during recovery. For more information on recovery, see [Performing Recovery](https://msdn.microsoft.com/library/d342c5c7-da64-4a4c-8e63-b52f4fbf2691). Your resource manager should complete all work that must be finished before calling the method of the `preparingEnlistment` parameter to indicate its vote for commitment. You should make sure that this is accomplished before receiving any phase 2 notification such as commit, rollback or in doubt. This is because phase 2 notifications can happen inline on the same thread that called the method in phase 1. As such, you should not do any work after the call (for example, releasing locks) that you would expect to have completed before receiving the phase 2 notifications. diff --git a/xml/System.Transactions/IsolationLevel.xml b/xml/System.Transactions/IsolationLevel.xml index 813f6ebfbd4..2a40602b784 100644 --- a/xml/System.Transactions/IsolationLevel.xml +++ b/xml/System.Transactions/IsolationLevel.xml @@ -44,15 +44,15 @@ Specifies the isolation level of a transaction. - infrastructure creates `Serializable` transactions. You can determine the isolation level of an existing transaction by using the property of a transaction. - + infrastructure creates `Serializable` transactions. You can determine the isolation level of an existing transaction by using the property of a transaction. + ]]> diff --git a/xml/System.Transactions/PreparingEnlistment.xml b/xml/System.Transactions/PreparingEnlistment.xml index 08a4da70262..68d85902952 100644 --- a/xml/System.Transactions/PreparingEnlistment.xml +++ b/xml/System.Transactions/PreparingEnlistment.xml @@ -45,21 +45,21 @@ Facilitates communication between an enlisted transaction participant and the transaction manager during the Prepare phase of the transaction. - method to obtain a resource's vote on the transaction. Depending on whether it votes to commit or roll back, your implementation of the resource manager should call the or methods of this type. - - The resource manager can also call the method at anytime before it has called the method. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. - - Durable resource managers can retrieve the information that is be needed by the transaction manager for re-enlistment from the property. For more information on recovery, see [Performing Recovery](https://msdn.microsoft.com/library/d342c5c7-da64-4a4c-8e63-b52f4fbf2691). - - - -## Examples + method to obtain a resource's vote on the transaction. Depending on whether it votes to commit or roll back, your implementation of the resource manager should call the or methods of this type. + + The resource manager can also call the method at anytime before it has called the method. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. + + Durable resource managers can retrieve the information that is be needed by the transaction manager for re-enlistment from the property. For more information on recovery, see [Performing Recovery](https://msdn.microsoft.com/library/d342c5c7-da64-4a4c-8e63-b52f4fbf2691). + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/tx_enlist/cs/enlist.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet2"::: + ]]> This type is thread safe. @@ -115,17 +115,17 @@ Indicates that the transaction should be rolled back. - method of the interface calls this method to indicate that the transaction must be rolled back. - - - -## Examples + method of the interface calls this method to indicate that the transaction must be rolled back. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/tx_enlist/cs/enlist.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet2"::: + ]]> @@ -214,21 +214,21 @@ Indicates that the transaction can be committed. - method of the interface, calls this method to indicate that the transaction can be committed. - - The resource manager can call the method at anytime before it has called this method. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. - - Once this method is called by an enlistment and before it returns, it is possible that another thread or this same thread could make a call into the same enlistment method such as to perform a rollback. This can result in a deadlock situation if the resource manager implementation does not release resource locks until after this method returns. - - - -## Examples + method of the interface, calls this method to indicate that the transaction can be committed. + + The resource manager can call the method at anytime before it has called this method. By doing so, the enlistment is casting a read only vote, meaning that it votes commit on the transaction but does not need to receive the final outcome. + + Once this method is called by an enlistment and before it returns, it is possible that another thread or this same thread could make a call into the same enlistment method such as to perform a rollback. This can result in a deadlock situation if the resource manager implementation does not release resource locks until after this method returns. + + + +## Examples :::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/tx_enlist/cs/enlist.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet2"::: + ]]> diff --git a/xml/System.Transactions/Transaction.xml b/xml/System.Transactions/Transaction.xml index 7893385b8b4..9eaf9c5d108 100644 --- a/xml/System.Transactions/Transaction.xml +++ b/xml/System.Transactions/Transaction.xml @@ -68,7 +68,7 @@ ## Remarks The namespace provides both an explicit programming model based on the class, as well as an implicit programming model using the class, in which transactions are automatically managed by the infrastructure. We recommend highly that you use the easier implicit model for development. To get started, see the [Implementing An Implicit Transaction Using Transaction Scope](/dotnet/framework/data/transactions/implementing-an-implicit-transaction-using-transaction-scope) topic. For more information on writing a transactional application, see [Writing A Transactional Application](/dotnet/framework/data/transactions/writing-a-transactional-application). - The class contains methods used by developers implementing resource managers for enlistment. It also provides functionalities for cloning a transaction and controlling the current transaction context. You can obtain the current transaction, if one is set, using the static property. + The class contains methods used by developers implementing resource managers for enlistment. It also provides functionalities for cloning a transaction and controlling the current transaction context. You can obtain the current transaction, if one is set, using the static property. ]]> @@ -1355,7 +1355,7 @@ delegate is a instance. You can then query the property of the specific instance to get an instance of , whose property contains the status of a transaction with either the or value. + You can register for this event instead of using a volatile enlistment to get outcome information for transactions. The parameter passed to the delegate is a instance. You can then query the property of the specific instance to get an instance of , whose property contains the status of a transaction with either the or value. **Caution** Signing up for this event negatively affects the performance of the transaction it is attached to. diff --git a/xml/System.Transactions/TransactionInformation.xml b/xml/System.Transactions/TransactionInformation.xml index ab03630f019..d26d506bd21 100644 --- a/xml/System.Transactions/TransactionInformation.xml +++ b/xml/System.Transactions/TransactionInformation.xml @@ -51,11 +51,11 @@ Provides additional information regarding a transaction. - property of the class. In this way, you can retrieve the status of any transaction object, including the current ambient transaction, by doing a call like `Transaction.Current.TransactionInformation.Status`. - + property of the class. In this way, you can retrieve the status of any transaction object, including the current ambient transaction, by doing a call like `Transaction.Current.TransactionInformation.Status`. + ]]> @@ -99,11 +99,11 @@ Gets the creation time of the transaction. A that contains the creation time of the transaction. -
@@ -147,13 +147,13 @@ Gets a unique identifier of the escalated transaction. A that contains the unique identifier of the escalated transaction. - . - - For more information on how a transaction's management is escalated, see [Transaction Management Escalation](/dotnet/framework/data/transactions/transaction-management-escalation). - + . + + For more information on how a transaction's management is escalated, see [Transaction Management Escalation](/dotnet/framework/data/transactions/transaction-management-escalation). + ]]>
diff --git a/xml/System.Transactions/TransactionManager.xml b/xml/System.Transactions/TransactionManager.xml index 4014f8ab274..c1a052d2c06 100644 --- a/xml/System.Transactions/TransactionManager.xml +++ b/xml/System.Transactions/TransactionManager.xml @@ -292,7 +292,7 @@ property. + For an explanation of the timeout interval, see the documentation for the property. This value can be set in the `MachineSettingsSection` of the config file. diff --git a/xml/System.Transactions/TransactionScope.xml b/xml/System.Transactions/TransactionScope.xml index e2233fcde44..aba5d12234a 100644 --- a/xml/System.Transactions/TransactionScope.xml +++ b/xml/System.Transactions/TransactionScope.xml @@ -67,7 +67,7 @@ > [!IMPORTANT] > We recommend that you create implicit transactions using the class, so that the ambient transaction context is automatically managed for you. You should also use the and class for applications that require the use of the same transaction across multiple function calls or multiple thread calls. For more information on this model, see the [Implementing An Implicit Transaction Using Transaction Scope](/dotnet/framework/data/transactions/implementing-an-implicit-transaction-using-transaction-scope) topic. For more information on writing a transactional application, see [Writing A Transactional Application](/dotnet/framework/data/transactions/writing-a-transactional-application). - Upon instantiating a by the `new` statement, the transaction manager determines which transaction to participate in. Once determined, the scope always participates in that transaction. The decision is based on two factors: whether an ambient transaction is present and the value of the `TransactionScopeOption` parameter in the constructor. The ambient transaction is the transaction your code executes in. You can obtain a reference to the ambient transaction by calling the static property of the class. For more information on how this parameter is used, see the "Transaction Flow Management" section of the [Implementing An Implicit Transaction Using Transaction Scope](/dotnet/framework/data/transactions/implementing-an-implicit-transaction-using-transaction-scope) topic. + Upon instantiating a by the `new` statement, the transaction manager determines which transaction to participate in. Once determined, the scope always participates in that transaction. The decision is based on two factors: whether an ambient transaction is present and the value of the `TransactionScopeOption` parameter in the constructor. The ambient transaction is the transaction your code executes in. You can obtain a reference to the ambient transaction by calling the static property of the class. For more information on how this parameter is used, see the "Transaction Flow Management" section of the [Implementing An Implicit Transaction Using Transaction Scope](/dotnet/framework/data/transactions/implementing-an-implicit-transaction-using-transaction-scope) topic. If no exception occurs within the transaction scope (that is, between the initialization of the object and the calling of its method), then the transaction in which the scope participates is allowed to proceed. If an exception does occur within the transaction scope, the transaction in which it participates will be rolled back. @@ -777,7 +777,7 @@ When you use the `transactionOptions` parameter to specify an property, and trying to do so results in an exception being thrown. + Failing to call this method aborts the transaction, because the transaction manager interprets this as a system failure, or exceptions thrown within the scope of transaction. However, you should also note that calling this method does not guarantee a commit of the transaction. It is merely a way of informing the transaction manager of your status. After calling this method, you can no longer access the ambient transaction via the property, and trying to do so results in an exception being thrown. The actual work of commit between the resources manager happens at the `End Using` statement if the object created the transaction. If it did not create the transaction, the commit occurs whenever is called by the owner of the object. At that point the Transaction Manager calls the resource managers and informs them to either commit or rollback, based on whether this method was called on the object. diff --git a/xml/System.Workflow.Activities.Rules/RuleEvaluationException.xml b/xml/System.Workflow.Activities.Rules/RuleEvaluationException.xml index e709ba95d32..6fedfbfd682 100644 --- a/xml/System.Workflow.Activities.Rules/RuleEvaluationException.xml +++ b/xml/System.Workflow.Activities.Rules/RuleEvaluationException.xml @@ -54,18 +54,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error and takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||A system-supplied localized description.| - + property of the new instance to a system-supplied message that describes the error and takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||A system-supplied localized description.| + ]]> @@ -90,18 +90,18 @@ The message that describes the error. Initializes a new instance of the class with a specified error message. - property of the new instance using the `message` parameter. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + property of the new instance using the `message` parameter. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]>
@@ -128,11 +128,11 @@ The that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. -
@@ -159,18 +159,18 @@ The that is the cause of the current . If the innerException parameter is not a null reference ( in Visual Basic), the current is raised in a catch block that handles the inner . Initializes a new instance of the class, with a specified error message and a reference to the inner that is the cause of this . - that is thrown as a direct result of a previous should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing`) if the property does not supply the inner value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner reference.| -||The error message string.| - + that is thrown as a direct result of a previous should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing`) if the property does not supply the inner value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner reference.| +||The error message string.| + ]]>
diff --git a/xml/System.Workflow.Activities.Rules/RuleEvaluationIncompatibleTypesException.xml b/xml/System.Workflow.Activities.Rules/RuleEvaluationIncompatibleTypesException.xml index d04bfb6803a..cbe37f439cb 100644 --- a/xml/System.Workflow.Activities.Rules/RuleEvaluationIncompatibleTypesException.xml +++ b/xml/System.Workflow.Activities.Rules/RuleEvaluationIncompatibleTypesException.xml @@ -76,18 +76,18 @@ A that contains the error message to associate with this instance. Initializes a new instance of the with a specified error message. - property of the new instance using the message parameter. - - The following table shows the initial property values for an instance of Exception. - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + property of the new instance using the message parameter. + + The following table shows the initial property values for an instance of Exception. + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]>
@@ -114,11 +114,11 @@ The that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -148,11 +148,11 @@ The instance that caused the current exception. Initializes a new instance of the class with a specified error message and a reference to the inner that is the cause of this . - that is thrown as a direct result of a previous should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. - + that is thrown as a direct result of a previous should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing` in Visual Basic) if the property does not supply the inner exception value to the constructor. + ]]> @@ -183,19 +183,19 @@ The appearing on the right side of the operator. Initializes a new instance of the class with the details of the compatibility violation. - |A null reference (`Nothing` in Visual Basic).| -||The value of the argument `message`| -||The value of the argument `left`.| -||The value of the argument `op`.| -||The value of the argument `right`.| - + |A null reference (`Nothing` in Visual Basic).| +||The value of the argument `message`| +||The value of the argument `left`.| +||The value of the argument `op`.| +||The value of the argument `right`.| + ]]> @@ -228,19 +228,19 @@ The instance that caused the current exception. Initializes a new instance of the class with the details of the compatibility violation. This includes the . - |The value of the argument `ex`.| -||The value of the argument `message`| -||The value of the argument `left`.| -||The value of the argument `op`.| -||The value of the argument `right`.| - + |The value of the argument `ex`.| +||The value of the argument `message`| +||The value of the argument `left`.| +||The value of the argument `op`.| +||The value of the argument `right`.| + ]]> @@ -273,11 +273,11 @@ The that contains contextual information about the source or destination. Sets the with information about the exception. - sets a with all the object data targeted for serialization. During de-serialization, this exception is reconstituted from the transmitted over the stream. - + sets a with all the object data targeted for serialization. During de-serialization, this exception is reconstituted from the transmitted over the stream. + ]]> diff --git a/xml/System.Workflow.Activities.Rules/RuleException.xml b/xml/System.Workflow.Activities.Rules/RuleException.xml index 2f97aca9758..2444b1ba3ae 100644 --- a/xml/System.Workflow.Activities.Rules/RuleException.xml +++ b/xml/System.Workflow.Activities.Rules/RuleException.xml @@ -54,18 +54,18 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error and takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||A system-supplied localized description.| - + property of the new instance to a system-supplied message that describes the error and takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||A system-supplied localized description.| + ]]> @@ -90,18 +90,18 @@ The message that describes the error. Initializes a new instance of the class with a specified error message. - property of the new instance using the `message` parameter. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| - + property of the new instance using the `message` parameter. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| + ]]> @@ -128,11 +128,11 @@ The that contains contextual information about the source or destination. Initializes a new instance of the class with serialized data. - @@ -159,18 +159,18 @@ The that is the cause of the current . If the innerException parameter is not a null reference ( in Visual Basic), the current is raised in a catch block that handles the inner . Initializes a new instance of the class, with a specified error message and a reference to the inner that is the cause of this . - that is thrown as a direct result of a previous should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing`) if the property does not supply the inner value to the constructor. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner reference.| -||The error message string.| - + that is thrown as a direct result of a previous should include a reference to the previous exception in the property. The property returns the same value that is passed into the constructor, or a null reference (`Nothing`) if the property does not supply the inner value to the constructor. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner reference.| +||The error message string.| + ]]> diff --git a/xml/System.Workflow.Activities.Rules/RuleExpressionInfo.xml b/xml/System.Workflow.Activities.Rules/RuleExpressionInfo.xml index 4c846a1bf49..f52edfa8aef 100644 --- a/xml/System.Workflow.Activities.Rules/RuleExpressionInfo.xml +++ b/xml/System.Workflow.Activities.Rules/RuleExpressionInfo.xml @@ -17,13 +17,13 @@ An instance of this class is returned by the method of an expression. - property on provides the return type of the expression. For example, a binary expression, when evaluated, has a return type of Boolean; or, an expression that accesses a property might return an integer type. - - The information in the can be used to validate the use of the expression. For example, a greater-than test cannot be used to compare two expressions if either returns a Boolean. - + property on provides the return type of the expression. For example, a binary expression, when evaluated, has a return type of Boolean; or, an expression that accesses a property might return an integer type. + + The information in the can be used to validate the use of the expression. For example, a greater-than test cannot be used to compare two expressions if either returns a Boolean. + ]]> diff --git a/xml/System.Workflow.Activities/CallExternalMethodActivity.xml b/xml/System.Workflow.Activities/CallExternalMethodActivity.xml index cf57efd62cc..90dc7881f59 100644 --- a/xml/System.Workflow.Activities/CallExternalMethodActivity.xml +++ b/xml/System.Workflow.Activities/CallExternalMethodActivity.xml @@ -237,7 +237,7 @@ property, verifies the and properties are set and verifies that the event referenced in the property can be found in the interface referenced in the property. + This method initializes the property, verifies the and properties are set and verifies that the event referenced in the property can be found in the interface referenced in the property. ]]> @@ -306,7 +306,7 @@ property corresponds to the name of the interface that was marked with the . + The property corresponds to the name of the interface that was marked with the . [!INCLUDE[DependencyPropertyRemark](~/includes/dependencypropertyremark-md.md)] @@ -439,7 +439,7 @@ property corresponds to the name of a method contained on an interface that is marked with the . + The property corresponds to the name of a method contained on an interface that is marked with the . [!INCLUDE[DependencyPropertyRemark](~/includes/dependencypropertyremark-md.md)] diff --git a/xml/System.Workflow.Activities/ConditionalEventArgs.xml b/xml/System.Workflow.Activities/ConditionalEventArgs.xml index 907cafcb18a..83ef65b08b6 100644 --- a/xml/System.Workflow.Activities/ConditionalEventArgs.xml +++ b/xml/System.Workflow.Activities/ConditionalEventArgs.xml @@ -27,15 +27,15 @@ Returns result information for the class. This class cannot be inherited. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - The class exposes an event of type EventHandler\. The purpose of the event is to provide information about the result of the condition evaluation (`true` or `false`) through the property of the event args. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + The class exposes an event of type EventHandler\. The purpose of the event is to provide information about the result of the condition evaluation (`true` or `false`) through the property of the event args. + ]]> diff --git a/xml/System.Workflow.Activities/DelayActivity.xml b/xml/System.Workflow.Activities/DelayActivity.xml index 6ff6843dccf..1a82a7d24ac 100644 --- a/xml/System.Workflow.Activities/DelayActivity.xml +++ b/xml/System.Workflow.Activities/DelayActivity.xml @@ -61,7 +61,7 @@ You can set a time out on the so that your workflow pauses before resuming execution. You specify the using . This causes your workflow to pause until the specified has elapsed. - The class runs the code method associated with the event before the activity starts and the code-beside method can be used to initialize the property. + The class runs the code method associated with the event before the activity starts and the code-beside method can be used to initialize the property. The is guaranteed to complete no sooner than the indicated . The delay can take longer because the timer notification might occur some time after the is reached. One reason for a longer delay is if the workflow is running under high system stress in a server environment. diff --git a/xml/System.Workflow.Activities/ExternalDataEventArgs.xml b/xml/System.Workflow.Activities/ExternalDataEventArgs.xml index 79e0fa5f3db..bb04e073ae0 100644 --- a/xml/System.Workflow.Activities/ExternalDataEventArgs.xml +++ b/xml/System.Workflow.Activities/ExternalDataEventArgs.xml @@ -166,7 +166,7 @@ activity. If the value that is set in the property of this activity does not match any of the roles associated with the user identity, the activity is not allowed to execute. + This property is evaluated by the activity. If the value that is set in the property of this activity does not match any of the roles associated with the user identity, the activity is not allowed to execute. The entity that raises the event can be a person or a computer. diff --git a/xml/System.Workflow.Activities/HandleExternalEventActivity.xml b/xml/System.Workflow.Activities/HandleExternalEventActivity.xml index 36807bd7174..a1231dc547f 100644 --- a/xml/System.Workflow.Activities/HandleExternalEventActivity.xml +++ b/xml/System.Workflow.Activities/HandleExternalEventActivity.xml @@ -401,7 +401,7 @@ property, verifies the and properties are set and verifies that the event referenced in the property can be found in the interface referenced in the property. + This method initializes the property, verifies the and properties are set and verifies that the event referenced in the property can be found in the interface referenced in the property. ]]> diff --git a/xml/System.Workflow.Activities/InvokeWorkflowActivity.xml b/xml/System.Workflow.Activities/InvokeWorkflowActivity.xml index 0e301eb8303..832f9237b1a 100644 --- a/xml/System.Workflow.Activities/InvokeWorkflowActivity.xml +++ b/xml/System.Workflow.Activities/InvokeWorkflowActivity.xml @@ -170,7 +170,7 @@ of the created instance is assigned to the property. + Once the workflow is started the of the created instance is assigned to the property. This property is a bindable property. The instance can be retrieved in the code-beside. diff --git a/xml/System.Workflow.Activities/ReceiveActivity.xml b/xml/System.Workflow.Activities/ReceiveActivity.xml index 615c5abd899..8422a07fb1b 100644 --- a/xml/System.Workflow.Activities/ReceiveActivity.xml +++ b/xml/System.Workflow.Activities/ReceiveActivity.xml @@ -401,9 +401,9 @@ property is set to an instance of type , the fault is returned to the client upon completion. + If the property is set to an instance of type , the fault is returned to the client upon completion. - If an exception is thrown during the activity execution and the property is set, then the specified fault is returned to the client. If an exception is thrown during the activity execution and the property is set, and the associated operation has a attribute that specifies a fault type that matches that of the property, then the channel is not faulted and the client can still communicate to the server. If the property is not set, the thrown exception is returned as a fault to the client. + If an exception is thrown during the activity execution and the property is set, then the specified fault is returned to the client. If an exception is thrown during the activity execution and the property is set, and the associated operation has a attribute that specifies a fault type that matches that of the property, then the channel is not faulted and the client can still communicate to the server. If the property is not set, the thrown exception is returned as a fault to the client. ]]> @@ -431,11 +431,11 @@ property and a public workflow property/field of type or another activity's public property/field of the same type. + This dependency property can be used to set up a binding between the receive activity's property and a public workflow property/field of type or another activity's public property/field of the same type. - This dependency property can also be used to set the value associated with the property of a activity. + This dependency property can also be used to set the value associated with the property of a activity. - This dependency property can also be used to get the binding or value associated with the property of the activity. + This dependency property can also be used to get the binding or value associated with the property of the activity. ]]> @@ -844,7 +844,7 @@ property can be set to an instance of type or . can be used to configure a receive activity using an existing Windows Communication Foundation (WCF) service contract. + The property can be set to an instance of type or . can be used to configure a receive activity using an existing Windows Communication Foundation (WCF) service contract. An instance of can be used to configure a receive activity for the workflow-first contract scenario. diff --git a/xml/System.Workflow.Activities/StateMachineWorkflowActivity.xml b/xml/System.Workflow.Activities/StateMachineWorkflowActivity.xml index 40ac6e6eaa8..bdac013f65d 100644 --- a/xml/System.Workflow.Activities/StateMachineWorkflowActivity.xml +++ b/xml/System.Workflow.Activities/StateMachineWorkflowActivity.xml @@ -221,9 +221,9 @@ property only returns the name of the current state when accessed from within the workflow, for example, from a code handler in a activity. The property does not work from host code because the host only has access to a copy of the workflow definition, and never to the live instance tree. + The property only returns the name of the current state when accessed from within the workflow, for example, from a code handler in a activity. The property does not work from host code because the host only has access to a copy of the workflow definition, and never to the live instance tree. - For more information about how to determine the current state from the host, see the property of the class. + For more information about how to determine the current state from the host, see the property of the class. ]]> @@ -288,7 +288,7 @@ property is mandatory and must be provided when a is created. The of the state machine is like any other state activity that is contained within the state machine. The state activity can be a direct child of the root activity and a can have only one . + The property is mandatory and must be provided when a is created. The of the state machine is like any other state activity that is contained within the state machine. The state activity can be a direct child of the root activity and a can have only one . For more information about and , see . @@ -357,9 +357,9 @@ property only returns the name of the previous state when accessed from within the workflow, for example, from a code handler in a . The property does not work from host code because the host only has access to a copy of the workflow definition, never to the live instance tree. + The property only returns the name of the previous state when accessed from within the workflow, for example, from a code handler in a . The property does not work from host code because the host only has access to a copy of the workflow definition, never to the live instance tree. - For more information about how to determine the previous state from the host, see the property of the class. + For more information about how to determine the previous state from the host, see the property of the class. ]]> diff --git a/xml/System.Workflow.Activities/WebServiceInputActivity.xml b/xml/System.Workflow.Activities/WebServiceInputActivity.xml index 40d5483be21..101be1e3ed9 100644 --- a/xml/System.Workflow.Activities/WebServiceInputActivity.xml +++ b/xml/System.Workflow.Activities/WebServiceInputActivity.xml @@ -414,7 +414,7 @@ property set to `true`. If more than one is set to `true`, the session is locked on the first request. This lasts as long as the other receive blocks the workflow; the session is deadlocked. + Only the first receive in a workflow can have the property set to `true`. If more than one is set to `true`, the session is locked on the first request. This lasts as long as the other receive blocks the workflow; the session is deadlocked. ]]> @@ -443,7 +443,7 @@ property should be set to `true` for only the very first . This signals to the workflow runtime that invoking this Web service method from a client starts the execution of the workflow. The first activity of a workflow definition that is exposed as a Web service is of type and sets this property to `true`. [!INCLUDE[DependencyPropertyRemark](~/includes/dependencypropertyremark-md.md)] + The property should be set to `true` for only the very first . This signals to the workflow runtime that invoking this Web service method from a client starts the execution of the workflow. The first activity of a workflow definition that is exposed as a Web service is of type and sets this property to `true`. [!INCLUDE[DependencyPropertyRemark](~/includes/dependencypropertyremark-md.md)] ]]> diff --git a/xml/System.Workflow.Activities/WhileActivity.xml b/xml/System.Workflow.Activities/WhileActivity.xml index 84ffc1f9870..2d702f0f4c3 100644 --- a/xml/System.Workflow.Activities/WhileActivity.xml +++ b/xml/System.Workflow.Activities/WhileActivity.xml @@ -52,7 +52,7 @@ The is a , meaning the can contain other activities. - Before each iteration, the property is evaluated. If the property evaluates to `false`, the immediately finishes. + Before each iteration, the property is evaluated. If the property evaluates to `false`, the immediately finishes. ]]> diff --git a/xml/System.Workflow.ComponentModel.Compiler/CompileWorkflowTask.xml b/xml/System.Workflow.ComponentModel.Compiler/CompileWorkflowTask.xml index 708410472ff..f12fc41ac9a 100644 --- a/xml/System.Workflow.ComponentModel.Compiler/CompileWorkflowTask.xml +++ b/xml/System.Workflow.ComponentModel.Compiler/CompileWorkflowTask.xml @@ -27,15 +27,15 @@ Represents the MSBuild task of compiling a workflow. This class cannot be inherited. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - This class extends the `Task` class of Microsoft Build framework. Methods of this class are invoked by the Microsoft Build framework to customize the build process when compiling Windows Workflow Foundation types of C# and Visual Basic projects. It provides support for compiling .xoml files into intermediate code files (either C# or Visual Basic). Workflows are validated before compiling. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + This class extends the `Task` class of Microsoft Build framework. Methods of this class are invoked by the Microsoft Build framework to customize the build process when compiling Windows Workflow Foundation types of C# and Visual Basic projects. It provides support for compiling .xoml files into intermediate code files (either C# or Visual Basic). Workflows are validated before compiling. + ]]> @@ -194,11 +194,11 @@ Gets or sets the that is used to obtain services provided by the Visual Studio host when the compile workflow task is invoked. The that is used to obtain services provided by Visual Studio host when the compile workflow task is invoked. - @@ -296,11 +296,11 @@ Gets or sets the path of the file that is used for signing the workflow assembly. The path of the file that is used for signing the workflow assembly. - @@ -364,11 +364,11 @@ This member is an explicit interface member implementation. It can be used only Gets an array of paths to output files from the workflow project being compiled. An array of paths to output files from the workflow project being compiled. - property. - + property. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Compiler/IWorkflowCompilerOptionsService.xml b/xml/System.Workflow.ComponentModel.Compiler/IWorkflowCompilerOptionsService.xml index 5785dee6035..781f9b2c45d 100644 --- a/xml/System.Workflow.ComponentModel.Compiler/IWorkflowCompilerOptionsService.xml +++ b/xml/System.Workflow.ComponentModel.Compiler/IWorkflowCompilerOptionsService.xml @@ -55,9 +55,9 @@ property is `true` and the workflow or the companion rules file directly references any .NET types not present on a list of authorized types. The list of authorized types is an XML document where each entry indicates an `Assembly`, a `Namespace`, a `TypeName`, and an `Authorized` {`true` or `false`} indicator. This class corresponds to an entry on the list. Also note that wildcard character designations are allowed, to include or exclude complete namespaces. For example, using `Type="System.*"` includes all types in , including types contained in child namespaces. + During the validation phase of workflow compilation, a workflow source document is rejected if the property is `true` and the workflow or the companion rules file directly references any .NET types not present on a list of authorized types. The list of authorized types is an XML document where each entry indicates an `Assembly`, a `Namespace`, a `TypeName`, and an `Authorized` {`true` or `false`} indicator. This class corresponds to an entry on the list. Also note that wildcard character designations are allowed, to include or exclude complete namespaces. For example, using `Type="System.*"` includes all types in , including types contained in child namespaces. - The use of a list of authorized types is controlled by the option **/checktypes** or by using the property. + The use of a list of authorized types is controlled by the option **/checktypes** or by using the property. ]]> diff --git a/xml/System.Workflow.ComponentModel.Compiler/WorkflowCompilationContext.xml b/xml/System.Workflow.ComponentModel.Compiler/WorkflowCompilationContext.xml index d8bf1fff6ac..b422aabf05a 100644 --- a/xml/System.Workflow.ComponentModel.Compiler/WorkflowCompilationContext.xml +++ b/xml/System.Workflow.ComponentModel.Compiler/WorkflowCompilationContext.xml @@ -22,15 +22,15 @@ Provides workflow compilation options for the current compilation or validation task. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - This class can only be created on a scope basis, using the method. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + This class can only be created on a scope basis, using the method. + ]]> @@ -55,11 +55,11 @@ if is enabled; otherwise, . - indicates whether the types in the workflow being compiled are checked against a list that allows or excludes types based on the value of the property. - + indicates whether the types in the workflow being compiled are checked against a list that allows or excludes types based on the value of the property. + ]]> @@ -87,11 +87,11 @@ Initializes a class at the current scope. A reference to the scope. - the context is set according to that service. - + the context is set according to that service. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/ActivityDesigner.xml b/xml/System.Workflow.ComponentModel.Design/ActivityDesigner.xml index 76c2500c387..3639af848de 100644 --- a/xml/System.Workflow.ComponentModel.Design/ActivityDesigner.xml +++ b/xml/System.Workflow.ComponentModel.Design/ActivityDesigner.xml @@ -125,7 +125,7 @@ If no is currently assigned to the control, a new instance of one is created. > [!NOTE] -> To get or set the property, you must add a reference to the Accessibility assembly installed with the .NET Framework. +> To get or set the property, you must add a reference to the Accessibility assembly installed with the .NET Framework. For more information about accessible objects, see [Microsoft Active Accessibility](/windows/win32/winauto/microsoft-active-accessibility). @@ -749,7 +749,7 @@ property is set to the to display. You can do this at design time or at run time. + The property is set to the to display. You can do this at design time or at run time. ]]> @@ -1065,7 +1065,7 @@ property for operations such as cut and paste, or updating the properties of an Activity when changes are made in a property window, for example. + Use the property for operations such as cut and paste, or updating the properties of an Activity when changes are made in a property window, for example. ]]> @@ -1183,7 +1183,7 @@ property to position the designer on the design surface at design time or run time. + Use the property to position the designer on the design surface at design time or run time. ]]> @@ -1234,7 +1234,7 @@ is determined by the size settings accessible through the property. + is determined by the size settings accessible through the property. ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/ActivityDesignerAccessibleObject.xml b/xml/System.Workflow.ComponentModel.Design/ActivityDesignerAccessibleObject.xml index f99d6e737ce..8695ec9d5b7 100644 --- a/xml/System.Workflow.ComponentModel.Design/ActivityDesignerAccessibleObject.xml +++ b/xml/System.Workflow.ComponentModel.Design/ActivityDesignerAccessibleObject.xml @@ -23,13 +23,13 @@ Implements an accessible object that classes use to adjust the designer user interface for users who have impairments. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + ]]> @@ -120,11 +120,11 @@ Gets a string that describes the default action of the activity designer. A description of the default action associated with the activity designer, or a null reference ( in Visual Basic) if the object has no default action. - @@ -149,11 +149,11 @@ Gets a string that describes the visual appearance of the activity designer. A description of the activity designer's visual appearance, or a null reference ( in Visual Basic) if the object has no description. - @@ -178,11 +178,11 @@ Performs the default action associated with the . - . - + . + ]]> @@ -255,13 +255,13 @@ Gets or sets the name of the associated with the accessible object's . The name of the or a null reference ( in Visual Basic) if the property has not been set. - property is a string used by clients to identify, find, or announce an activity for the user. To access the name of a child activity, you must first call with the index of the name of the child activity you are retrieving. - - You cannot perform a set operation on . - + property is a string used by clients to identify, find, or announce an activity for the user. To access the name of a child activity, you must first call with the index of the name of the child activity you are retrieving. + + You cannot perform a set operation on . + ]]> @@ -334,11 +334,11 @@ Gets the role of the current . One of the values, or if no role has been specified. - member of . - + member of . + ]]> @@ -388,13 +388,13 @@ Gets the accessible state of the current . A combination of values. - has the following possible values: - - , , , , , , , and . - + has the following possible values: + + , , , , , , , and . + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/ActivityDesignerGlyphCollection.xml b/xml/System.Workflow.ComponentModel.Design/ActivityDesignerGlyphCollection.xml index 02b9e0e00d8..0863437d6e4 100644 --- a/xml/System.Workflow.ComponentModel.Design/ActivityDesignerGlyphCollection.xml +++ b/xml/System.Workflow.ComponentModel.Design/ActivityDesignerGlyphCollection.xml @@ -26,17 +26,17 @@ Exposes a generic of designer glyphs associated with an activity designer. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - contains all designer glyphs that appear on the class with which the collection is associated. - - You can access the contents of the through the property. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + contains all designer glyphs that appear on the class with which the collection is associated. + + You can access the contents of the through the property. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/ActivityDesignerTheme.xml b/xml/System.Workflow.ComponentModel.Design/ActivityDesignerTheme.xml index f0cf2aa07f3..89740140306 100644 --- a/xml/System.Workflow.ComponentModel.Design/ActivityDesignerTheme.xml +++ b/xml/System.Workflow.ComponentModel.Design/ActivityDesignerTheme.xml @@ -624,7 +624,7 @@ property to specify the foreground color of the theme. The foreground color is usually the color of the text. + Use the property to specify the foreground color of the theme. The foreground color is usually the color of the text. ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/ActivityDesignerThemeAttribute.xml b/xml/System.Workflow.ComponentModel.Design/ActivityDesignerThemeAttribute.xml index 9895c66abea..70cc1f99c26 100644 --- a/xml/System.Workflow.ComponentModel.Design/ActivityDesignerThemeAttribute.xml +++ b/xml/System.Workflow.ComponentModel.Design/ActivityDesignerThemeAttribute.xml @@ -27,15 +27,15 @@ Specifies the theme class an activity designer uses on the workflow design surface. This class cannot be inherited. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - Theme classes specify a set of properties that determine the appearance of an activity when it is placed on a workflow design surface. Activity-designer developers can associate a theme class to a designer by declaring a Theme attribute for the designer. The class defines the declarative Theme attribute, including the argument that must be passed in the attribute, and all of its properties. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + Theme classes specify a set of properties that determine the appearance of an activity when it is placed on a workflow design surface. Activity-designer developers can associate a theme class to a designer by declaring a Theme attribute for the designer. The class defines the declarative Theme attribute, including the argument that must be passed in the attribute, and all of its properties. + ]]> @@ -104,11 +104,11 @@ Gets or sets an XML string that defines default property settings for the activity designer. A string that contains the default theme property settings in XML format. - property by declaring the property in the Theme attribute. - + property by declaring the property in the Theme attribute. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/ActivityDragEventArgs.xml b/xml/System.Workflow.ComponentModel.Design/ActivityDragEventArgs.xml index 4f6d4f4dd4a..7c6f6e46697 100644 --- a/xml/System.Workflow.ComponentModel.Design/ActivityDragEventArgs.xml +++ b/xml/System.Workflow.ComponentModel.Design/ActivityDragEventArgs.xml @@ -23,15 +23,15 @@ Represents a class that provides data for the , , and events in the workflow designer. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - These event arguments are passed to classes when a drag-and-drop operation is in progress on the workflow design surface. classes can access the information contained in the class to influence the behavior of the operation. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + These event arguments are passed to classes when a drag-and-drop operation is in progress on the workflow design surface. classes can access the information contained in the class to influence the behavior of the operation. + ]]> @@ -78,11 +78,11 @@ Gets or sets the location where the activities are to be dropped on the workflow design surface. A that defines the location on the workflow design surface where the activities will be dropped. - class creates a drag image for the activities being dragged. objects can use the property to snap the image to a target and drop the activities at the specified location. - + class creates a drag image for the activities being dragged. objects can use the property to snap the image to a target and drop the activities at the specified location. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/ActivityPreviewDesigner.xml b/xml/System.Workflow.ComponentModel.Design/ActivityPreviewDesigner.xml index 20da29005e7..2515e0d40fd 100644 --- a/xml/System.Workflow.ComponentModel.Design/ActivityPreviewDesigner.xml +++ b/xml/System.Workflow.ComponentModel.Design/ActivityPreviewDesigner.xml @@ -221,7 +221,7 @@ and do not contain null references (`Nothing` in Visual Basic), will return the value of the property of the . If the property contains a null reference (`Nothing`), will return the associated with the first designer in the collection. + If and do not contain null references (`Nothing` in Visual Basic), will return the value of the property of the . If the property contains a null reference (`Nothing`), will return the associated with the first designer in the collection. ]]> @@ -508,7 +508,7 @@ and do not contain null references (`Nothing` in Visual Basic), returns the value of the property of the . If the contains a null reference (`Nothing` in Visual Basic), returns the associated with the last designer in the collection. + If and do not contain null references (`Nothing` in Visual Basic), returns the value of the property of the . If the contains a null reference (`Nothing` in Visual Basic), returns the associated with the last designer in the collection. ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/AmbientTheme.xml b/xml/System.Workflow.ComponentModel.Design/AmbientTheme.xml index c238074c5c0..a76f772f0d9 100644 --- a/xml/System.Workflow.ComponentModel.Design/AmbientTheme.xml +++ b/xml/System.Workflow.ComponentModel.Design/AmbientTheme.xml @@ -95,7 +95,7 @@ property, it negates the property value. + When you set the property, it negates the property value. ]]> @@ -134,7 +134,7 @@ with its color set to the current property value. + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a with its color set to the current property value. ]]> @@ -237,7 +237,7 @@ with its color set to the current property value. + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a with its color set to the current property value. ]]> @@ -312,7 +312,7 @@ with its color set to the current property value and its width set to 1. + If this property contains a null reference (`Nothing` in Visual Basic) by default it will return a with its color set to the current property value and its width set to 1. ]]> @@ -516,7 +516,7 @@ with its color set to the current property value. + If this property contains a null reference (`Nothing` in Visual Basic) by default it will return a with its color set to the current property value. ]]> @@ -591,7 +591,7 @@ with its color set to the current property value and its width set to the property. + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a with its color set to the current property value and its width set to the property. ]]> @@ -730,7 +730,7 @@ with its color set to the current property value. + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a with its color set to the current property value. ]]> @@ -769,7 +769,7 @@ with its color set to the current property value, its width set to 1, and its property set to . + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a with its color set to the current property value, its width set to 1, and its property set to . ]]> @@ -969,7 +969,7 @@ with its color set to the current property value. + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a with its color set to the current property value. ]]> @@ -1008,7 +1008,7 @@ with its color set to the current property value, its width set to 1, and its property set to . + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a with its color set to the current property value, its width set to 1, and its property set to . ]]> @@ -1079,7 +1079,7 @@ with its color calculated based on the current property value, its width set to 1, and its property set to . + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a with its color calculated based on the current property value, its width set to 1, and its property set to . ]]> @@ -1150,7 +1150,7 @@ object with its color set to the current property value. + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a object with its color set to the current property value. ]]> @@ -1261,7 +1261,7 @@ object with its color set to the current property value. + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a object with its color set to the current property value. ]]> @@ -1300,7 +1300,7 @@ property value and its width set to 1. + If this property contains a null reference (`Nothing` in Visual Basic) by default it will return a `Pen` with its color set to the current property value and its width set to 1. ]]> @@ -1382,7 +1382,7 @@ with its color set to the current property value, its width set to 1, and its property set to . + If this property contains a null reference (`Nothing` in Visual Basic), by default it will return a with its color set to the current property value, its width set to 1, and its property set to . ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/CommentGlyph.xml b/xml/System.Workflow.ComponentModel.Design/CommentGlyph.xml index e0065128a79..b3ad3151a3d 100644 --- a/xml/System.Workflow.ComponentModel.Design/CommentGlyph.xml +++ b/xml/System.Workflow.ComponentModel.Design/CommentGlyph.xml @@ -23,15 +23,15 @@ Provides a glyph for an to display when a user disables an activity at design time. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - Activity designers display when a user sets the property to `false` at design time for the designer or its parent designer. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + Activity designers display when a user sets the property to `false` at design time for the designer or its parent designer. + ]]> @@ -81,11 +81,11 @@ Returns the bounds for the current comment glyph on the specified . A that represents the bounds for the glyph. - inflates the bounds of `designer` by the value held in and returns the resultant rectangle. - + inflates the bounds of `designer` by the value held in and returns the resultant rectangle. + ]]> @@ -142,11 +142,11 @@ Gets the view priority of the glyph on the activity designer. An integer that represents the view priority of the glyph on the activity designer. - diff --git a/xml/System.Workflow.ComponentModel.Design/CompositeActivityDesigner.xml b/xml/System.Workflow.ComponentModel.Design/CompositeActivityDesigner.xml index a3266fd04bf..599ee805ae2 100644 --- a/xml/System.Workflow.ComponentModel.Design/CompositeActivityDesigner.xml +++ b/xml/System.Workflow.ComponentModel.Design/CompositeActivityDesigner.xml @@ -90,7 +90,7 @@ If no is currently assigned to the control, a new instance of one is created. > [!NOTE] -> To get or set the property, you must add a reference to the Accessibility assembly installed with the .NET Framework. +> To get or set the property, you must add a reference to the Accessibility assembly installed with the .NET Framework. For more information about accessible objects, see [Microsoft Active Accessibility](/windows/win32/winauto/microsoft-active-accessibility). @@ -775,7 +775,7 @@ property should determine whether the designer allows edits at design time. + Some custom activities might not allow you to modify properties or other settings in the design environment. The property should determine whether the designer allows edits at design time. ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/CompositeDesignerTheme.xml b/xml/System.Workflow.ComponentModel.Design/CompositeDesignerTheme.xml index d04e15b7f34..e1aac70ddb4 100644 --- a/xml/System.Workflow.ComponentModel.Design/CompositeDesignerTheme.xml +++ b/xml/System.Workflow.ComponentModel.Design/CompositeDesignerTheme.xml @@ -268,7 +268,7 @@ property is set to `true`, the method obtains settings for the object from the operating system. + If the property is set to `true`, the method obtains settings for the object from the operating system. ]]> @@ -302,7 +302,7 @@ ## Remarks When this method is called it sets the and properties to . - The enumeration determines where a designer theme obtains its ambient property settings. If the value is set, the designer theme class obtains its ambient settings from the property. If the value is set, the designer theme class obtains its ambient settings from the operating system on which the designer is installed. + The enumeration determines where a designer theme obtains its ambient property settings. If the value is set, the designer theme class obtains its ambient settings from the property. If the value is set, the designer theme class obtains its ambient settings from the operating system on which the designer is installed. ]]> @@ -406,7 +406,7 @@ property value is `null` (`Nothing` in Visual Basic) this property will provide the image for the watermark. If the property is set to a valid value, this property is set to `null` (`Nothing`). + If the property value is `null` (`Nothing` in Visual Basic) this property will provide the image for the watermark. If the property is set to a valid value, this property is set to `null` (`Nothing`). ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/DesignerGlyph.xml b/xml/System.Workflow.ComponentModel.Design/DesignerGlyph.xml index a0f1be0ff92..7dfb723db2f 100644 --- a/xml/System.Workflow.ComponentModel.Design/DesignerGlyph.xml +++ b/xml/System.Workflow.ComponentModel.Design/DesignerGlyph.xml @@ -32,7 +32,7 @@ The class is the base class for all designer glyphs used on a workflow design surface. - Activity designer developers can use classes that inherit from to draw custom glyphs onto the surface of an . classes draw such glyphs at the top-level Z order, which places the custom glyph visually on top of all other glyphs on the designer based on the value of the custom glyph. A lower value for the property indicates a higher priority and therefore draws the glyph at the top-most Z order position on an activity designer. + Activity designer developers can use classes that inherit from to draw custom glyphs onto the surface of an . classes draw such glyphs at the top-level Z order, which places the custom glyph visually on top of all other glyphs on the designer based on the value of the custom glyph. A lower value for the property indicates a higher priority and therefore draws the glyph at the top-most Z order position on an activity designer. ]]> @@ -143,10 +143,10 @@ property indicates a higher priority and therefore draws the glyph at the top-most Z order position on an activity designer. The value of the field is 0. + A lower value for the property indicates a higher priority and therefore draws the glyph at the top-most Z order position on an activity designer. The value of the field is 0. > [!NOTE] -> This constant value serves as a guideline when creating custom glyphs. You are free to use different values for the property when designing your custom glyph. +> This constant value serves as a guideline when creating custom glyphs. You are free to use different values for the property when designing your custom glyph. ]]> @@ -175,10 +175,10 @@ property indicates a lower priority and therefore draws the glyph at the bottom-most Z order position on an activity designer. The value of the field is 1000000. + A high value for the property indicates a lower priority and therefore draws the glyph at the bottom-most Z order position on an activity designer. The value of the field is 1000000. > [!NOTE] -> This constant value serves as a guideline when creating custom glyphs. You are free to use different values for the property when designing your custom glyph. +> This constant value serves as a guideline when creating custom glyphs. You are free to use different values for the property when designing your custom glyph. ]]> @@ -207,10 +207,10 @@ property indicates a higher priority whereas a higher value indicates a lower priority. The value of the field is 10000. + A lower value for the property indicates a higher priority whereas a higher value indicates a lower priority. The value of the field is 10000. > [!NOTE] -> This constant value serves as a guideline when creating custom glyphs. You are free to use different values for the property when designing your custom glyph. +> This constant value serves as a guideline when creating custom glyphs. You are free to use different values for the property when designing your custom glyph. ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/DesignerTheme.xml b/xml/System.Workflow.ComponentModel.Design/DesignerTheme.xml index d04c92d54fc..6c9eaefa087 100644 --- a/xml/System.Workflow.ComponentModel.Design/DesignerTheme.xml +++ b/xml/System.Workflow.ComponentModel.Design/DesignerTheme.xml @@ -35,17 +35,17 @@ Supplies base class implementation for all activity designer theme classes used in a workflow design-time environment. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - All classes that supply theme property settings to classes must inherit from the class. Designer themes provide a set of property values with which to display background and foreground colors and styles, fonts, and other style settings for the designer classes displayed on a workflow design surface. - - The class also inherits from . - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + All classes that supply theme property settings to classes must inherit from the class. Designer themes provide a set of property values with which to display background and foreground colors and styles, fonts, and other style settings for the designer classes displayed on a workflow design surface. + + The class also inherits from . + ]]> @@ -98,11 +98,11 @@ Gets or sets the unqualified name of the designer type to which the designer theme is applied. The name of the designer type to which the designer theme is applied. - property associates the designer theme with a designer by using the unqualified name of the designer type, while the property associates the designer theme with a designer type by using the of the designer. - + property associates the designer theme with a designer by using the unqualified name of the designer type, while the property associates the designer theme with a designer type by using the of the designer. + ]]> A user attempted a set operation when the property was set to . @@ -138,11 +138,11 @@ Gets the workflow theme that encapsulates the designer theme. The object associated with the . - property returns the object that the used during initialization. - + property returns the object that the used during initialization. + ]]> @@ -177,13 +177,13 @@ Gets or sets the type of the designer associated with the designer theme. A that represents the designer to be associated with the current designer theme. - property associates the designer theme with a designer type by using the of the designer, while the property associates the designer theme with a designer by using the unqualified name of the designer type. - - Possible values for this property include , , and any classes created by activity designer developers that inherit from . - + property associates the designer theme with a designer type by using the of the designer, while the property associates the designer theme with a designer by using the unqualified name of the designer type. + + Possible values for this property include , , and any classes created by activity designer developers that inherit from . + ]]> A user attempted a set operation when the property was set to . @@ -235,11 +235,11 @@ Allows the to attempt to free resources and perform other clean-up operations before it is reclaimed by garbage collection. - releases only unmanaged resources prior to garbage collection. - + releases only unmanaged resources prior to garbage collection. + ]]> @@ -264,11 +264,11 @@ Performs further initialization tasks beyond those performed by . - class provides no default behavior for this method. Classes that inherit from must provide their own logic for this method. - + class provides no default behavior for this method. Classes that inherit from must provide their own logic for this method. + ]]> @@ -296,13 +296,13 @@ The enumeration value that the designer theme should now use. Notifies the designer theme class that the ambient property settings for the designer have changed. - use this method to make necessary changes when the enumeration value changes from to or to . - - The enumeration determines where a designer theme obtains its ambient property settings. If the value is set, the designer theme class obtains its ambient settings from the property. If the value is set, the designer theme class obtains its ambient settings from the operating system on which the designer is installed. - + use this method to make necessary changes when the enumeration value changes from to or to . + + The enumeration determines where a designer theme obtains its ambient property settings. If the value is set, the designer theme class obtains its ambient settings from the property. If the value is set, the designer theme class obtains its ambient settings from the operating system on which the designer is installed. + ]]> @@ -338,13 +338,13 @@ if is read-only; otherwise, . The default is . - that the is initialized with is not a null reference (`Nothing` in Visual Basic), obtains its value from the property. If the is a null reference (`Nothing`), is `false`. - - If the is assigned to the , the property is set to `true`, and properties on all designer themes associated with this theme cannot be changed. If required, properties can be set after loading the theme but before assigning it to the . - + that the is initialized with is not a null reference (`Nothing` in Visual Basic), obtains its value from the property. If the is a null reference (`Nothing`), is `false`. + + If the is assigned to the , the property is set to `true`, and properties on all designer themes associated with this theme cannot be changed. If required, properties can be set after loading the theme but before assigning it to the . + ]]> @@ -372,11 +372,11 @@ Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. - interface. - + interface. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/DesignerView.xml b/xml/System.Workflow.ComponentModel.Design/DesignerView.xml index 92b00e3434d..f4b7e2be9a7 100644 --- a/xml/System.Workflow.ComponentModel.Design/DesignerView.xml +++ b/xml/System.Workflow.ComponentModel.Design/DesignerView.xml @@ -23,13 +23,13 @@ Serves as a repository for information about the views supported by the or classes that inherit from it. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + ]]> @@ -148,11 +148,11 @@ if and the current are equal; otherwise, . - uses the property to determine whether the compared designer views are equal. - + uses the property to determine whether the compared designer views are equal. + ]]> @@ -222,11 +222,11 @@ Notifies the designer when the view is activated. - has no default behavior; classes that inherit from must implement their own logic. - + has no default behavior; classes that inherit from must implement their own logic. + ]]> @@ -251,11 +251,11 @@ Notifies the designer when the view is deactivated. - has no default behavior; classes that inherit from must implement their own logic. - + has no default behavior; classes that inherit from must implement their own logic. + ]]> @@ -302,11 +302,11 @@ Gets the dictionary of user data associated with the designer view. An that contains the user data associated with the . - is `null`, a is created to hold the user data. - + is `null`, a is created to hold the user data. + ]]> @@ -331,11 +331,11 @@ Gets the identifier associated with the designer view. An integer that contains the identifier for the . - diff --git a/xml/System.Workflow.ComponentModel.Design/FreeformActivityDesigner.xml b/xml/System.Workflow.ComponentModel.Design/FreeformActivityDesigner.xml index 1e5d368718e..f05f89102ea 100644 --- a/xml/System.Workflow.ComponentModel.Design/FreeformActivityDesigner.xml +++ b/xml/System.Workflow.ComponentModel.Design/FreeformActivityDesigner.xml @@ -195,7 +195,7 @@ ## Remarks The default size of is a object with dimensions of 40 pixels by 40 pixels. - If the property associated with the current workflow theme is set to `true`, settings are half the height and half the width of the grid size. + If the property associated with the current workflow theme is set to `true`, settings are half the height and half the width of the grid size. When you set , the layout of the is updated. @@ -232,7 +232,7 @@ allows the to grow as necessary to fit its contents but does not shrink smaller than the value of the property. + The default behavior of allows the to grow as necessary to fit its contents but does not shrink smaller than the value of the property. When you set , the layout of the is updated. @@ -803,7 +803,7 @@ returns the last child designer in the property or a `null` reference (`Nothing` in Visual Basic) if the does not contain any child designers. + returns the last child designer in the property or a `null` reference (`Nothing` in Visual Basic) if the does not contain any child designers. ]]> @@ -1259,7 +1259,7 @@ always sets the property to an empty string and the property to `null` (`Nothing` in Visual Basic). + Unless overridden in a derived class, always sets the property to an empty string and the property to `null` (`Nothing` in Visual Basic). If is set to `true`, the locations of each child designer in the is snapped to the nearest grid line. diff --git a/xml/System.Workflow.ComponentModel.Design/HitTestInfo.xml b/xml/System.Workflow.ComponentModel.Design/HitTestInfo.xml index a866f66121c..dff61fef5ca 100644 --- a/xml/System.Workflow.ComponentModel.Design/HitTestInfo.xml +++ b/xml/System.Workflow.ComponentModel.Design/HitTestInfo.xml @@ -23,15 +23,15 @@ Contains information about a part of the at a specified coordinate. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - The class, in conjunction with the method of the is used to determine which part of an the user has clicked. The class contains the location and associated designer that was clicked. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + The class, in conjunction with the method of the is used to determine which part of an the user has clicked. The class contains the location and associated designer that was clicked. + ]]> @@ -86,11 +86,11 @@ Gets the associated with the class. The associated with the class. - property stores a reference to the associated with the object. Use the to reference extended information about the designer associated with the . - + property stores a reference to the associated with the object. Use the to reference extended information about the designer associated with the . + ]]> @@ -121,11 +121,11 @@ Returns the bounds of the area hit. A rectangle that encloses the associated with the object or an empty rectangle if the object is not associated with a designer. - . - + . + ]]> @@ -156,11 +156,11 @@ Contains information about where the hit occurred. A that describes the area hit. - to determine on what area of the designer the hit occurred. - + to determine on what area of the designer the hit occurred. + ]]> @@ -186,11 +186,11 @@ Returns the index of the hit designer. The index of the designer hit by the . - to determine which designer was hit. This is useful for insertion or deletion operations. - + to determine which designer was hit. This is useful for insertion or deletion operations. + ]]> @@ -215,11 +215,11 @@ Gets an empty . An empty . - . - + . + ]]> @@ -250,11 +250,11 @@ Gets a selectable object associated with the hit area. A selectable object associated with the hit area or a null reference ( in Visual Basic) if no designer is associated with the . - , will return the activity associated with the designer, or null reference (`Nothing`) if no designer is associated with the . - + , will return the activity associated with the designer, or null reference (`Nothing`) if no designer is associated with the . + ]]> @@ -285,11 +285,11 @@ Gets the user data associated with the . A new dictionary for user data, or a reference to the existing user data. - to store user information about the . If no user data has been stored, calling creates a new, empty dictionary for use. - + to store user information about the . If no user data has been stored, calling creates a new, empty dictionary for use. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/ITypeProviderCreator.xml b/xml/System.Workflow.ComponentModel.Design/ITypeProviderCreator.xml index ef2ba2af32e..23b0752e1dc 100644 --- a/xml/System.Workflow.ComponentModel.Design/ITypeProviderCreator.xml +++ b/xml/System.Workflow.ComponentModel.Design/ITypeProviderCreator.xml @@ -28,13 +28,13 @@ Defines a group of methods that classes can use to create a type provider for an activity or workflow designer. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + ]]> @@ -63,11 +63,11 @@ Returns the local assembly associated with the specified object. The associated with . - property. - + property. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/LockedActivityGlyph.xml b/xml/System.Workflow.ComponentModel.Design/LockedActivityGlyph.xml index c8a8763fa85..32594860a6d 100644 --- a/xml/System.Workflow.ComponentModel.Design/LockedActivityGlyph.xml +++ b/xml/System.Workflow.ComponentModel.Design/LockedActivityGlyph.xml @@ -23,15 +23,15 @@ Provides a glyph for an to display when the activity associated with the designer cannot be modified. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - An activity designer displays when the property is set to `true`. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + An activity designer displays when the property is set to `true`. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/ParallelActivityDesigner.xml b/xml/System.Workflow.ComponentModel.Design/ParallelActivityDesigner.xml index f6e3ab3a282..f97fc7c95c3 100644 --- a/xml/System.Workflow.ComponentModel.Design/ParallelActivityDesigner.xml +++ b/xml/System.Workflow.ComponentModel.Design/ParallelActivityDesigner.xml @@ -133,7 +133,7 @@ property or the property is set to `false`, returns a null reference (`Nothing` in Visual Basic). If the property count is greater than 0, returns the associated with the first activity designer in the collection. + If the designer's property or the property is set to `false`, returns a null reference (`Nothing` in Visual Basic). If the property count is greater than 0, returns the associated with the first activity designer in the collection. ]]> @@ -216,7 +216,7 @@ or property is set to `false`, returns a null reference (`Nothing` in Visual Basic). If contains child activity designers, returns the last selectable object associated with the first child activity designer. If the child activity designer is collapsed, returns the associated with the first activity designer in the collection. + If the designer's or property is set to `false`, returns a null reference (`Nothing` in Visual Basic). If contains child activity designers, returns the last selectable object associated with the first child activity designer. If the child activity designer is collapsed, returns the associated with the first activity designer in the collection. ]]> @@ -346,7 +346,7 @@ property determines the commands that are displayed on the context menu. + The property determines the commands that are displayed on the context menu. The verb collection includes any designer verbs inherits from the designer classes it extends. diff --git a/xml/System.Workflow.ComponentModel.Design/SequentialActivityDesigner.xml b/xml/System.Workflow.ComponentModel.Design/SequentialActivityDesigner.xml index 831539b4712..154de0f8257 100644 --- a/xml/System.Workflow.ComponentModel.Design/SequentialActivityDesigner.xml +++ b/xml/System.Workflow.ComponentModel.Design/SequentialActivityDesigner.xml @@ -23,15 +23,15 @@ Defines properties and methods for all activity designers that have a sequential vertical layout on the workflow design surface. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - The and classes that inherit from it can contain child activity designers. Their appearance on the workflow design surface is organized vertically, with child activities displayed on the surface of the . - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + The and classes that inherit from it can contain child activity designers. Their appearance on the workflow design surface is organized vertically, with child activities displayed on the surface of the . + ]]> @@ -74,11 +74,11 @@ Gets an that allows the to adjust its UI for users who have disabilities. The to associate with the designer. - is a null reference (`Nothing` in Visual Basic), the creates an . - + is a null reference (`Nothing` in Visual Basic), the creates an . + ]]> @@ -104,13 +104,13 @@ if the designer can be expanded and collapsed on the workflow design surface; otherwise, . The default is . - returns `true`, the designer renders an expand-collapse button on the workflow design surface. - - If the parent designer of the is , returns `false`. Additionally, if the is the root designer, returns `false`. - + returns `true`, the designer renders an expand-collapse button on the workflow design surface. + + If the parent designer of the is , returns `false`. Additionally, if the is the root designer, returns `false`. + ]]> @@ -181,11 +181,11 @@ Returns an array of rectangles that bound the activity designer's connectors. The array that bounds the connectors. - returns an empty array. If there are no activity designers in the parent designer, returns an array of one rectangle. - + returns an empty array. If there are no activity designers in the parent designer, returns an array of one rectangle. + ]]> @@ -286,11 +286,11 @@ Gets or sets the text to display when the contains no other activity designers. A string that contains the text to display on the designer surface. - property value is displayed on the surface when it contains no child activity designers. - + property value is displayed on the surface when it contains no child activity designers. + ]]> @@ -363,11 +363,11 @@ Returns information about the at the specified point on the workflow design surface. A that contains information about the . - is based on the point on the workflow design surface that was passed to it. It includes the activity designer associated with the point, the bounds of that activity designer, the exact hit location of the point, any selectable objects associated with the point, and any user data associated with the point. - + is based on the point on the workflow design surface that was passed to it. It includes the activity designer associated with the point, the bounds of that activity designer, the exact hit location of the point, any selectable objects associated with the point, and any user data associated with the point. + ]]> @@ -395,11 +395,11 @@ The with which to initialize the . Initializes the designer by using the specified activity. - assigns a value for the property that is displayed on the if it does not contain any child designers. - + assigns a value for the property that is displayed on the if it does not contain any child designers. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/SequentialWorkflowRootDesigner.xml b/xml/System.Workflow.ComponentModel.Design/SequentialWorkflowRootDesigner.xml index 194299a7806..f65ad0f143e 100644 --- a/xml/System.Workflow.ComponentModel.Design/SequentialWorkflowRootDesigner.xml +++ b/xml/System.Workflow.ComponentModel.Design/SequentialWorkflowRootDesigner.xml @@ -254,7 +254,7 @@ property is set to the to display. You can do this at design time or at run time. + property is set to the to display. You can do this at design time or at run time. Unless overridden in a derived class, returns a null reference (`Nothing` in Visual Basic). @@ -463,7 +463,7 @@ property is not set to a null reference (`Nothing` in Visual Basic) and the corresponding property is not an empty string or set to a null reference (`Nothing`), returns `true`. + If the property is not set to a null reference (`Nothing` in Visual Basic) and the corresponding property is not an empty string or set to a null reference (`Nothing`), returns `true`. ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/ShadowGlyph.xml b/xml/System.Workflow.ComponentModel.Design/ShadowGlyph.xml index 28923218894..b02add4664a 100644 --- a/xml/System.Workflow.ComponentModel.Design/ShadowGlyph.xml +++ b/xml/System.Workflow.ComponentModel.Design/ShadowGlyph.xml @@ -23,15 +23,15 @@ Provides a drop shadow for display by classes. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - A displays a if the property is set to `true`. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + A displays a if the property is set to `true`. + ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/StructuredCompositeActivityDesigner.xml b/xml/System.Workflow.ComponentModel.Design/StructuredCompositeActivityDesigner.xml index 408c4762212..4274c701231 100644 --- a/xml/System.Workflow.ComponentModel.Design/StructuredCompositeActivityDesigner.xml +++ b/xml/System.Workflow.ComponentModel.Design/StructuredCompositeActivityDesigner.xml @@ -277,7 +277,7 @@ returns the associated with the property that is exposed through . + returns the associated with the property that is exposed through . ]]> @@ -863,7 +863,7 @@ hosts multiple views. Use the property to determine how many views the current designer hosts. + The collection is returned only if the hosts multiple views. Use the property to determine how many views the current designer hosts. ]]> diff --git a/xml/System.Workflow.ComponentModel.Design/TypeFilterProviderAttribute.xml b/xml/System.Workflow.ComponentModel.Design/TypeFilterProviderAttribute.xml index 7fe782934d8..cb164137d9a 100644 --- a/xml/System.Workflow.ComponentModel.Design/TypeFilterProviderAttribute.xml +++ b/xml/System.Workflow.ComponentModel.Design/TypeFilterProviderAttribute.xml @@ -27,19 +27,19 @@ Specifies the class a type or member uses to filter the types that are displayed in the class browser dialog box. This class cannot be inherited. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - The class you use to filter the types to display in the class browser dialog box must implement . - - Use the property to determine the name of the filter class. - - For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + The class you use to filter the types to display in the class browser dialog box must implement . + + Use the property to determine the name of the filter class. + + For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). + ]]> diff --git a/xml/System.Workflow.ComponentModel.Serialization/ActivityCodeDomSerializationManager.xml b/xml/System.Workflow.ComponentModel.Serialization/ActivityCodeDomSerializationManager.xml index 26d7b2ac9a6..3897951e0b1 100644 --- a/xml/System.Workflow.ComponentModel.Serialization/ActivityCodeDomSerializationManager.xml +++ b/xml/System.Workflow.ComponentModel.Serialization/ActivityCodeDomSerializationManager.xml @@ -30,13 +30,13 @@ Manages serialization of activities into designer-generated source code segments before compilation. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + ]]> @@ -114,11 +114,11 @@ Gets the associated with . The associated with the . - to provide information to a nested . - + to provide information to a nested . + ]]> @@ -151,21 +151,21 @@ The data to create. An of arguments to pass to the constructor for the specified type. - The name assigned to the resulting object. This name can be used to access the object later through . - + The name assigned to the resulting object. This name can be used to access the object later through . + If null is passed, the object is created but cannot be accessed by name. - to add the object to the design container; otherwise, . - + to add the object to the design container; otherwise, . + The object must implement for this to have any effect. Creates an instance of the specified type and adds it to a collection of named instances. The newly created object instance. - method of the same name. - + method of the same name. + ]]> @@ -197,11 +197,11 @@ Gets an of the specified name, or null if that does not exist. An of the specified name, or null if that does not exist. - method of the same name. - + method of the same name. + ]]> @@ -233,13 +233,13 @@ Gets the name of the specified , or null if the has no name. A that contains the name of the . - is called. - - If the activity has no parent, then the activity qualified ID is returned with any periods (.) replaced by underscores (_). - + is called. + + If the activity has no parent, then the activity qualified ID is returned with any periods (.) replaced by underscores (_). + ]]> @@ -273,11 +273,11 @@ Gets a serializer of the requested type for the specified type. A serializer of the requested type for the specified type. - is invoked. - + is invoked. + ]]> @@ -338,11 +338,11 @@ Gets a of the specified name. An instance of the , or a null reference ( in Visual Basic) if the cannot be loaded. - provides an indirect reference to the property of the same name. - + provides an indirect reference to the property of the same name. + ]]> @@ -370,13 +370,13 @@ Gets a that contains a read-only collection of type . A that contains a read-only collection of type . - class, you can query about its contents. Use the property to determine the number of elements in the collection. Use the property to obtain a specific property by index number or by name. - - In addition to properties, you can use the method to obtain a description of the property that uses the specified name from the collection. - + class, you can query about its contents. Use the property to determine the number of elements in the collection. Use the property to obtain a specific property by index number or by name. + + In addition to properties, you can use the method to obtain a description of the property that uses the specified name from the collection. + ]]> @@ -407,13 +407,13 @@ The provider to remove. Removes a custom serialization provider from the serialization manager. - . - - provides an indirect reference to the property of the same name. - + . + + provides an indirect reference to the property of the same name. + ]]> @@ -444,15 +444,15 @@ An that contains the error to report. Reports an error in serialization. - - - is called to display the information to the user. - - provides an indirect reference to the method of the same name. - + + + is called to display the information to the user. + + provides an indirect reference to the method of the same name. + ]]> @@ -479,11 +479,11 @@ Occurs when cannot locate the specified name in the serialization manager name table. - @@ -510,11 +510,11 @@ Occurs when serialization is complete. - @@ -539,11 +539,11 @@ Gets the associated with the . The associated with the . - @@ -576,13 +576,13 @@ A that contains the name to give the instance. Sets the name of the specified existing . - provides an indirect reference to the method of the same name. - - An exception is thrown if you try to rename an existing object or if you try to give a new object a name that is already taken. In addition, an exception is thrown if you do not pass in an existing object to the method. - + provides an indirect reference to the method of the same name. + + An exception is thrown if you try to rename an existing object or if you try to give a new object a name that is already taken. In addition, an exception is thrown if you do not pass in an existing object to the method. + ]]> diff --git a/xml/System.Workflow.ComponentModel/ActivityCollection.xml b/xml/System.Workflow.ComponentModel/ActivityCollection.xml index 1dfa85c414f..0a45c5e8522 100644 --- a/xml/System.Workflow.ComponentModel/ActivityCollection.xml +++ b/xml/System.Workflow.ComponentModel/ActivityCollection.xml @@ -578,7 +578,7 @@ property is zero after this operation is finished. + The property is zero after this operation is finished. ]]> @@ -1052,7 +1052,7 @@ property. + For collections whose underlying store is not publicly available, the expected implementation is to return the current instance. Note that the pointer to the current instance might not be sufficient for collections that wrap other collections; those should return the underlying collection property. Most collection classes in the namespace also implement a `Synchronized` method, which provides a synchronized wrapper around the underlying collection. However, derived classes can provide their own synchronized version of the collection using the property. The synchronizing code must perform operations on the property of the collection, not directly on the collection. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the collection instance. diff --git a/xml/System.Workflow.ComponentModel/GetValueOverride.xml b/xml/System.Workflow.ComponentModel/GetValueOverride.xml index 46dde4d19da..2fefc768d8c 100644 --- a/xml/System.Workflow.ComponentModel/GetValueOverride.xml +++ b/xml/System.Workflow.ComponentModel/GetValueOverride.xml @@ -24,15 +24,15 @@ Allows a custom override of the logic associated with a dependency property that is defined on a dependency object. An that represents the value of the designated . - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - The implementation of this delegate can be set on the property of while calling or . - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + The implementation of this delegate can be set on the property of while calling or . + ]]> diff --git a/xml/System.Workflow.ComponentModel/SetValueOverride.xml b/xml/System.Workflow.ComponentModel/SetValueOverride.xml index e6a94793f86..05117d0b917 100644 --- a/xml/System.Workflow.ComponentModel/SetValueOverride.xml +++ b/xml/System.Workflow.ComponentModel/SetValueOverride.xml @@ -25,15 +25,15 @@ The to set the value to. Allows a custom override of the logic associated with a dependency property that is defined on a dependency object. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - The implementation of this delegate can be set to the property of while calling or . - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + The implementation of this delegate can be set to the property of while calling or . + ]]> diff --git a/xml/System.Workflow.ComponentModel/TerminateActivity.xml b/xml/System.Workflow.ComponentModel/TerminateActivity.xml index d26f6c8aa22..7e0d9ca6a4c 100644 --- a/xml/System.Workflow.ComponentModel/TerminateActivity.xml +++ b/xml/System.Workflow.ComponentModel/TerminateActivity.xml @@ -136,7 +136,7 @@ property is set to `false`) a is thrown. + If this property is set when the activity is in runtime mode (the property is set to `false`) a is thrown. Propagation of this error message is determined by the host (the instance manager or the persistence provider). diff --git a/xml/System.Workflow.Runtime.Hosting/WorkflowCommitWorkBatchService.xml b/xml/System.Workflow.Runtime.Hosting/WorkflowCommitWorkBatchService.xml index 9a192a1b4da..ac3bc85d44c 100644 --- a/xml/System.Workflow.Runtime.Hosting/WorkflowCommitWorkBatchService.xml +++ b/xml/System.Workflow.Runtime.Hosting/WorkflowCommitWorkBatchService.xml @@ -32,7 +32,7 @@ When a work batch is committed the runtime calls into the and gives it a delegate to call to do the actual committing of the work batch. The runtime still has the primary responsibility of committing the work batch but allows the to insert itself in the process for customization around the commit process. - This process allows custom error handling logic. If the owns the transaction, which is the case when the property returns `null` therefore necessitating the need to create a new ambient transaction, it is allowed to call the delegate more than once, creating a new transaction for each call. The most common case for this for example is to handle intermittent network problems or SQL cluster failovers. If the call to the throws an exception can catch this exception, start a new transaction and call the delegate again. This gives a level of resilience to workflow instance execution that otherwise would cause workflows to terminate. + This process allows custom error handling logic. If the owns the transaction, which is the case when the property returns `null` therefore necessitating the need to create a new ambient transaction, it is allowed to call the delegate more than once, creating a new transaction for each call. The most common case for this for example is to handle intermittent network problems or SQL cluster failovers. If the call to the throws an exception can catch this exception, start a new transaction and call the delegate again. This gives a level of resilience to workflow instance execution that otherwise would cause workflows to terminate. ]]> diff --git a/xml/System.Workflow.Runtime.Hosting/WorkflowPersistenceService.xml b/xml/System.Workflow.Runtime.Hosting/WorkflowPersistenceService.xml index 2d15a49691c..fa6efb4632a 100644 --- a/xml/System.Workflow.Runtime.Hosting/WorkflowPersistenceService.xml +++ b/xml/System.Workflow.Runtime.Hosting/WorkflowPersistenceService.xml @@ -295,11 +295,11 @@ ## Remarks The workflow runtime engine saves the state of completed scope activities in order to implement compensation. You must call one of the overloaded methods to serialize `activity` into a ; you may then choose to additionally process the before writing it to your data store. However, when the workflow runtime engine calls , you must restore an identical copy of the activity. - You must be able to associate the completed scope with its enclosing workflow instance to mark the scope as unneeded in your data store when the workflow instance finishes or is terminated. Therefore, you should also save the of the workflow instance that is associated with the completed scope; this can be obtained from the property of the associated with `activity`. + You must be able to associate the completed scope with its enclosing workflow instance to mark the scope as unneeded in your data store when the workflow instance finishes or is terminated. Therefore, you should also save the of the workflow instance that is associated with the completed scope; this can be obtained from the property of the associated with `activity`. - takes the of the completed scope as a parameter. Therefore, you must also save the property associated with `activity`. This property can be referenced through the field of `activity`. + takes the of the completed scope as a parameter. Therefore, you must also save the property associated with `activity`. This property can be referenced through the field of `activity`. - If you are implementing a persistence service that uses a durable store, to maintain consistency with the internal state of the workflow runtime engine, you should participate in workflow transaction batching to defer the actual write to your durable store until a workflow commit point. To participate in batching, add a work item to the property that represents the pending changes to the database, and implement the interface in your persistence service. + If you are implementing a persistence service that uses a durable store, to maintain consistency with the internal state of the workflow runtime engine, you should participate in workflow transaction batching to defer the actual write to your durable store until a workflow commit point. To participate in batching, add a work item to the property that represents the pending changes to the database, and implement the interface in your persistence service. If you cannot save the completed scope to your data store, you should throw a with an appropriate error message. @@ -344,7 +344,7 @@ The workflow runtime engine calls a final time when the workflow instance is completed or terminated. Therefore, if is equal to or , you can safely delete the workflow instance and all its associated completed scopes from your data store. Alternatively, you can subscribe to the or events to determine when it is safe to delete records associated with the workflow instance. Whether you actually delete the records from your data store depends on your implementation. - If you implement a persistence service that uses a durable store, then, to maintain consistency with the internal state of the workflow runtime engine, you should participate in workflow transaction batching to defer the actual write to your durable store until a workflow commit point. To participate in batching, add a work item that represents the pending changes to your durable store to the property, and implement the interface in your persistence service. + If you implement a persistence service that uses a durable store, then, to maintain consistency with the internal state of the workflow runtime engine, you should participate in workflow transaction batching to defer the actual write to your durable store until a workflow commit point. To participate in batching, add a work item that represents the pending changes to your durable store to the property, and implement the interface in your persistence service. ]]> diff --git a/xml/System.Workflow.Runtime.Tracking/ActivityTrackPoint.xml b/xml/System.Workflow.Runtime.Tracking/ActivityTrackPoint.xml index ee6ae54f19a..70beecf94d6 100644 --- a/xml/System.Workflow.Runtime.Tracking/ActivityTrackPoint.xml +++ b/xml/System.Workflow.Runtime.Tracking/ActivityTrackPoint.xml @@ -123,7 +123,7 @@ ## Remarks If any in is matched for a particular activity status event, the track point will not be matched and no will be sent to the tracking service. If is empty, there are no excluded locations. - You can use to specifically exclude locations from being tracked by the runtime tracking infrastructure. For example, if you want to track all activities except the activity with an property of "Code1", you can define an that matches all activities and add it to . Then you can define another that matches activities with an property set to "Code1" and add it to . The track point will then match all activities except the "Code1" activity. + You can use to specifically exclude locations from being tracked by the runtime tracking infrastructure. For example, if you want to track all activities except the activity with an property of "Code1", you can define an that matches all activities and add it to . Then you can define another that matches activities with an property set to "Code1" and add it to . The track point will then match all activities except the "Code1" activity. ]]> diff --git a/xml/System.Workflow.Runtime.Tracking/ActivityTrackingLocation.xml b/xml/System.Workflow.Runtime.Tracking/ActivityTrackingLocation.xml index 76af3c5756c..2137f8732e2 100644 --- a/xml/System.Workflow.Runtime.Tracking/ActivityTrackingLocation.xml +++ b/xml/System.Workflow.Runtime.Tracking/ActivityTrackingLocation.xml @@ -454,7 +454,7 @@ to more precisely define the instance of the reference activity type to be matched. For example, if you want to match only activities with an equal to "MyCode", you can set to"CodeActivity" and add an to that specifies that the property of the activity instance must be equal to "MyCode". + You can use to more precisely define the instance of the reference activity type to be matched. For example, if you want to match only activities with an equal to "MyCode", you can set to"CodeActivity" and add an to that specifies that the property of the activity instance must be equal to "MyCode". Every in must be `true` and one of the values in must be matched for the to be matched. diff --git a/xml/System.Workflow.Runtime.Tracking/SqlTrackingQuery.xml b/xml/System.Workflow.Runtime.Tracking/SqlTrackingQuery.xml index 4769b3f2b69..88fb2d871d6 100644 --- a/xml/System.Workflow.Runtime.Tracking/SqlTrackingQuery.xml +++ b/xml/System.Workflow.Runtime.Tracking/SqlTrackingQuery.xml @@ -93,7 +93,7 @@ property is initialized to `connectionString`. + The property is initialized to `connectionString`. ]]> diff --git a/xml/System.Workflow.Runtime.Tracking/SqlTrackingQueryOptions.xml b/xml/System.Workflow.Runtime.Tracking/SqlTrackingQueryOptions.xml index 212a3f8bfee..6e73a99f330 100644 --- a/xml/System.Workflow.Runtime.Tracking/SqlTrackingQueryOptions.xml +++ b/xml/System.Workflow.Runtime.Tracking/SqlTrackingQueryOptions.xml @@ -135,7 +135,7 @@ ## Remarks constrains the set of objects returned by a call to to those workflow instances that have the specified by , that have the status specified by during the period specified by and , and that have extracted data that matches at least one of the objects specified by . - The value specified by is inclusive. For more information about how the status of a workflow instance is matched, see the property. + The value specified by is inclusive. For more information about how the status of a workflow instance is matched, see the property. > [!NOTE] > If `WorkflowStatus` is set to null, then `StatusMaxDateTime` and `StatusMinDateTime` are ignored. All workflow instances will be returned when `GetWorkflows` is called. @@ -169,7 +169,7 @@ ## Remarks constrains the set of objects returned by a call to to those workflow instances that have the specified by , that have the status specified by during the period specified by and , and that have extracted data that matches at least one of the objects specified by . - The value specified by is inclusive. For more information about how the status of a workflow instance is matched, see the property. + The value specified by is inclusive. For more information about how the status of a workflow instance is matched, see the property. > [!NOTE] > If `WorkflowStatus` is set to null, then `StatusMaxDateTime` and `StatusMinDateTime` are ignored. All workflow instances will be returned when `GetWorkflows` is called. @@ -203,7 +203,7 @@ ## Remarks constrains the set of objects returned by a call to to those workflow instances that have the specified by , that have the status specified by during the period specified by and , and that have extracted data that matches at least one of the objects specified by . - or can contain records that contain data that is extracted from the workflow. The property contains objects that specify certain values for this extracted data. If the workflow instance meets the other criteria specified by and is not a null reference (`Nothing`), the extracted data stored in the database for a workflow instance must match one or more of the extracted data values specified by the property for a object to be returned for the workflow instance. + or can contain records that contain data that is extracted from the workflow. The property contains objects that specify certain values for this extracted data. If the workflow instance meets the other criteria specified by and is not a null reference (`Nothing`), the extracted data stored in the database for a workflow instance must match one or more of the extracted data values specified by the property for a object to be returned for the workflow instance. If is a null reference (`Nothing`), the set of objects returned will not be constrained by the values of the extracted data for any of the workflow instances in the database. @@ -236,7 +236,7 @@ ## Remarks constrains the set of objects returned by a call to to those workflow instances that have the specified by , that have the status specified by during the period specified by and , and that have extracted data that matches at least one of the objects specified by . - A workflow instance is considered to have a status that matches if the last received for that workflow instance before or during the specified time period has its property set to a value that maps to the value specified by . Therefore, the for the workflow instance must have a that is configured for the appropriate value. Only values that have been sent in workflow tracking records can be matched. If no workflow tracking records have been sent for the workflow instance, the workflow instance is considered to have a status of . + A workflow instance is considered to have a status that matches if the last received for that workflow instance before or during the specified time period has its property set to a value that maps to the value specified by . Therefore, the for the workflow instance must have a that is configured for the appropriate value. Only values that have been sent in workflow tracking records can be matched. If no workflow tracking records have been sent for the workflow instance, the workflow instance is considered to have a status of . The following table shows the mapping between values and values. diff --git a/xml/System.Workflow.Runtime.Tracking/SqlTrackingService.xml b/xml/System.Workflow.Runtime.Tracking/SqlTrackingService.xml index a8afb85f87e..b84e94adcbf 100644 --- a/xml/System.Workflow.Runtime.Tracking/SqlTrackingService.xml +++ b/xml/System.Workflow.Runtime.Tracking/SqlTrackingService.xml @@ -167,11 +167,11 @@ property is set to `false` and is set to `true`, then all transaction retries depend on the value of the property. + If the property is set to `false` and is set to `true`, then all transaction retries depend on the value of the property. If is set to `true`, then certain work is batched and retries of those work batch transactions are handled by a derived type of , such as or . - Regardless of whether is set to `true`, the following work items cannot be batched and any transaction retries must be handled through the property. + Regardless of whether is set to `true`, the following work items cannot be batched and any transaction retries must be handled through the property. - Polling for tracking profile changes. diff --git a/xml/System.Workflow.Runtime.Tracking/TrackingDataItem.xml b/xml/System.Workflow.Runtime.Tracking/TrackingDataItem.xml index 718720e75c0..5d32b4da3a7 100644 --- a/xml/System.Workflow.Runtime.Tracking/TrackingDataItem.xml +++ b/xml/System.Workflow.Runtime.Tracking/TrackingDataItem.xml @@ -23,15 +23,15 @@ Represents a single item of data extracted from a workflow and all its associated annotations. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - When the runtime tracking infrastructure matches a track point, it sends a tracking record to the tracking service. An or a may contain or objects that specify data to be extracted from the workflow and returned in the or the . A represents a single item of this extracted data in either or . - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + When the runtime tracking infrastructure matches a track point, it sends a tracking record to the tracking service. An or a may contain or objects that specify data to be extracted from the workflow and returned in the or the . A represents a single item of this extracted data in either or . + ]]> @@ -74,11 +74,11 @@ Gets or sets the list of annotations associated with the extracted data. A that contains the annotations associated with the extracted data. - or a can specify annotations to be sent with the extracted data. These are contained in the property. - + or a can specify annotations to be sent with the extracted data. These are contained in the property. + ]]> @@ -103,11 +103,11 @@ Gets or sets the extracted data associated with the . An that represents the extracted data. - contains the member data, specified by an or a , that was extracted from the workflow instance. - + contains the member data, specified by an or a , that was extracted from the workflow instance. + ]]> @@ -132,11 +132,11 @@ Gets or sets the name of the property or field associated with the extracted data. The dot delineated name of the property or field that was extracted. - ; a member of such a field or property; and a single item of a field or a property (or a member of either) that implements the interface, for example a single element in a collection. contains the dot delineated name of the item extracted and is equivalent to or depending on which type of extract specified the data contained by the . - + ; a member of such a field or property; and a single item of a field or a property (or a member of either) that implements the interface, for example a single element in a collection. contains the dot delineated name of the item extracted and is equivalent to or depending on which type of extract specified the data contained by the . + ]]> diff --git a/xml/System.Workflow.Runtime.Tracking/TrackingDataItemValue.xml b/xml/System.Workflow.Runtime.Tracking/TrackingDataItemValue.xml index 1bf5511d95f..f78ffff2838 100644 --- a/xml/System.Workflow.Runtime.Tracking/TrackingDataItemValue.xml +++ b/xml/System.Workflow.Runtime.Tracking/TrackingDataItemValue.xml @@ -184,7 +184,7 @@ is equivalent to the property of the activity from which the data was extracted. + is equivalent to the property of the activity from which the data was extracted. ]]> diff --git a/xml/System.Workflow.Runtime.Tracking/TrackingProfile.xml b/xml/System.Workflow.Runtime.Tracking/TrackingProfile.xml index 8e40f557802..ee5179b3a14 100644 --- a/xml/System.Workflow.Runtime.Tracking/TrackingProfile.xml +++ b/xml/System.Workflow.Runtime.Tracking/TrackingProfile.xml @@ -34,11 +34,11 @@ > [!NOTE] > [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - During its run time, a workflow instance emits tracking events to the runtime tracking infrastructure. The runtime tracking infrastructure uses a to filter these tracking events and returns tracking records based on this filtering to a tracking service. There are three kinds of tracking events that can be filtered: activity status events, workflow status events, and user events. You can add objects to the property to match specific activity status events; objects to the property to match specific workflow status events; and objects to the property to match specific user events. When a track point is matched, the runtime tracking infrastructure returns the data associated with the tracking event to the tracking service over the associated with that service. The data is returned in either an , a , or a depending on the type of track point that was matched. + During its run time, a workflow instance emits tracking events to the runtime tracking infrastructure. The runtime tracking infrastructure uses a to filter these tracking events and returns tracking records based on this filtering to a tracking service. There are three kinds of tracking events that can be filtered: activity status events, workflow status events, and user events. You can add objects to the property to match specific activity status events; objects to the property to match specific workflow status events; and objects to the property to match specific user events. When a track point is matched, the runtime tracking infrastructure returns the data associated with the tracking event to the tracking service over the associated with that service. The data is returned in either an , a , or a depending on the type of track point that was matched. A tracking service implements the methods in the abstract class to provide the functionality for the runtime tracking infrastructure to request a associated with the service, and a associated with a particular workflow instance or with a particular workflow type. A tracking service must also implement the abstract class to provide the channel over which the runtime tracking infrastructure can send tracking records. - When the tracking service returns a tracking profile object to the runtime, the workflow starts to execute, and the tracking profile is serialized. If the serialization of the tracking profile fails, an exception is raised to the workflow instance. If the exception is not handled, the workflow instance is terminated. The tracking profile can be validated before passing it to the runtime using the property. + When the tracking service returns a tracking profile object to the runtime, the workflow starts to execute, and the tracking profile is serialized. If the serialization of the tracking profile fails, an exception is raised to the workflow instance. If the exception is not handled, the workflow instance is terminated. The tracking profile can be validated before passing it to the runtime using the property. A can be serialized to XML by using the , which formats the XML according to the . This provides a convenient format for profile storage and for authoring a profile in a non-programmatic manner. For example, the SQL Tracking Service stores serialized versions of its tracking profiles, as will any tracking service you create based on the class. @@ -94,7 +94,7 @@ of an activity instance changes. The runtime tracking infrastructure uses the property to filter these activity status events to determine when to send an to the tracking service. You can add an to the property to specify points of interest in the potential execution path of the workflow instance for which you want the runtime infrastructure to send an . + A workflow instance emits activity status events to the runtime tracking infrastructure whenever the of an activity instance changes. The runtime tracking infrastructure uses the property to filter these activity status events to determine when to send an to the tracking service. You can add an to the property to specify points of interest in the potential execution path of the workflow instance for which you want the runtime infrastructure to send an . An does not actually define a physical point in a workflow instance, but instead defines a set of match parameters that can be used by the runtime tracking infrastructure to match an activity status event for which it should send an . Therefore, the same can be matched many times during the lifespan of a workflow instance. An can also specify data to be extracted from the workflow instance and returned in the . @@ -125,7 +125,7 @@ , , , or to instrument a workflow or an activity to emit data to the runtime tracking infrastructure at specific points during the execution of a workflow. Such an occurrence is called a user event and the data emitted is called user data. The runtime tracking infrastructure uses the property to filter user events to determine when to send a to the tracking service. You can add a to the property to specify points of interest in the potential execution path of the workflow instance for which you want a sent. + A workflow designer or an activity designer can use , , , or to instrument a workflow or an activity to emit data to the runtime tracking infrastructure at specific points during the execution of a workflow. Such an occurrence is called a user event and the data emitted is called user data. The runtime tracking infrastructure uses the property to filter user events to determine when to send a to the tracking service. You can add a to the property to specify points of interest in the potential execution path of the workflow instance for which you want a sent. A does not actually define a physical point in a workflow instance, but instead defines a set of match parameters that can be used by the runtime tracking infrastructure to match user events. Therefore, the same can be matched many times during the lifespan of a workflow instance. The runtime tracking infrastructure always returns the user data associated with a matched in the , but a can also specify data to be extracted from the workflow instance and returned in the tracking record. @@ -185,7 +185,7 @@ occurs indicating that the status of a workflow instance has changed. The runtime tracking infrastructure uses the property to filter these workflow status events to determine when to send a to the tracking service. You can add a to the property to specify points of interest in the potential execution path of the workflow instance for which you want a sent. + A workflow instance emits workflow status events to the runtime tracking infrastructure whenever a occurs indicating that the status of a workflow instance has changed. The runtime tracking infrastructure uses the property to filter these workflow status events to determine when to send a to the tracking service. You can add a to the property to specify points of interest in the potential execution path of the workflow instance for which you want a sent. A does not actually define a physical point in a workflow instance, but instead defines one or more values that can be used by the runtime tracking infrastructure to match workflow status events. Therefore, the same can be matched many times during the lifespan of a workflow instance. A can also specify any annotations to be returned in the . diff --git a/xml/System.Workflow.Runtime.Tracking/TrackingProfileDeserializationException.xml b/xml/System.Workflow.Runtime.Tracking/TrackingProfileDeserializationException.xml index 49085bc957b..ce5caba2908 100644 --- a/xml/System.Workflow.Runtime.Tracking/TrackingProfileDeserializationException.xml +++ b/xml/System.Workflow.Runtime.Tracking/TrackingProfileDeserializationException.xml @@ -27,15 +27,15 @@ The exception that is thrown when an XML document cannot be deserialized into a by a . - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - When the throws this exception it supplies a message that describes the reason for the exception. In some cases the supplies a list of validation errors and warnings that it encountered while trying to deserialize the . The property contains this list if it is supplied. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + When the throws this exception it supplies a message that describes the reason for the exception. In some cases the supplies a list of validation errors and warnings that it encountered while trying to deserialize the . The property contains this list if it is supplied. + ]]> @@ -65,19 +65,19 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error and takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic)| -||A system-supplied localized description.| -||An empty .| - + property of the new instance to a system-supplied message that describes the error and takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic)| +||A system-supplied localized description.| +||An empty .| + ]]> @@ -102,19 +102,19 @@ The message that describes the error. Initializes a new instance of the class with a specified error message. - . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic)| -||The error message string.| -||An empty .| - + . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic)| +||The error message string.| +||An empty .| + ]]> @@ -141,19 +141,19 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a catch 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 supplied to the constructor or a null reference (Nothing in Visual Basic) if the `innerException` parameter 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.| -||An empty .| - + property. The property returns the same value that is supplied to the constructor or a null reference (Nothing in Visual Basic) if the `innerException` parameter 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.| +||An empty .| + ]]> @@ -183,13 +183,13 @@ A that contains contextual information about the source or destination. Sets the object with the collection of associated with this exception, and additional exception information. - sets a with all the exception object data targeted for serialization. During deserialization the exception object is reconstituted from the transmitted over the stream. - - For more information see XML and SOAP Serialization. - + sets a with all the exception object data targeted for serialization. During deserialization the exception object is reconstituted from the transmitted over the stream. + + For more information see XML and SOAP Serialization. + ]]> @@ -216,11 +216,11 @@ Gets a list that contains validation warnings and errors associated with this exception. A of objects that contains validation warnings and errors associated with this exception. The default is an empty list. - uses an to deserialize an XML document into a . The collects validation errors and warnings emitted by the . At certain points during deserialization, the determines whether the has encountered any validation errors, and, if it has, the adds these warnings and errors to and throws a . Not all exceptions of this class will have set. - + uses an to deserialize an XML document into a . The collects validation errors and warnings emitted by the . At certain points during deserialization, the determines whether the has encountered any validation errors, and, if it has, the adds these warnings and errors to and throws a . Not all exceptions of this class will have set. + ]]> diff --git a/xml/System.Workflow.Runtime.Tracking/TrackingProfileSerializer.xml b/xml/System.Workflow.Runtime.Tracking/TrackingProfileSerializer.xml index a479b0b1ab0..3957b21037c 100644 --- a/xml/System.Workflow.Runtime.Tracking/TrackingProfileSerializer.xml +++ b/xml/System.Workflow.Runtime.Tracking/TrackingProfileSerializer.xml @@ -86,7 +86,7 @@ Deserialization refers to the process of creating an object from a well-formed XML document. uses the tracking profile XSD contained in to deserialize the XML document that is contained in the text reader into a valid . Validation on the XML document is performed during deserialization, and, if the document is not valid, a is thrown. You can catch this exception and examine to determine the cause of the validation error. If there are any unhandled exceptions while deserializing the tracking profile then the workflow instance for which the tracking profile was requested will be terminated. > [!NOTE] -> If you want to perform validation without deserializing the XML representation of a tracking profile, you can write your own tracking profile validator. See the property for more information. +> If you want to perform validation without deserializing the XML representation of a tracking profile, you can write your own tracking profile validator. See the property for more information. ]]> diff --git a/xml/System.Workflow.Runtime.Tracking/TrackingRecord.xml b/xml/System.Workflow.Runtime.Tracking/TrackingRecord.xml index 34cd7c67a5e..ba733b24bee 100644 --- a/xml/System.Workflow.Runtime.Tracking/TrackingRecord.xml +++ b/xml/System.Workflow.Runtime.Tracking/TrackingRecord.xml @@ -23,15 +23,15 @@ The base class from which , , and are derived. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - During its execution, a workflow instance emits three kinds of tracking events to the runtime tracking infrastructure: activity status events, user events, and workflow status events. The runtime tracking infrastructure tries to match these events with track points in a . Whenever the runtime tracking infrastructure matches a track point, it sends a tracking record that contains data associated with both the track point and the tracking event to the tracking service. There are three kinds of tracking record that the runtime tracking infrastructure can send: an , a , and a . Each kind of tracking record derives from the class and corresponds to one of the three kinds of track point that the runtime tracking infrastructure can match: an , a , or a . - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + During its execution, a workflow instance emits three kinds of tracking events to the runtime tracking infrastructure: activity status events, user events, and workflow status events. The runtime tracking infrastructure tries to match these events with track points in a . Whenever the runtime tracking infrastructure matches a track point, it sends a tracking record that contains data associated with both the track point and the tracking event to the tracking service. There are three kinds of tracking record that the runtime tracking infrastructure can send: an , a , and a . Each kind of tracking record derives from the class and corresponds to one of the three kinds of track point that the runtime tracking infrastructure can match: an , a , or a . + ]]> @@ -74,11 +74,11 @@ When overridden in a derived class, gets the collection of annotations associated with the track point. A that contains the annotations associated with the track point to which this corresponds. - , a or a in a . The runtime tracking infrastructure stores these annotations, and, when it matches the track point, it returns them in . - + , a or a in a . The runtime tracking infrastructure stores these annotations, and, when it matches the track point, it returns them in . + ]]> @@ -103,11 +103,11 @@ When overridden in a derived class, gets or sets the event data, if any, that is associated with the tracking event that caused the tracking record to be sent. An that represents the event data, if any, that is associated with the tracking event that caused the tracking record to be sent. - property of the derived class. For example, when a workflow instance is terminated, the runtime tracking infrastructure sends a with set to a that contains information about the reason for the termination. - + property of the derived class. For example, when a workflow instance is terminated, the runtime tracking infrastructure sends a with set to a that contains information about the reason for the termination. + ]]> @@ -132,11 +132,11 @@ When overridden in a derived class, gets or sets the time and date of the tracking event associated with the tracking record. A that indicates the date and time that the tracking event occurred. - is Coordinated Universal Time (UTC). - + is Coordinated Universal Time (UTC). + ]]> @@ -161,11 +161,11 @@ When overridden in a derived class, gets or sets a value that indicates the order of the tracking event associated with the tracking record relative to the other tracking events emitted by the workflow instance. A value that indicates the order of the tracking event relative to the other tracking events emitted by the workflow instance. - indicates the relative order of the tracking event within the workflow instance. will be unique within a workflow instance, but it is not guaranteed to be sequential. - + indicates the relative order of the tracking event within the workflow instance. will be unique within a workflow instance, but it is not guaranteed to be sequential. + ]]> diff --git a/xml/System.Workflow.Runtime.Tracking/TrackingWorkflowTerminatedEventArgs.xml b/xml/System.Workflow.Runtime.Tracking/TrackingWorkflowTerminatedEventArgs.xml index 2b4d1655734..f3d9049b229 100644 --- a/xml/System.Workflow.Runtime.Tracking/TrackingWorkflowTerminatedEventArgs.xml +++ b/xml/System.Workflow.Runtime.Tracking/TrackingWorkflowTerminatedEventArgs.xml @@ -36,7 +36,7 @@ A is generated by the runtime tracking infrastructure when a workflow instance is terminated. If the associated with a workflow instance includes a configured for a , the workflow tracking infrastructure puts the in in the that it sends to the tracking service. - A workflow instance may be terminated in one of three ways: the host may call ; a activity may be invoked from inside the workflow instance; or an unhandled exception may occur. If the workflow is terminated by the host or a activity, the runtime tracking infrastructure sets to a that has its property set to a description of the reason for the termination. If the workflow is terminated because of an unhandled exception, the runtime tracking infrastructure passes the unhandled exception in . + A workflow instance may be terminated in one of three ways: the host may call ; a activity may be invoked from inside the workflow instance; or an unhandled exception may occur. If the workflow is terminated by the host or a activity, the runtime tracking infrastructure sets to a that has its property set to a description of the reason for the termination. If the workflow is terminated because of an unhandled exception, the runtime tracking infrastructure passes the unhandled exception in . > [!NOTE] > is used only by the runtime tracking service to pass information in a . The data for a event is passed in a . @@ -70,7 +70,7 @@ ## Remarks When the workflow instance is terminated because of an unhandled exception, contains the unhandled exception. - When the workflow instance is terminated by either a host call to or by a activity, contains a that has its property set to a description of the reason for the termination. If the host terminates the workflow instance, it supplies this description in the `string` parameter to ; if the workflow instance is terminated by a , the description is supplied by . + When the workflow instance is terminated by either a host call to or by a activity, contains a that has its property set to a description of the reason for the termination. If the host terminates the workflow instance, it supplies this description in the `string` parameter to ; if the workflow instance is terminated by a , the description is supplied by . ]]> diff --git a/xml/System.Workflow.Runtime/ServicesExceptionNotHandledEventArgs.xml b/xml/System.Workflow.Runtime/ServicesExceptionNotHandledEventArgs.xml index d393323405b..8f928aff025 100644 --- a/xml/System.Workflow.Runtime/ServicesExceptionNotHandledEventArgs.xml +++ b/xml/System.Workflow.Runtime/ServicesExceptionNotHandledEventArgs.xml @@ -23,15 +23,15 @@ Provides data for the event. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - When a service that derives from the class encounters an exception that it cannot handle, it can call the method to tell the workflow runtime engine to raise the event. The service passes the of the workflow instance and the associated with this event in its call to . The workflow runtime engine encapsulates these parameters in a and raises the event. From inside of a subscriber to the event, you can read the property and the property to get the information associated with a particular event. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + When a service that derives from the class encounters an exception that it cannot handle, it can call the method to tell the workflow runtime engine to raise the event. The service passes the of the workflow instance and the associated with this event in its call to . The workflow runtime engine encapsulates these parameters in a and raises the event. From inside of a subscriber to the event, you can read the property and the property to get the information associated with a particular event. + ]]> @@ -78,11 +78,11 @@ Gets the of the workflow instance associated with the unhandled exception. The of the workflow instance associated with the unhandled exception. - is equivalent to the of the workflow instance associated with the event. - + is equivalent to the of the workflow instance associated with the event. + ]]> diff --git a/xml/System.Workflow.Runtime/WorkflowEnvironment.xml b/xml/System.Workflow.Runtime/WorkflowEnvironment.xml index ae312769817..90355ca8973 100644 --- a/xml/System.Workflow.Runtime/WorkflowEnvironment.xml +++ b/xml/System.Workflow.Runtime/WorkflowEnvironment.xml @@ -23,15 +23,15 @@ Represents the transactional environment of the workflow instance that is running on the current thread. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - The represents the transactional environment of the workflow instance that is running on the current thread. has two properties: the property, which exposes the current work batch and allows a host or a host service to participate in the current transaction by adding items to this property; and the property, which exposes the of the workflow instance currently running on this thread. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + The represents the transactional environment of the workflow instance that is running on the current thread. has two properties: the property, which exposes the current work batch and allows a host or a host service to participate in the current transaction by adding items to this property; and the property, which exposes the of the workflow instance currently running on this thread. + ]]> @@ -56,11 +56,11 @@ Gets the current work batch. The that represents the current work batch. - property allows hosts or host services to participate in the current transaction by adding pending work items to the current work batch. A host or a host service that wants to participate in the current transaction must implement the interface and use to add pending work items to . Durable services should add items to to keep the state of their data stores consistent with the state of the workflow instance. The out-of-box durable services, and , both implement this functionality. - + property allows hosts or host services to participate in the current transaction by adding pending work items to the current work batch. A host or a host service that wants to participate in the current transaction must implement the interface and use to add pending work items to . Durable services should add items to to keep the state of their data stores consistent with the state of the workflow instance. The out-of-box durable services, and , both implement this functionality. + ]]> @@ -85,11 +85,11 @@ Gets the of the workflow instance associated with the current thread. The that identifies the current workflow instance. - contains the of the workflow instance currently running in this thread. Whenever code is run from within a workflow thread, you can get the of the workflow instance through the property. For example, if your code is in a service called by an activity, will provide of the workflow instance for the calling activity. - + contains the of the workflow instance currently running in this thread. Whenever code is run from within a workflow thread, you can get the of the workflow instance through the property. For example, if your code is in a service called by an activity, will provide of the workflow instance for the calling activity. + ]]> diff --git a/xml/System.Workflow.Runtime/WorkflowInstance.xml b/xml/System.Workflow.Runtime/WorkflowInstance.xml index 5a0072e0c4c..b8d34180ce6 100644 --- a/xml/System.Workflow.Runtime/WorkflowInstance.xml +++ b/xml/System.Workflow.Runtime/WorkflowInstance.xml @@ -507,7 +507,7 @@ calls on the root activity of this workflow instance. If encounters an exception, it terminates the workflow instance by calling with the property of the exception passed as the reason for the termination. + calls on the root activity of this workflow instance. If encounters an exception, it terminates the workflow instance by calling with the property of the exception passed as the reason for the termination. ]]> @@ -582,7 +582,7 @@ ## Remarks The workflow instance is terminated in a synchronous manner. The host calls to terminate the workflow instance. The workflow runtime engine clears the in-memory workflow instance and informs the persistence service that the instance has been cleared from memory. For the , this means that all state information for that workflow instance is deleted from the database upon termination. You will not be able to reload the workflow instance from a previously stored persistence point. - After the in-memory workflow instance is cleared and the persistence service is informed of the termination, the `Terminate` method raises the event and passes `reason` in the property of a contained in the . + After the in-memory workflow instance is cleared and the persistence service is informed of the termination, the `Terminate` method raises the event and passes `reason` in the property of a contained in the . `Terminate` is different from in that while Terminate clears the in-memory workflow instance and informs the persistence service of the termination, `Abort` simply clears the in-memory workflow instance, which can then be restarted from the last persistence point. diff --git a/xml/System.Workflow.Runtime/WorkflowOwnershipException.xml b/xml/System.Workflow.Runtime/WorkflowOwnershipException.xml index c186742ddcb..f0f96b69dae 100644 --- a/xml/System.Workflow.Runtime/WorkflowOwnershipException.xml +++ b/xml/System.Workflow.Runtime/WorkflowOwnershipException.xml @@ -27,17 +27,17 @@ The exception that is thrown when the workflow runtime engine attempts to load a workflow instance that is currently loaded by another workflow runtime engine instance. Additionally, this exception is thrown when the workflow runtime engine attempts to save a workflow after the ownership timeout that was specified while loading the workflow has expired. - [!NOTE] -> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] - - The is used by persistence services which support the capability for multiple applications to access the same database. In such an environment, an instance of the workflow runtime may try to load a workflow that is already loaded by another instance of the workflow runtime engine. For example, the class throws the when this situation occurs. - - If you implement a persistence service that throws the you should provide the of the workflow instance for which the exception occurs by using an appropriate constructor for the class or setting the property before you throw the exception. - +> [!INCLUDE[DeprecatedContent](~/includes/deprecatedcontent-md.md)] + + The is used by persistence services which support the capability for multiple applications to access the same database. In such an environment, an instance of the workflow runtime may try to load a workflow that is already loaded by another instance of the workflow runtime engine. For example, the class throws the when this situation occurs. + + If you implement a persistence service that throws the you should provide the of the workflow instance for which the exception occurs by using an appropriate constructor for the class or setting the property before you throw the exception. + ]]> @@ -67,19 +67,19 @@ Initializes a new instance of the class. - property of the new instance to a system-supplied message that describes the error and takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic)| -||A system-supplied localized description.| -||An empty .| - + property of the new instance to a system-supplied message that describes the error and takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic)| +||A system-supplied localized description.| +||An empty .| + ]]> @@ -104,19 +104,19 @@ The of the workflow instance for which this exception occurred. Initializes a new instance of the class by using a specified workflow instance . - property of the workflow instance. The property of the new instance is initialized to a system-supplied message that describes the error and takes into account the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic)| -||A system-supplied localized description.| -||The of the workflow instance, specified by `instanceId`, for which this exception occurred.| - + property of the workflow instance. The property of the new instance is initialized to a system-supplied message that describes the error and takes into account the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic)| +||A system-supplied localized description.| +||The of the workflow instance, specified by `instanceId`, for which this exception occurred.| + ]]> @@ -141,19 +141,19 @@ The message that describes the error. Initializes a new instance of the class by using a specified error message. - before you throw the exception. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic).| -||The error message string.| -||An empty .| - + before you throw the exception. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic).| +||The error message string.| +||An empty .| + ]]> @@ -180,19 +180,19 @@ The message that describes the error. Initializes a new instance of the class by using a specified workflow instance and a specified error message. - property of the workflow instance. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||A null reference (`Nothing` in Visual Basic)| -||The error message string.| -||The of the workflow instance, specified by `instanceId`, for which this exception occurred.| - + property of the workflow instance. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||A null reference (`Nothing` in Visual Basic)| +||The error message string.| +||The of the workflow instance, specified by `instanceId`, for which this exception occurred.| + ]]> @@ -219,13 +219,13 @@ A that contains contextual information about the source or destination. Initializes a new instance of the WorkflowOwnershipException class with serialized data. - @@ -252,19 +252,19 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a catch block that handles the inner exception. Initializes a new instance of the class by using 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 supplied to the constructor or a null reference (Nothing in Visual Basic) if the `innerException` parameter does not supply the inner exception value to the constructor. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. If you use this constructor you should explicitly set before you throw the exception. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| -||An empty .| - + property. The property returns the same value that is supplied to the constructor or a null reference (Nothing in Visual Basic) if the `innerException` parameter does not supply the inner exception value to the constructor. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. If you use this constructor you should explicitly set before you throw the exception. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| +||An empty .| + ]]> @@ -293,21 +293,21 @@ The exception that is the cause of the current exception. If the parameter is not a null reference ( in Visual Basic), the current exception is raised in a catch block that handles the inner exception. Initializes a new instance of the class by using a specified workflow instance , 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 supplied to the constructor or a null reference (Nothing in Visual Basic) if the `innerException` parameter does not supply the inner exception value to the constructor. - - `instanceId` is equivalent to the property of the workflow instance. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. - - The following table shows the initial property values for an instance of . - -|Property|Value| -|--------------|-----------| -||The inner exception reference.| -||The error message string.| -||The of the workflow instance, specified by `instanceId`, for which this exception occurred.| - + property. The property returns the same value that is supplied to the constructor or a null reference (Nothing in Visual Basic) if the `innerException` parameter does not supply the inner exception value to the constructor. + + `instanceId` is equivalent to the property of the workflow instance. The content of the `message` parameter is intended to be understood by humans. The caller of this constructor is required to ensure that this string has been localized for the current system culture. + + The following table shows the initial property values for an instance of . + +|Property|Value| +|--------------|-----------| +||The inner exception reference.| +||The error message string.| +||The of the workflow instance, specified by `instanceId`, for which this exception occurred.| + ]]> @@ -337,13 +337,13 @@ A that contains contextual information about the source or destination. Sets the object with the of the workflow instance associated with this exception, and additional exception information. - sets a with all the exception object data targeted for serialization. During deserialization the exception object is reconstituted from the transmitted over the stream. - - For more information see XML and SOAP Serialization. - + sets a with all the exception object data targeted for serialization. During deserialization the exception object is reconstituted from the transmitted over the stream. + + For more information see XML and SOAP Serialization. + ]]> diff --git a/xml/System.Workflow.Runtime/WorkflowRuntime.xml b/xml/System.Workflow.Runtime/WorkflowRuntime.xml index c59f8489ab9..dd0bafceb6d 100644 --- a/xml/System.Workflow.Runtime/WorkflowRuntime.xml +++ b/xml/System.Workflow.Runtime/WorkflowRuntime.xml @@ -1339,7 +1339,7 @@ ## Remarks The workflow can be terminated by the host through a call to the method, by a activity, or by the workflow run-time engine when an unhandled exception occurs. The workflow run-time engine raises the event after the workflow instance is terminated, but before it is invalidated in memory. - For the event, the sender contains the and contains the and information about the reason the instance was terminated in the property. + For the event, the sender contains the and contains the and information about the reason the instance was terminated in the property. For more information about handling events, see [Handling and raising events](/dotnet/standard/events/). diff --git a/xml/System.Workflow.Runtime/WorkflowTerminatedEventArgs.xml b/xml/System.Workflow.Runtime/WorkflowTerminatedEventArgs.xml index a85d59b4df8..6aaacd44f3a 100644 --- a/xml/System.Workflow.Runtime/WorkflowTerminatedEventArgs.xml +++ b/xml/System.Workflow.Runtime/WorkflowTerminatedEventArgs.xml @@ -61,10 +61,10 @@ ## Remarks When the workflow instance is terminated because of an unhandled exception, contains the unhandled exception. - When the workflow instance is terminated by either a host call to or by a activity, contains a that has its property set to a description of the reason for the termination. If the host terminates the workflow instance, it supplies this description in the `string` parameter to . If the workflow instance is terminated by a , the description is supplied by . + When the workflow instance is terminated by either a host call to or by a activity, contains a that has its property set to a description of the reason for the termination. If the host terminates the workflow instance, it supplies this description in the `string` parameter to . If the workflow instance is terminated by a , the description is supplied by . > [!NOTE] -> Although in the case of a event that is not due to an unhandled exception, the workflow runtime engine encapsulates a description of the reason for the termination in the property of a , it does not necessarily throw this exception. +> Although in the case of a event that is not due to an unhandled exception, the workflow runtime engine encapsulates a description of the reason for the termination in the property of a , it does not necessarily throw this exception. ]]> diff --git a/xml/ns-System.Configuration.Install.xml b/xml/ns-System.Configuration.Install.xml index 445e64ef4b3..646c70e2699 100644 --- a/xml/ns-System.Configuration.Install.xml +++ b/xml/ns-System.Configuration.Install.xml @@ -5,9 +5,9 @@ property, an installer contains a collection of other installers as children. As the installer is executed, it cycles through its children and calls , , , or . For an example of an object in the collection, see . + Through the property, an installer contains a collection of other installers as children. As the installer is executed, it cycles through its children and calls , , , or . For an example of an object in the collection, see . - The property contains information about the installation. For example, information about the location of the log file for the installation, the location of the file that saves information required by the method, and the command line that was entered when the installation executable was run. For an example of an installation executable, see [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). + The property contains information about the installation. For example, information about the location of the log file for the installation, the location of the file that saves information required by the method, and the command line that was entered when the installation executable was run. For an example of an installation executable, see [Installutil.exe (Installer Tool)](/dotnet/framework/tools/installutil-exe-installer-tool). The , , , and methods are not always called on the same instance of . For example, you might use an to install and commit an application, and then release the reference to that . Later, uninstalling the application creates a new reference to an , which means that the method is called on a different instance of . For this reason, do not save the state of a computer in an installer. Instead, use an that is preserved across calls and passed into the , , , and methods. diff --git a/xml/ns-System.Data.xml b/xml/ns-System.Data.xml index 29b454cc403..2721c210c59 100644 --- a/xml/ns-System.Data.xml +++ b/xml/ns-System.Data.xml @@ -9,7 +9,7 @@ The centerpiece of the ADO.NET architecture is the class. Each can contain multiple objects, with each containing data from a single data source, such as SQL Server. - Each contains a --a collection of objects--that determines the schema of each . The property determines the type of data held by the . The and properties let you further guarantee data integrity. The property lets you construct calculated columns. + Each contains a --a collection of objects--that determines the schema of each . The property determines the type of data held by the . The and properties let you further guarantee data integrity. The property lets you construct calculated columns. If a participates in a parent/child relationship with another , the relationship is constructed by adding a to the of a object. When such a relation is added, a and a are both created automatically, depending on the parameter settings for the constructor. The guarantees that values that are contained in a column are unique. The determines what action will happen to the child row or column when a primary key value is changed or deleted. diff --git a/xml/ns-System.Device.Location.xml b/xml/ns-System.Device.Location.xml index 0c1280eb25c..0e68e9222bc 100644 --- a/xml/ns-System.Device.Location.xml +++ b/xml/ns-System.Device.Location.xml @@ -11,9 +11,9 @@ **Note** In versions of Windows prior to Windows 7, the following conditions apply: -- All objects that have constructors can be created, but the property will always have the value . +- All objects that have constructors can be created, but the property will always have the value . -- The location indicated by the property of will always be . +- The location indicated by the property of will always be . - No location events will be raised. diff --git a/xml/ns-System.Diagnostics.PerformanceData.xml b/xml/ns-System.Diagnostics.PerformanceData.xml index 007770cfc35..285abf36d10 100644 --- a/xml/ns-System.Diagnostics.PerformanceData.xml +++ b/xml/ns-System.Diagnostics.PerformanceData.xml @@ -2,241 +2,241 @@ Use the classes in this namespace to provide counter data. The counters are used to expose performance metrics to consumers such as the Performance Monitor. The namespace does not contain classes for consuming the counter data. For a complete description of the performance counters architecture, see Performance Counters. - constructor to define the counter set. Call this method for each counter set defined in the manifest. - - 2. For each counter set, call one of the methods to add the counters to the set. Call this method for each counter defined in the counter set. - - 3. Call the method to create an instance of the counter set (an instance contains the counter data). For single instance counter sets, call this method one time. For multiple instance counter sets, call this method for each instance for which you need to provide counter data (use a unique name for each instance). - - 4. Use the property to access and set the counter data for the counter. - -4. After you finish your provider, use the [LodCtr](/windows/desktop/perfctrs/adding-counter-names-and-descriptions-to-the-registry#running-the-lodctr-tool) tool to register the counters on the computer. For example, - - ```console - lodctr /m:provider.man - ``` - - The example assumes the manifest and executable file are in the current directory. - - You can use the classes in this namespace on computers that run the Windows Vista and later operating systems. - - - -## Examples - The following shows a simple manifest: - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - - The following shows a simple provider implementation for the manifest: - -```cs -using System.Diagnostics.PerformanceData; - - private static Guid providerId = new Guid("{51D1685C-35ED-45be-99FE-17261A4F27F3}"); - private static Guid typingCounterSetId = new Guid("{582803C9-AACD-45e5-8C30-571141A22092}"); - - private static CounterSet typingCounterSet; // Defines the counter set - private static CounterSetInstance typingCsInstance; // Instance of the counter set - - private static int numberOfLetterAInWord = 0; - - . . . - - // Create the 'Typing' counter set. - typingCounterSet = new CounterSet(providerId, typingCounterSetId, CounterSetInstanceType.Single); - - // Add the counters to the counter set definition. - typingCounterSet.AddCounter(1, CounterType.RawData32, "Total Word Count"); - typingCounterSet.AddCounter(2, CounterType.Delta32, "Words Typed In Interval"); - typingCounterSet.AddCounter(3, CounterType.RawData32, "A Key Pressed"); - typingCounterSet.AddCounter(4, CounterType.RawData32, "Words Containing A"); - typingCounterSet.AddCounter(5, CounterType.SampleFraction, "Percent of Words Containing A"); - typingCounterSet.AddCounter(6, CounterType.SampleBase, "Percent Base"); - - // Create an instance of the counter set (contains the counter data). - typingCsInstance = typingCounterSet.CreateCounterSetInstance("Typing Instance"); - typingCsInstance.Counters[1].Value = 0; - typingCsInstance.Counters[2].Value = 0; - typingCsInstance.Counters[3].Value = 0; - typingCsInstance.Counters[4].Value = 0; - typingCsInstance.Counters[5].Value = 0; - typingCsInstance.Counters[6].Value = 0; - - . . . - - private void Form1_FormClosing(object sender, FormClosingEventArgs e) - { - typingCounterSet.Dispose(); - } - - // Simple effort to capture letter A key press and words typed. - private void textInput_KeyDown(object sender, KeyEventArgs e) - { - Keys keyData = e.KeyData; - - switch (e.KeyData) - { - case Keys.A : + constructor to define the counter set. Call this method for each counter set defined in the manifest. + + 2. For each counter set, call one of the methods to add the counters to the set. Call this method for each counter defined in the counter set. + + 3. Call the method to create an instance of the counter set (an instance contains the counter data). For single instance counter sets, call this method one time. For multiple instance counter sets, call this method for each instance for which you need to provide counter data (use a unique name for each instance). + + 4. Use the property to access and set the counter data for the counter. + +4. After you finish your provider, use the [LodCtr](/windows/desktop/perfctrs/adding-counter-names-and-descriptions-to-the-registry#running-the-lodctr-tool) tool to register the counters on the computer. For example, + + ```console + lodctr /m:provider.man + ``` + + The example assumes the manifest and executable file are in the current directory. + + You can use the classes in this namespace on computers that run the Windows Vista and later operating systems. + + + +## Examples + The following shows a simple manifest: + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + + The following shows a simple provider implementation for the manifest: + +```cs +using System.Diagnostics.PerformanceData; + + private static Guid providerId = new Guid("{51D1685C-35ED-45be-99FE-17261A4F27F3}"); + private static Guid typingCounterSetId = new Guid("{582803C9-AACD-45e5-8C30-571141A22092}"); + + private static CounterSet typingCounterSet; // Defines the counter set + private static CounterSetInstance typingCsInstance; // Instance of the counter set + + private static int numberOfLetterAInWord = 0; + + . . . + + // Create the 'Typing' counter set. + typingCounterSet = new CounterSet(providerId, typingCounterSetId, CounterSetInstanceType.Single); + + // Add the counters to the counter set definition. + typingCounterSet.AddCounter(1, CounterType.RawData32, "Total Word Count"); + typingCounterSet.AddCounter(2, CounterType.Delta32, "Words Typed In Interval"); + typingCounterSet.AddCounter(3, CounterType.RawData32, "A Key Pressed"); + typingCounterSet.AddCounter(4, CounterType.RawData32, "Words Containing A"); + typingCounterSet.AddCounter(5, CounterType.SampleFraction, "Percent of Words Containing A"); + typingCounterSet.AddCounter(6, CounterType.SampleBase, "Percent Base"); + + // Create an instance of the counter set (contains the counter data). + typingCsInstance = typingCounterSet.CreateCounterSetInstance("Typing Instance"); + typingCsInstance.Counters[1].Value = 0; + typingCsInstance.Counters[2].Value = 0; + typingCsInstance.Counters[3].Value = 0; + typingCsInstance.Counters[4].Value = 0; + typingCsInstance.Counters[5].Value = 0; + typingCsInstance.Counters[6].Value = 0; + + . . . + + private void Form1_FormClosing(object sender, FormClosingEventArgs e) + { + typingCounterSet.Dispose(); + } + + // Simple effort to capture letter A key press and words typed. + private void textInput_KeyDown(object sender, KeyEventArgs e) + { + Keys keyData = e.KeyData; + + switch (e.KeyData) + { + case Keys.A : // In the .NET 3.5 Framework, you had to use the - // Value property to set and increment the counter - // value. Beginning with the .NET 4.0 Framework, - // the Value property is safe to use in a multi- - // threaded application. - typingCsInstance.Counters["A Key Pressed"].Value++; - numberOfLetterAInWord++; - - break; - - case Keys.Enter: - case Keys.Space: - case Keys.Tab: - - if (numberOfLetterAInWord > 0) - { - // Beginning with the .NET 4.0 Framework, you - // can use the Increment method to increment - // the counter value by 1. The Increment method - // is safe to use in a multi-threaded - // application. - typingCsInstance.Counters["Words Containing A"].Increment(); - typingCsInstance.Counters["Percent of Words Containing A"].Increment(); - numberOfLetterAInWord = 0; - } - - typingCsInstance.Counters["Percent Base"].Increment(); - typingCsInstance.Counters["Total Word Count"].Increment(); - typingCsInstance.Counters["Words Typed In Interval"].Increment(); - - break; - } - } -``` - + // Value property to set and increment the counter + // value. Beginning with the .NET 4.0 Framework, + // the Value property is safe to use in a multi- + // threaded application. + typingCsInstance.Counters["A Key Pressed"].Value++; + numberOfLetterAInWord++; + + break; + + case Keys.Enter: + case Keys.Space: + case Keys.Tab: + + if (numberOfLetterAInWord > 0) + { + // Beginning with the .NET 4.0 Framework, you + // can use the Increment method to increment + // the counter value by 1. The Increment method + // is safe to use in a multi-threaded + // application. + typingCsInstance.Counters["Words Containing A"].Increment(); + typingCsInstance.Counters["Percent of Words Containing A"].Increment(); + numberOfLetterAInWord = 0; + } + + typingCsInstance.Counters["Percent Base"].Increment(); + typingCsInstance.Counters["Total Word Count"].Increment(); + typingCsInstance.Counters["Words Typed In Interval"].Increment(); + + break; + } + } +``` + ]]> diff --git a/xml/ns-System.Drawing.Printing.xml b/xml/ns-System.Drawing.Printing.xml index 919b4cf3638..e2694aa3b89 100644 --- a/xml/ns-System.Drawing.Printing.xml +++ b/xml/ns-System.Drawing.Printing.xml @@ -7,7 +7,7 @@ ## Remarks Typically, when you print from a Windows Forms application, you create a new instance of the class, set properties, such as and , that describe how to print, and call the method to actually print the document. Calling the method raises the event, which should be handled to perform the document layout for printing. - Use the property of the object obtained from the event to specify the output to print. If you are printing a text file, use to read one line at a time from the stream and call the method to draw the line in the graphics object. For more information about this process, see the and classes. You can view an example of printing a text document in the class overview topic. + Use the property of the object obtained from the event to specify the output to print. If you are printing a text file, use to read one line at a time from the stream and call the method to draw the line in the graphics object. For more information about this process, see the and classes. You can view an example of printing a text document in the class overview topic. > [!NOTE] > The methods of the class are not supported for printing. Instead, use the methods of the class. diff --git a/xml/ns-System.Runtime.Caching.Hosting.xml b/xml/ns-System.Runtime.Caching.Hosting.xml index f4d4aff0119..426336c7034 100644 --- a/xml/ns-System.Runtime.Caching.Hosting.xml +++ b/xml/ns-System.Runtime.Caching.Hosting.xml @@ -5,9 +5,9 @@ class exposes a static property. When a .NET Framework hosting environment starts individual application domains, it can set a reference to the property. This enables the hosting environment to provide better integration with the cache. + The base class exposes a static property. When a .NET Framework hosting environment starts individual application domains, it can set a reference to the property. This enables the hosting environment to provide better integration with the cache. - In .NET Framework 4, the namespace provides interfaces that a hosting environment can use to set a reference on the property. + In .NET Framework 4, the namespace provides interfaces that a hosting environment can use to set a reference on the property. ]]> diff --git a/xml/ns-System.Speech.Recognition.SrgsGrammar.xml b/xml/ns-System.Speech.Recognition.SrgsGrammar.xml index f0df7714548..2d307d4d493 100644 --- a/xml/ns-System.Speech.Recognition.SrgsGrammar.xml +++ b/xml/ns-System.Speech.Recognition.SrgsGrammar.xml @@ -7,7 +7,7 @@ ## Remarks To create an SRGS grammar programmatically, you construct an empty instance and add instances of classes that represent SRGS elements. The , , , , , and classes represent elements defined in the SRGS specification. Some of the properties of the class represent attributes in the SRGS specification, such as , , , and . See [SRGS Grammar XML Reference](https://learn.microsoft.com/previous-versions/office/developer/speech-technologies/hh361653(v%3doffice.14)) for a reference to the elements and attributes of the SRGS specification as supported by System.Speech. - To add a grammar rule to a , use the method of the class. You can modify the text within an SRGS element using the property of a instance. + To add a grammar rule to a , use the method of the class. You can modify the text within an SRGS element using the property of a instance. With the class, you can optimize recognition of phrases in a grammar by specifying subsets of a complete phrase that will be allowed to constitute a match, and by selecting a matching mode from the enumeration.